# Arquitetura Detalhada

Diagramas detalhados da arquitetura interna da plataforma Monetarie PIX, incluindo arvores de supervisao, fluxos de requisicao e diagramas de estado dos componentes.

## Pre-requisitos

- Conhecimento basico de OTP (Elixir/Erlang supervision trees)
- Entendimento da arquitetura umbrella do Elixir
- Familiaridade com NATS JetStream e PostgreSQL

## Arvores de Supervisao

### Shared.Application

Aplicacao base com infraestrutura compartilhada por todos os servicos:

```mermaid
graph TD
    SA[Shared.Application<br/>one_for_one<br/>max_restarts: 10/60s]

    SA --> PGS[Shared.PostgrexSupervisor]
    SA --> REPO[Shared.Repo<br/>PostgreSQL Pool]
    SA --> FINCH[Finch<br/>name: Shared.Finch<br/>DICT: 10x2 conn<br/>default: 25x2 conn]
    SA --> TEL[Shared.Telemetry<br/>Metrics + 10s Poller]
    SA --> REDIS[Shared.Redis.Connection<br/>10-conn pool]
    SA --> CERT[Shared.Crypto.CertificatePool<br/>5-min refresh]
    SA --> CHAN[Shared.Bacen.ChannelRouter<br/>CPM/CSM health tracking]
    SA --> ERR[Shared.Bacen.ErrorLookup<br/>ETS cache, 10-min refresh]
    SA --> PART[Shared.PartitionManager<br/>Daily partition check + purge]
    SA --> NATS_SUP[Shared.Nats.Supervisor<br/>Condicional: NATS_ENABLED=true]

    NATS_SUP --> GNAT[Gnat.ConnectionSupervisor<br/>:monetarie_pix_nats]
    NATS_SUP --> JS[Shared.Nats.JetStream<br/>6 streams]

    subgraph Condicional
        SA -.-> SIM[Shared.Bacen.Simulator<br/>Condicional: SIMULATOR_ENABLED=true]
    end

    style SA fill:#3498db,color:#fff
    style NATS_SUP fill:#2ecc71,color:#fff
```

### DictService.Application

Servico DICT (porta 4001) — gerenciamento de chaves PIX:

```mermaid
graph TD
    DA[DictService.Application<br/>one_for_one<br/>max_restarts: 10/60s]

    DA --> DE[DictServiceWeb.Endpoint<br/>:4001]
    DA --> CID[DictService.Sync.CidSyncService<br/>6h full sync + 5min events]
    DA --> NP[DictService.Events.NatsPublisher<br/>Condicional: NATS_ENABLED=true]
    DA --> DLR[DictService.Nats.DictLookupResponder<br/>dict.lookup.request]
    DA --> DAR[DictService.Nats.DictApiResponder<br/>dict.api.request]

    style DA fill:#e74c3c,color:#fff
```

### SpiService.Application

Servico SPI (porta 4002) — processamento de pagamentos ISO 20022:

```mermaid
graph TD
    SPA[SpiService.Application<br/>rest_for_one<br/>max_restarts: 10/60s]

    SPA --> SE[SpiServiceWeb.Endpoint<br/>:4002]
    SPA --> WS[SpiService.Workers.Supervisor<br/>Condicional: NATS_ENABLED=true<br/>max_restarts: 10/60s]

    WS --> IP[InboundProcessor<br/>batch: 100, conc: 10<br/>poll: 200ms]
    WS --> OS[OutboundSender<br/>batch: 100, conc: 10<br/>poll: 200ms]
    WS --> SU[StatusUpdater<br/>batch: 100, conc: 10<br/>poll: 200ms]
    WS --> RP[ReturnProcessor<br/>batch: 100, conc: 5<br/>poll: 200ms]

    style SPA fill:#9b59b6,color:#fff
    style WS fill:#8e44ad,color:#fff
```

### SettlementService.Application

Servico Settlement / API Gateway (porta 4003):

