# Arquitetura do Sistema

Documentacao detalhada da arquitetura interna do Monetarie PIX, incluindo os 4 servicos backend, fluxo de mensagens NATS JetStream, esquemas de banco de dados, uso do Redis e arquitetura de workers.

## Pre-requisitos

- Leitura da [Introducao](./introduction.md)
- Conhecimento basico de Elixir/OTP e Phoenix Framework
- Familiaridade com arquitetura de microsservicos e mensageria

## Visao Geral

O Monetarie PIX utiliza uma arquitetura umbrella do Elixir com 4 aplicacoes OTP que compartilham o mesmo BEAM (maquina virtual Erlang). O Settlement Service atua como API Gateway na porta 4003, roteando requisicoes para os servicos DICT (porta 4001) e SPI (porta 4002) conforme necessario.

```mermaid
graph TB
    subgraph BEAM["BEAM VM (Elixir/OTP)"]
        subgraph settlement["Settlement Service :4003"]
            ROUTER[Router<br/>~200 endpoints]
            PROXY_DICT[DictProxyController]
            PROXY_SPI[SpiProxyController]
            ACCOUNTING[Accounting Context]
            MONITORING[Monitoring GenServers]
            CIRCUIT[Circuit Breaker]
        end

        subgraph dict["Dict Service :4001"]
            DICT_API[DICT API v2.10.0<br/>~92 endpoints]
            CID_SYNC[CidSyncService<br/>6h full + 5min delta]
            DICT_NATS[NatsPublisher]
        end

        subgraph spi["SPI Service :4002"]
            SPI_API[SPI API<br/>~95 endpoints]
            INBOUND[InboundProcessor]
            OUTBOUND[OutboundSender]
            STATUS[StatusUpdater]
            RETURN[ReturnProcessor]
        end

        subgraph shared["Shared (Biblioteca Comum)"]
            AUTH[Auth + JWT + MFA + RBAC]
            CRYPTO[Crypto + XMLDSig + X.509]
            BACEN_CLIENT[BACEN Client + Channel Router]
            BASE_WORKER[BaseWorker<br/>Parallel + DLQ + Backpressure]
            REPO[Ecto Repo + Schemas]
            NATS_SUP[NATS Supervisor]
            REDIS_CONN[Redis Connection Pool]
            TELEMETRY[Telemetry + Prometheus]
        end

        ROUTER --> PROXY_DICT --> DICT_API
        ROUTER --> PROXY_SPI --> SPI_API
        DICT_API --> AUTH
        SPI_API --> AUTH
        INBOUND --> BASE_WORKER
        OUTBOUND --> BASE_WORKER
        STATUS --> BASE_WORKER
        RETURN --> BASE_WORKER
    end

    PG[(PostgreSQL 16)] --- REPO
    REDIS[(Redis 7)] --- REDIS_CONN
    NATS_CLUSTER[NATS JetStream] --- NATS_SUP
    BACEN_API[BACEN API] --- BACEN_CLIENT
```

## Aplicacoes Umbrella

### Shared (Biblioteca Comum)

Biblioteca compartilhada por todos os servicos. Nao expoe endpoints HTTP.

| Modulo | Responsabilidade |
|--------|------------------|
| `Shared.Auth.JwtAuth` | Autenticacao JWT com cadeia de fallback (JWT_SECRET, GUARDIAN_SECRET_KEY, SECRET_KEY_BASE) |
| `Shared.Auth.MFA` | Autenticacao multi-fator TOTP com codigos de backup |
| `Shared.Auth.TokenBlacklist` | Revogacao de JWT via Redis (SET com TTL) |
| `Shared.Auth.SsoAuth` | Autenticacao SSO (aceita tokens Core Banking com `iss: "monetarie"`) |
| `Shared.Plugs.RequirePermission` | RBAC baseado em ETS com cache de 5 minutos |
| `Shared.Plugs.Idempotency` | Idempotencia via Redis (24h TTL, Idempotency-Key header) |
| `Shared.Plugs.TraceContext` | Tracing distribuido W3C (x-trace-id, 16 bytes hex) |
| `Shared.Crypto.XmlSigner` | Assinatura XMLDSig RSA-SHA256 com certificados ICP-Brasil |
| `Shared.Crypto.CertificatePool` | Pool de certificados com refresh a cada 5 minutos |
| `Shared.Bacen.Client` | Cliente HTTP para APIs DICT e SPI do Banco Central |
| `Shared.Bacen.ChannelRouter` | Roteamento CPM/CSM com health tracking e failover automatico |
| `Shared.Bacen.ErrorLookup` | Cache ETS de codigos de erro BACEN (refresh 10 minutos) |
| `Shared.Workers.BaseWorker` | Worker base com processamento paralelo, DLQ, backpressure adaptativo |
| `Shared.Nats.Supervisor` | Supervisao de conexoes e consumidores NATS |
| `Shared.Redis.Connection` | Pool de 10 conexoes Redis |

