architecture

# Architecture

## Papel do servico

O Communications Service e o motor operacional de comunicacoes assincronas da plataforma.

Ele faz:

- ingestao de notificacoes via API interna
- scan de reminders
- enqueue e processamento de jobs
- retries com backoff
- dispatch de notification deliveries
- envio de push
- observabilidade tecnica

## O que fica no PocketBase

O PocketBase continua como fonte de verdade de dominio:

- `notifications`
- `notification_recipients`
- `notification_deliveries`
- `notification_preferences`
- `push_devices`
- `reminders`
- `reminder_deliveries`

## O que fica no Redis

O Redis segura apenas o estado efemero operacional:

- filas BullMQ
- locks de idempotencia
- jobs recorrentes

## Fronteira de acesso

- browser nao chama o Communications Service diretamente
- o servico e interno
- rotas administrativas exigem `Authorization: Bearer <SERVICE_AUTH_TOKEN>`
- `n8n` e outros produtores trusted devem preferir `POST /internal/notifications`

## Ingestao de notificacoes

Contrato recomendado:

- produtor chama a API interna
- o servico aplica `notification_preferences`
- cria `notifications`, `notification_recipients` e `notification_deliveries`
- enfileira imediatamente o que ja estiver elegivel

Isso reduz acoplamento com o schema do PocketBase e centraliza:

- defaults
- dedupe
- idempotencia
- fan-out
- politica de preferencia por usuario

## Intervalos padrao

- `REMINDER_SCAN_EVERY_MS = 30000`
- `NOTIFICATION_SCAN_EVERY_MS = 30000`
- `JOB_ATTEMPTS = 5`
- `JOB_BACKOFF_BASE_MS = 5000`