```mermaid
graph TD
    SSA[SettlementService.Application<br/>rest_for_one<br/>max_restarts: 10/60s]

    SSA --> SSE[SettlementServiceWeb.Endpoint<br/>:4003 — API Gateway]
    SSA --> SWS[SettlementService.Workers.Supervisor<br/>Condicional: NATS_ENABLED=true<br/>max_restarts: 10/60s]
    SSA --> BC[SettlementService.Monitoring.Broadcaster<br/>WebSocket PubSub]
    SSA --> HC[SettlementService.Monitoring.HealthChecker<br/>10s services, 30s BACEN]
    SSA --> QM[SettlementService.Monitoring.QueueMonitor<br/>15s NATS lag polling]

    SWS --> SCH[Scheduler<br/>batch: 10, conc: 1<br/>poll: 5000ms]
    SWS --> FI[FileImporter<br/>batch: 10, conc: 1<br/>poll: 10000ms]
    SWS --> CEP[CoreEventProcessor<br/>batch: 50, conc: 5<br/>poll: 500ms]

    style SSA fill:#e67e22,color:#fff
    style SWS fill:#d35400,color:#fff
```

## Fluxos de Requisicao

### PIX Send (Outbound)

Fluxo completo de envio de pagamento PIX:

```mermaid
sequenceDiagram
    participant CLI as Cliente
    participant GW as Settlement<br/>Gateway :4003
    participant DB as PostgreSQL
    participant NATS as NATS JetStream
    participant SPI as SPI Service
    participant BACEN as BACEN SPI

    CLI->>GW: POST /api/v1/payments
    Note over GW: TraceContext → x-trace-id
    Note over GW: JWTAuth → verificar cookie
    Note over GW: RequirePermission → RBAC check
    Note over GW: Idempotency → verificar replay

    GW->>DB: BEGIN TRANSACTION
    GW->>DB: INSERT monetarie_spi.messages (status=PDNG)
    GW->>DB: INSERT monetarie_spi.payments
    GW->>DB: COMMIT

    GW->>NATS: monetarie.spi.transaction.created
    GW-->>CLI: HTTP 201 {status: "PDNG", e2e_id: "E..."}

    NATS->>SPI: InboundProcessor consume
    SPI->>SPI: Construir pacs.008 (ISO 20022)
    SPI->>SPI: XMLDSig RSA-SHA256
    SPI->>BACEN: POST /api/v2/spi/pix (mTLS)
    BACEN-->>SPI: pacs.002 (status report)

    SPI->>DB: UPDATE messages SET status=ACSP
    SPI->>NATS: monetarie.spi.transaction.updated

    NATS->>SPI: StatusUpdater consume
    SPI->>DB: UPDATE messages SET status=STLD
    SPI->>NATS: monetarie.spi.transaction.completed

    Note over NATS: Core Banking consome<br/>monetarie.spi.transaction.completed
```

### PIX Receive (Inbound)

Fluxo completo de recebimento de pagamento PIX:

```mermaid
sequenceDiagram
    participant BACEN as BACEN SPI
    participant SPI as SPI Service
    participant DB as PostgreSQL
    participant NATS as NATS JetStream
    participant CORE as Core Banking

    BACEN->>SPI: POST /inbound (pacs.008)
    Note over SPI: Verificar XMLDSig
    Note over SPI: Validar XSD schema

    SPI->>DB: BEGIN TRANSACTION
    SPI->>DB: INSERT monetarie_spi.messages (status=PDNG, direction=INBOUND)
    SPI->>DB: INSERT monetarie_spi.payments
    SPI->>DB: COMMIT

    SPI->>NATS: monetarie.spi.transaction.created

    NATS->>SPI: InboundProcessor consume
    SPI->>SPI: Validar debtor/creditor
    SPI->>SPI: Verificar saldo
    SPI->>DB: UPDATE messages SET status=ACSP
    SPI->>NATS: monetarie.spi.transaction.updated

    SPI->>BACEN: pacs.002 (ACSP)
    SPI->>DB: UPDATE messages SET status=STLD
    SPI->>NATS: monetarie.spi.transaction.completed

    NATS->>CORE: monetarie.spi.transaction.completed
    Note over CORE: PixHandler processa<br/>type: "transaction.completed"
```