### Dict Service (:4001)

Implementacao do DICT (Diretorio de Identificadores de Contas Transacionais) conforme API v2.10.0 do Banco Central.

| Componente | Descricao |
|------------|-----------|
| **~92 endpoints** | CRUD de chaves PIX, claims (reivindicacoes), portabilidade, consultas |
| **CidSyncService** | GenServer para sincronizacao de CIDs — full sync a cada 6 horas + delta a cada 5 minutos |
| **NatsPublisher** | Publicacao de eventos DICT no JetStream (criacao, remocao, alteracao de chaves) |
| **Tipos de chave** | CPF, CNPJ, PHONE (telefone), EMAIL, EVP (chave aleatoria) |

### SPI Service (:4002)

Implementacao do SPI (Sistema de Pagamentos Instantaneos) com processamento de mensagens ISO 20022.

| Componente | Descricao |
|------------|-----------|
| **~95 endpoints** | Transacoes, pagamentos, saldos, extratos, historico de status |
| **InboundProcessor** | Processa mensagens recebidas (pacs.008 entrada) — batch 100, concurrency 10 |
| **OutboundSender** | Envia mensagens para o BACEN (pacs.008 saida) — batch 100, concurrency 10 |
| **StatusUpdater** | Atualiza status de transacoes (pacs.002) — batch 100, concurrency 10 |
| **ReturnProcessor** | Processa devolucoes (pacs.004) — batch 100, concurrency 5 |

### Settlement Service (:4003 — API Gateway)

Gateway principal que recebe todas as requisicoes externas e roteia para DICT e SPI conforme necessario.

| Componente | Descricao |
|------------|-----------|
| **~200 endpoints** | Gateway + liquidacao + netting + contabilidade + monitoramento + configuracao |
| **DictProxyController** | Proxy transparente para Dict Service (chaves, claims, infracoes MED 2.0) |
| **SpiProxyController** | Proxy transparente para SPI Service (transacoes, pagamentos) |
| **CoreEventProcessor** | Consome eventos Core Banking via NATS (pagamento, devolucao, chaves, saldo) |
| **Scheduler** | Agendamento de ciclos de liquidacao e importacao de arquivos |
| **Broadcaster** | WebSocket event broadcaster via PubSub (6 canais de monitoramento) |
| **HealthChecker** | Health checks a cada 10s (servicos + DB + Redis + NATS), BACEN a cada 30s |
| **QueueMonitor** | Monitoramento de lag dos consumidores NATS a cada 15s |
| **CircuitBreaker** | ETS-based, atomico — 5 falhas abre, 30s cooldown, half-open com probe unico |

## Fluxo de Mensagens NATS JetStream

O Monetarie PIX utiliza 7 streams NATS JetStream para comunicacao assincrona entre servicos.

```mermaid
graph LR
    subgraph Streams JetStream
        S1[MONETARIE_SPI<br/>monetarie.spi.><br/>7 dias]
        S2[MONETARIE_DICT<br/>monetarie.dict.><br/>7 dias]
        S3[MONETARIE_SETTLEMENT<br/>monetarie.settlement.><br/>7 dias]
        S4[MONETARIE_AUDIT<br/>monetarie.audit.><br/>90 dias]
        S5[MONETARIE_DLQ<br/>monetarie.dlq.><br/>90 dias]
        S6[MONETARIE_CORE<br/>monetarie.core.><br/>7 dias]
    end

    SPI_WORKERS[SPI Workers] -->|Publica| S1
    DICT_PUB[Dict NatsPublisher] -->|Publica| S2
    SETTLEMENT_W[Settlement Workers] -->|Publica| S3
    ALL[Todos os servicos] -->|Audit trail| S4
    BASE[BaseWorker] -->|Mensagens falhadas| S5
    CORE_BANKING[Core Banking] -->|Eventos| S6

    S1 -->|Consome| STATUS_UPDATER[StatusUpdater]
    S2 -->|Consome| CID_SYNC[CidSyncService]
    S6 -->|Consome| CORE_PROC[CoreEventProcessor]

    style S5 fill:#fee,stroke:#f66
    style S4 fill:#ffe,stroke:#fa0
```

### Subjects NATS

| Subject | Direcao | Descricao |
|---------|---------|-----------|
| `monetarie.spi.transaction.*` | PIX interno | Eventos de transacao SPI |
| `monetarie.dict.keys.*` | PIX interno | Eventos de chaves DICT |
| `monetarie.settlement.*` | PIX interno | Eventos de liquidacao |
| `monetarie.audit.*` | PIX interno | Trail de auditoria |
| `monetarie.dlq.*` | PIX interno | Dead letter queue |
| `monetarie.core.pix.payment_request` | Core --> PIX | Requisicoes de pagamento |
| `monetarie.core.pix.return_request` | Core --> PIX | Requisicoes de devolucao |
| `monetarie.core.pix.key_create` | Core --> PIX | Criacao de chaves PIX |
| `monetarie.core.pix.key_delete` | Core --> PIX | Remocao de chaves PIX |
| `monetarie.core.pix.dict_lookup` | Core --> PIX | Consulta DICT |
| `monetarie.core.pix.balance_inquiry` | Core --> PIX | Consulta de saldo |
| `dict.lookup.request` | Core <--> PIX | Consulta DICT (request/reply) |
| `dict.api.request` | Core <--> PIX | Claims/MED/infracoes (request/reply) |

::: warning IMPORTANTE
Subjects de request/reply DEVEM estar fora do escopo de streams JetStream. O stream `MONETARIE_SPI` captura `monetarie.spi.>`, entao qualquer request/reply em `monetarie.spi.*` sera interceptado pelo JetStream e corrompera as respostas. Use subjects como `dict.*` para request/reply.
:::

## Esquemas PostgreSQL

O Monetarie PIX utiliza 8 schemas PostgreSQL para separacao logica dos dados.

```mermaid
erDiagram
    monetarie_auth {
        uuid users PK
        uuid institutions PK
        uuid groups PK
        uuid user_groups PK
        uuid audit_logs PK
        uuid sessions PK
        uuid mfa_configurations PK
    }

    monetarie_dict {
        uuid pix_keys PK
        uuid claims PK
        uuid infraction_reports PK
        uuid cid_entries PK
        uuid dict_operations PK
    }

    monetarie_spi {
        uuid messages PK
        uuid payments PK
        uuid accounts PK
        uuid message_history PK
        uuid balance_history PK
        enum key_type
        enum debit_credit
        enum message_direction
    }

    monetarie_spi_ref {
        integer banks PK
        integer status_codes PK
        integer reason_codes PK
        integer message_types PK
        integer xsd_schemas PK
        integer error_codes PK
    }

    monetarie_spi_msg {
        uuid crypto_keys PK
        uuid private_keys PK
        uuid xml_messages PK
    }

    monetarie_audit {
        uuid xml_archives PK
        uuid bacen_api_validations PK
        uuid activity_log PK
        uuid login_history PK
    }

    monetarie_settlement {
        uuid netting PK
        uuid reconciliation PK
        uuid fees PK
        uuid qr_codes PK
        uuid chart_of_accounts PK
        uuid journal_entries PK
        uuid accounting_events PK
        uuid cost_centers PK
    }

    bacen_simulator {
        uuid config PK
        uuid scenarios PK
        uuid test_runs PK
        uuid exchanges PK
    }

    monetarie_auth ||--o{ monetarie_spi : "usuario cria transacao"
    monetarie_dict ||--o{ monetarie_spi : "chave identifica pagamento"
    monetarie_spi ||--o{ monetarie_settlement : "transacao gera liquidacao"
    monetarie_spi ||--o{ monetarie_audit : "mensagem gera auditoria"
```

| Schema | Tabelas | Descricao |
|--------|---------|-----------|
| `monetarie_auth` | ~10 | Usuarios, instituicoes, grupos, sessoes, MFA, logs de auditoria |
| `monetarie_dict` | ~8 | Chaves PIX, claims, infracoes MED 2.0, sincronizacao CID |
| `monetarie_spi` | ~12 | Transacoes (messages), pagamentos, contas, saldos, historico |
| `monetarie_spi_ref` | ~6 | Dados de referencia: bancos (369), codigos de status, razoes, tipos de mensagem |
| `monetarie_spi_msg` | ~3 | Chaves criptograficas, mensagens XML |
| `monetarie_audit` | ~4 | Arquivos XML, validacoes BACEN, log de atividades (particionado), historico de login (particionado) |
| `monetarie_settlement` | ~8 | Netting, reconciliacao, taxas, QR codes, contabilidade COSIF |
| `bacen_simulator` | ~24 | Configuracao, cenarios, execucoes de teste, trocas de mensagem |