### DICT Lookup

Fluxo de consulta de chave no diretorio DICT:

```mermaid
sequenceDiagram
    participant CLI as Cliente
    participant GW as Settlement :4003
    participant DICT as Dict Service :4001
    participant DB as PostgreSQL
    participant BACEN as BACEN DICT API

    CLI->>GW: GET /api/v1/keys/12345678901
    Note over GW: Proxy para Dict Service

    GW->>DICT: GET /api/v2/entries/12345678901
    DICT->>DB: SELECT FROM monetarie_dict.keys
    alt Chave encontrada no cache local
        DB-->>DICT: key data
        DICT-->>GW: HTTP 200 {key_type, owner, account}
    else Chave nao encontrada localmente
        DICT->>BACEN: GET /api/v2/entries/12345678901 (mTLS)
        BACEN-->>DICT: {key_type, owner, account}
        DICT->>DB: INSERT/UPDATE monetarie_dict.keys
        DICT-->>GW: HTTP 200 {key_type, owner, account}
    end

    GW-->>CLI: HTTP 200 {key_type, owner, account}
```

## Diagrama de Estado do Circuit Breaker

```mermaid
stateDiagram-v2
    [*] --> Closed

    Closed --> Open : 5 falhas consecutivas
    Open --> HalfOpen : Apos 30s cooldown
    HalfOpen --> Closed : Probe request sucesso
    HalfOpen --> Open : Probe request falha

    state Closed {
        [*] --> Normal
        Normal --> Normal : Sucesso (reset counter)
        Normal --> CountingFailures : Falha (increment)
        CountingFailures --> CountingFailures : Falha < 5
        CountingFailures --> Normal : Sucesso (reset)
    }

    state Open {
        [*] --> FailFast
        FailFast : Todas requisicoes rejeitadas
        FailFast : {:error, :circuit_open}
        FailFast --> Cooldown : Timer 30s
    }

    state HalfOpen {
        [*] --> Probing
        Probing : 1 requisicao permitida
        Probing : Demais rejeitadas
    }
```

Telemetry events emitidos:

| Transicao | Evento Telemetry | Metadata |
|-----------|-----------------|----------|
| Closed -> Open | `[:pix, :circuit_breaker, :state_change]` | `from_state: :closed, to_state: :open, failure_count: N` |
| Open -> HalfOpen | `[:pix, :circuit_breaker, :state_change]` | `from_state: :open, to_state: :half_open` |
| HalfOpen -> Closed | `[:pix, :circuit_breaker, :state_change]` | `from_state: :half_open, to_state: :closed` |
| HalfOpen -> Open | `[:pix, :circuit_breaker, :state_change]` | `from_state: :half_open, to_state: :open` |
| Requisicao aceita | `[:pix, :circuit_breaker, :request]` | `result: :ok` |
| Requisicao rejeitada | `[:pix, :circuit_breaker, :request]` | `result: :rejected` |
| Requisicao com erro | `[:pix, :circuit_breaker, :request]` | `result: :error` |

## Fluxo de Processamento do Worker

```mermaid
sequenceDiagram
    participant GS as BaseWorker<br/>GenServer
    participant JS as NATS JetStream
    participant TASK as Task.async_stream
    participant DB as PostgreSQL
    participant DLQ as DLQ Stream

    loop A cada poll_interval (adaptativo)
        GS->>JS: fetch_messages(batch_size)
        JS-->>GS: [msg1, msg2, ..., msgN]

        alt max_concurrency > 1 (paralelo)
            GS->>TASK: Task.async_stream(messages)
            loop Para cada mensagem
                TASK->>TASK: decode_message(raw)
                TASK->>TASK: set_trace_id(headers)
                TASK->>TASK: process_message(decoded)

                alt Sucesso
                    TASK->>JS: ACK
                    TASK->>TASK: telemetry :ok
                end

                alt Retry (tentativa < 5)
                    TASK->>JS: NAK (redelivery)
                    TASK->>TASK: telemetry :retry
                end

                alt Falha (tentativa >= 5)
                    TASK->>JS: ACK
                    TASK->>DLQ: publish_to_dlq (3 retries)
                    TASK->>TASK: telemetry :error
                end
            end
            TASK-->>GS: resultados
        else max_concurrency = 1 (sequencial)
            GS->>GS: process_and_ack(msg) para cada mensagem
        end

        Note over GS: Backpressure adaptativo:<br/>batch cheio → min_poll (50ms)<br/>batch vazio → max_poll (2000ms)

        GS->>GS: Emitir telemetry: batch_completed + poll
        GS->>GS: schedule_adaptive_poll(batch_count)
    end

    loop A cada 60s
        GS->>GS: Heartbeat log<br/>processed/failed/retried/uptime
    end
```