::: info NOTA
As tabelas `activity_log` e `login_history` sao particionadas por mes (2026-01 a 2026-04 + DEFAULT). O `PartitionManager` GenServer cria novas particoes diariamente e purga registros expirados.
:::

## Redis

O Redis 7 e utilizado para 4 funcionalidades distintas, todas com operacoes atomicas.

| Funcionalidade | Padrao de Chave | TTL | Descricao |
|----------------|-----------------|-----|-----------|
| **Rate limiting** | `rate_limit:{ip}:{path}` | 15 min | Token bucket — 10 tentativas por 15 min por IP (login + MFA) |
| **Token blacklist** | `blacklist:{jti}` | TTL restante do JWT | Revogacao de JWT no logout |
| **Idempotencia** | `idempotency:{user_id}:{key}` | 24 horas | Cache de resposta para replay (SET NX atomico) |
| **Circuit breaker** | ETS (nao Redis) | — | Estado do circuit breaker em ETS com `:ets.update_counter` atomico |

## Arquitetura de Workers

Todos os workers NATS herdam de `Shared.Workers.BaseWorker`, que fornece:

```mermaid
graph TB
    subgraph BaseWorker
        POLL[Poll Loop<br/>poll_interval adaptativo]
        BATCH[Batch Fetch<br/>batch_size mensagens]
        PARALLEL[Task.async_stream<br/>max_concurrency]
        ACK[ACK/NAK<br/>Logger.error em falhas]
        DLQ[DLQ Publish<br/>3 retries + backoff]
        BACKPRESSURE[Backpressure<br/>min 50ms / max 2000ms]
    end

    POLL --> BATCH --> PARALLEL --> ACK
    PARALLEL -->|Falha| DLQ
    BATCH -->|Batch cheio| BACKPRESSURE -->|Reduz intervalo| POLL
    BATCH -->|Batch vazio| BACKPRESSURE -->|Aumenta intervalo| POLL

    subgraph Workers
        W1[InboundProcessor<br/>batch:100 conc:10]
        W2[OutboundSender<br/>batch:100 conc:10]
        W3[StatusUpdater<br/>batch:100 conc:10]
        W4[ReturnProcessor<br/>batch:100 conc:5]
        W5[CoreEventProcessor<br/>batch:50 conc:5]
        W6[Scheduler<br/>batch:1 conc:1]
    end

    BaseWorker --> W1
    BaseWorker --> W2
    BaseWorker --> W3
    BaseWorker --> W4
    BaseWorker --> W5
    BaseWorker --> W6
```

| Worker | batch_size | max_concurrency | poll_interval | Descricao |
|--------|-----------|-----------------|---------------|-----------|
| InboundProcessor | 100 | 10 | 200ms | Mensagens recebidas (pacs.008 entrada) |
| OutboundSender | 100 | 10 | 200ms | Mensagens para envio ao BACEN |
| StatusUpdater | 100 | 10 | 200ms | Atualizacao de status (pacs.002) |
| ReturnProcessor | 100 | 5 | 200ms | Devolucoes (pacs.004) |
| CoreEventProcessor | 50 | 5 | 500ms | Eventos do Core Banking |
| Scheduler | 1 | 1 | 60000ms | Ciclos de liquidacao |

### Resiliencia dos Workers

- **DLQ com retry**: Mensagens falhadas sao publicadas na DLQ com 3 tentativas e backoff exponencial
- **Backpressure adaptativo**: Poll interval ajustado automaticamente (batch cheio = 50ms, vazio = 2000ms)
- **Timeout**: 60 segundos por mensagem no `Task.async_stream`
- **Safe delivery count**: `Integer.parse` com fallback para headers malformados
- **Repo.transaction**: InboundProcessor e StatusUpdater usam transacoes para evitar registros orfaos
- **Telemetria**: Eventos `[:pix, :worker, :message_processed]`, `[:pix, :worker, :batch_completed]`, `[:pix, :worker, :poll]`

## Resultado Esperado

Ao final desta secao, voce tera compreensao detalhada de:

- Como os 4 servicos Elixir se comunicam dentro do BEAM
- O papel do Settlement Service como API Gateway
- O fluxo de mensagens NATS JetStream entre servicos e com o Core Banking
- A organizacao dos 8 schemas PostgreSQL
- O uso do Redis para rate limiting, blacklist, idempotencia
- A arquitetura de workers com processamento paralelo e resiliencia