## Fluxo de Autenticacao

```mermaid
graph TD
    A[Requisicao HTTP] --> B{Cookie pix_session?}
    B -->|Nao| C{Header Authorization?}
    B -->|Sim| D[JWTAuth plug]

    C -->|Nao| Z[HTTP 401]
    C -->|Sim Bearer| E{Issuer?}

    D --> F{Token valido?}
    F -->|Nao| Z
    F -->|Sim| G{Token no blacklist?}
    G -->|Sim| Z
    G -->|Nao| H[RequirePermission plug]

    E -->|"monetarie"| D
    E -->|"monetarie-sso"| I[SsoAuth plug]
    I --> J{target_system = "pix"?}
    J -->|Nao| Z
    J -->|Sim| F

    H --> K{Permissao no ETS cache?}
    K -->|Sim + autorizado| L[HTTP 200]
    K -->|Sim + negado| M[HTTP 403]
    K -->|Miss| N[Query group_features]
    N --> O[Cachear no ETS 5min]
    O --> K

    style Z fill:#e74c3c,color:#fff
    style M fill:#e74c3c,color:#fff
    style L fill:#27ae60,color:#fff
```

## Visao Geral de Portas e Comunicacao

```mermaid
graph TB
    subgraph Internet
        CLI[Clientes]
    end

    subgraph Kubernetes Cluster
        subgraph pix namespace
            TRAEFIK[Traefik Ingress<br/>:80/:443]
            SETTLE[Settlement :4003<br/>API Gateway]
            DICT[Dict :4001]
            SPI[SPI :4002]
            ADMIN[Admin Frontend<br/>:80 nginx]
            USER[User Frontend<br/>:80 nginx]
        end
    end

    subgraph Infraestrutura
        PG[(PostgreSQL :5432<br/>10.140.241.2)]
        REDIS[(Redis :6379<br/>10.140.240.4)]
        NATS1[NATS :4222<br/>10.10.40.5]
        NATS2[NATS :4222<br/>10.10.40.7]
        NATS3[NATS :4222<br/>10.10.40.4]
    end

    subgraph BACEN
        DICT_API[DICT API<br/>:16522 mTLS]
        SPI_CPM[SPI CPM<br/>:16522 mTLS]
        SPI_CSM[SPI CSM<br/>:17522 mTLS]
    end

    CLI -->|HTTPS| TRAEFIK
    TRAEFIK --> SETTLE
    TRAEFIK --> ADMIN
    TRAEFIK --> USER

    SETTLE -->|HTTP| DICT
    SETTLE -->|HTTP| SPI

    SETTLE --> PG
    DICT --> PG
    SPI --> PG

    SETTLE --> REDIS

    SETTLE --> NATS1
    SPI --> NATS1
    DICT --> NATS1

    DICT -.->|mTLS| DICT_API
    SPI -.->|mTLS| SPI_CPM
    SPI -.->|mTLS| SPI_CSM
```

## Resultado Esperado

Ao estudar esta arquitetura detalhada, voce tera compreensao completa de:

- As 4 arvores de supervisao OTP e seus componentes
- Os fluxos de requisicao para PIX send, receive e DICT lookup
- O diagrama de estado do circuit breaker com todos os transitions
- O fluxo de processamento do BaseWorker com backpressure adaptativo
- O fluxo de autenticacao completo (JWT + SSO + RBAC + blacklist)
- A topologia de rede entre todos os componentes da plataforma