# Monetarie SPB -- System Architecture & Operations Manual **Version:** 2.0 **Last Updated:** 2026-02-07 **Authors:** Monetarie Engineering **Classification:** Internal -- Confidential **ISPB:** 12345678 -- MONETARIE INSTITUICAO DE PAGAMENTO E SERVICOS LTDA --- ## Table of Contents 1. [Executive Summary](#1-executive-summary) 2. [Infrastructure Topology](#2-infrastructure-topology) 3. [Backend Services](#3-backend-services) 4. [Frontend Architecture](#4-frontend-architecture) 5. [Messaging Architecture](#5-messaging-architecture) 6. [Database Architecture](#6-database-architecture) 7. [Security Architecture](#7-security-architecture) 8. [Failure Analysis & Resilience](#8-failure-analysis--resilience) 9. [Monitoring & Observability](#9-monitoring--observability) 10. [Deployment Architecture](#10-deployment-architecture) 11. [Environment Configuration](#11-environment-configuration) --- ## 1. Executive Summary Monetarie SPB is a cloud-native integration platform for Brazil's Central Bank Payment System (Sistema de Pagamentos Brasileiro). It provides a complete, BACEN-compliant messaging gateway that connects financial institutions to the RSFN (Rede do Sistema Financeiro Nacional) network. ### Key Characteristics | Attribute | Value | |-----------|-------| | **Architecture** | Event-driven microservices | | **Backend Services** | 11 Elixir 1.17 / Phoenix 1.8.3 services | | **Frontend** | Vue 3.5.27 + Vuetify 3.11.8 + TypeScript 5.9 | | **BACEN Message Types** | 979 across 30 categories | | **External Messaging** | IBM MQ via AMQP 1.0 (5 domains) | | **Internal Messaging** | NATS JetStream (durable pub/sub) | | **Database** | PostgreSQL 16 (Cloud SQL) | | **Cache** | Redis 7.2 | | **Infrastructure** | GKE on GCP (southamerica-east1) | | **Ingress** | GCE/Traefik with Let's Encrypt TLS | | **Throughput** | 10,000+ messages/second | | **BACEN Compliance** | 979/979 message types, XMLDSig RSA-SHA256, ICP-Brasil certificates | ### Design Principles 1. **Event-Driven**: All inter-service communication flows through NATS JetStream with at-least-once delivery guarantees. 2. **Domain-Driven Design**: Each service owns its bounded context (payments, securities, forex, settlements, etc.). 3. **CQRS**: Command-Query Responsibility Segregation separates write and read paths. 4. **Circuit Breaker**: Per-domain reconnection with exponential backoff prevents cascading failures. 5. **Audit-First**: Every BACEN message and state transition is persisted for regulatory compliance (10-year retention for ICOM messages). 6. **Zero-Trust Networking**: Kubernetes NetworkPolicies restrict all inter-pod communication to explicitly allowed paths. --- ## 2. Infrastructure Topology ### 2.1 GKE Cluster Architecture ```mermaid graph TB subgraph Internet Users[End Users] BACEN_RSFN[BACEN RSFN Network] end subgraph GCP["GCP - southamerica-east1"] subgraph GKE["GKE Cluster (fluxiq-dev)"] subgraph NS_SPB["Namespace: spb"] subgraph Presentation["Presentation Tier"] FE1[frontend
replica 1] FE2[frontend
replica 2] end subgraph Gateway["Gateway Tier"] AG1[api-gateway
replica 1] AG2[api-gateway
replica 2] end subgraph Core["Core Services"] BG1[bacen-gateway
replica 1] BG2[bacen-gateway
replica 2] AS1[auth-service
replica 1] AS2[auth-service
replica 2] MP1[message-processor
replica 1] MP2[message-processor
replica 2] MP3[message-processor
replica 3] end subgraph Domain["Domain Services"] TS1[transaction-service
replica 1] TS2[transaction-service
replica 2] UM1[user-management
replica 1] UM2[user-management
replica 2] SS[securities-service] SET[settlement-service] FX[forex-service] CS[cash-service] ES[extract-service] end subgraph Infrastructure["Infrastructure"] NATS[nats
StatefulSet] IBMMQ[ibmmq
StatefulSet] REDIS[redis
StatefulSet] PGB[pgbouncer
replica 1+2] end subgraph Testing["Testing"] SIM[bacen-simulator] end end end subgraph External["External Services"] CSQL[(Cloud SQL
PostgreSQL 16)] end INGRESS[GCE Ingress
+ Let's Encrypt] end Users --> INGRESS INGRESS --> FE1 & FE2 INGRESS --> AG1 & AG2 AG1 & AG2 --> BG1 & BG2 & AS1 & AS2 & MP1 & TS1 & UM1 BG1 & BG2 --> IBMMQ IBMMQ -.->|AMQP 1.0| BACEN_RSFN BG1 & BG2 --> NATS MP1 & MP2 & MP3 --> NATS TS1 & TS2 --> NATS BG1 & BG2 --> PGB --> CSQL AS1 & AS2 --> PGB BG1 & BG2 --> REDIS style BACEN_RSFN fill:#f66,stroke:#333,color:#fff style CSQL fill:#4285F4,stroke:#333,color:#fff style NATS fill:#27AAE1,stroke:#333,color:#fff style IBMMQ fill:#054ADA,stroke:#333,color:#fff style REDIS fill:#DC382D,stroke:#333,color:#fff ``` ### 2.2 Network Topology ```mermaid graph LR subgraph External INET[Internet
Port 443] RSFN[BACEN RSFN
Port 1414+] end subgraph Ingress ING[GCE Ingress] end subgraph Frontend FE[frontend
:80] end subgraph API AG[api-gateway
:4000] end subgraph Auth AS[auth-service
:4001] end subgraph BACEN BG[bacen-gateway
:4002] end subgraph Processing MP[message-processor
:4003] end subgraph Transactions TS[transaction-service
:4005] end subgraph Users UM[user-management
:4004] end subgraph Messaging MQ[ibmmq
:1414] NT[nats
:4222] end subgraph Data PG[(PostgreSQL
:5432)] RD[(Redis
:6379)] end INET -->|HTTPS| ING ING -->|HTTP :80| FE ING -->|HTTP :4000| AG FE -.->|API calls| AG AG -->|:4001| AS AG -->|:4002| BG AG -->|:4003| MP AG -->|:4005| TS AG -->|:4004| UM BG -->|AMQP 1.0 :1414| MQ MQ <-->|mTLS| RSFN AG & BG & MP & TS & UM & AS -->|:4222| NT AG & BG & AS & TS & UM & MP -->|:5432| PG BG -->|:6379| RD ``` ### 2.3 Message Flow Topology #### Outbound Message Flow (Institution to BACEN) ```mermaid sequenceDiagram participant User participant FE as Frontend participant AG as API Gateway
(4000) participant NATS as NATS JetStream participant MP as Message Processor
(4003) participant BG as BACEN Gateway
(4002) participant SM as SignatureManager participant DM as DomainManager participant MQ as IBM MQ participant BACEN as BACEN RSFN User->>FE: Create transaction FE->>AG: POST /api/messages AG->>NATS: Publish messages.new NATS->>BG: MessageConsumer receives BG->>BG: Validate message type (979 types) BG->>NATS: Publish messages.validated NATS->>MP: SimplePipeline receives MP->>MP: BacenProcessor.process() MP->>NATS: Publish bacen.message.outbound NATS->>BG: MessageConsumer receives BG->>BG: Build ISO 20022 XML BG->>SM: Sign with XMLDSig (RSA-SHA256) SM-->>BG: Signed XML BG->>BG: Build 588-byte SecurityHeader BG->>DM: send_message(domain, xml, metadata) DM->>MQ: :amqp10_client.send_msg() MQ->>BACEN: AMQP 1.0 over mTLS BACEN-->>MQ: ACK BG->>NATS: Publish bacen.message.sent ``` #### Inbound Message Flow (BACEN to Institution) ```mermaid sequenceDiagram participant BACEN as BACEN RSFN participant MQ as IBM MQ participant DM as DomainManager participant BG as BACEN Gateway
(4002) participant SM as SignatureManager participant NATS as NATS JetStream participant TS as Transaction Service
(4005) participant MP as Message Processor
(4003) BACEN->>MQ: AMQP 1.0 message MQ->>DM: {:amqp10_msg, link_ref, msg} DM->>DM: extract_message_body() DM->>BG: MessageProcessor.receive_from_bacen() BG->>SM: verify(signed_xml) SM->>SM: Verify XMLDSig signature SM->>SM: Verify ICP-Brasil certificate chain SM-->>BG: {:ok, :valid} BG->>BG: Parse ISO 20022 XML BG->>BG: Extract message type via CodMsg BG->>NATS: Publish bacen.message.received.{type} NATS->>TS: Transaction state update NATS->>MP: Processing/routing BG->>NATS: Publish bacen.message.sent (metrics) ``` --- ## 3. Backend Services ### 3.1 Service Catalog | Service | Port | Replicas | Description | Key Modules | Dependencies | Health | |---------|------|----------|-------------|-------------|-------------|--------| | **api-gateway** | 4000 | 2 | REST entry point, request routing, SSO auth | `SsoAuth`, `AuthProxyController`, `MessagesController`, `PaymentsController`, `UsersController`, `GroupsController`, `DashboardController` | NATS, PostgreSQL, Auth Service | `/api/health` | | **auth-service** | 4001 | 2 | JWT authentication, Guardian, Azure AD OAuth | `AuthController` (login/verify/refresh), `Guardian`, `Ueberauth` | PostgreSQL, NATS | `/health` | | **bacen-gateway** | 4002 | 2 | Core BACEN integration, 979 message types, IBM MQ | `DomainManager`, `MessageProcessor`, `MessageRegistry`, `SignatureManager`, `ErrorHandler`, `DeadLetterQueue`, `Metrics`, `MQConsumer`, `MessageRouter`, `HandlerFactory` | IBM MQ, NATS, PostgreSQL, Redis | `/health`, `/ready` | | **message-processor** | 4003 | 2-3 | High-throughput NATS message pipeline | `SimplePipeline` (GenServer), `BacenProcessor` | NATS, BACEN Gateway (HTTP) | `/health`, `/ready` | | **user-management** | 4004 | 2 | RBAC, users, groups, permissions, entities | `UsersController`, `GroupsController`, `PermissionsController`, `EntitiesController` | PostgreSQL, NATS | `/health`, `/ready` | | **transaction-service** | 4005 | 2 | STR/LPI/TED/DOC lifecycle, payment processing | `PaymentsController` (CRUD + status), `GenStateMachine` | PostgreSQL, NATS | `/health`, `/ready` | | **securities-service** | 4006 | 1 | SEL/CTP/RDC/TES securities operations | `SecuritiesController`, `CustodyController`, `FixedIncomeController`, `OtherController` | PostgreSQL, NATS | `/health`, `/ready` | | **settlement-service** | 4007 | 1 | LDL net position calculation, batch settlement | `SettlementController` (CRUD + net_position + batch) | PostgreSQL, NATS | `/health`, `/ready` | | **forex-service** | 4008 | 1 | CAM currency exchange operations | `ForexController` (CRUD + by_currency + date_range) | PostgreSQL, NATS | `/health`, `/ready` | | **cash-service** | 4009 | 1 | CIR cash operations, vault management | `CashController` (CRUD + vault_balance + vault_operations) | PostgreSQL, NATS | `/health`, `/ready` | | **extract-service** | 4010 | 1 | Data extraction, conciliation reports | `ExtractController` (transactions + conciliation) | PostgreSQL, NATS | `/health`, `/ready` | ### 3.2 API Gateway (Port 4000) -- Detail The API Gateway is the single entry point for all client requests. It implements the SsoAuth plug for SSO authentication and proxies requests to backend services. **Route Table:** | Method | Path | Controller | Description | |--------|------|------------|-------------| | GET | `/metrics` | PrometheusMetricsController | Prometheus scrape endpoint | | GET | `/api/health` | HealthController | Health check | | GET | `/api/dashboard/stats` | DashboardController | Dashboard statistics | | GET | `/api/dashboard/recent-activity` | DashboardController | Recent activity feed | | POST | `/api/auth/login` | AuthProxyController | Login (proxied to Auth Service) | | POST | `/api/auth/verify` | AuthProxyController | Token verification | | GET/POST | `/api/messages` | MessagesController | Message CRUD | | GET | `/api/messages/:id` | MessagesController | Single message | | GET/POST | `/api/payments` | PaymentsController | Payment CRUD | | GET | `/api/payments/:id` | PaymentsController | Single payment | | GET/POST | `/api/transactions` | PaymentsController | Transaction alias | | CRUD | `/api/users` | UsersController | User management | | CRUD | `/api/groups` | GroupsController | Group management | ### 3.3 Auth Service (Port 4001) -- Detail Handles JWT authentication via Guardian library with SSO code exchange support. | Method | Path | Description | |--------|------|-------------| | POST | `/api/auth/login` | Authenticate with email/password | | POST | `/api/auth/verify` | Verify JWT token validity | | POST | `/api/auth/refresh` | Refresh expired JWT token | Authentication supports: - **JWT Guardian**: Access + Refresh token pair - **Azure AD OAuth**: Enterprise SSO via Ueberauth - **SSO Code Exchange**: Cross-system authentication via `MONETARIE_SSO_SECRET` ### 3.4 BACEN Gateway (Port 4002) -- Detail The heart of the SPB system. Manages all communication with BACEN via 5 independent IBM MQ domain connections. **Supervisor Tree:** ``` BacenGateway.Supervisor (one_for_one) |-- BacenGateway.Repo (Ecto) |-- BacenGateway.Cache (Redix) |-- Phoenix.PubSub |-- Gnat.ConnectionSupervisor (NATS) |-- BacenGateway.Metrics (ETS) |-- BacenGateway.DeadLetterQueue (GenServer + Ecto) |-- BacenGateway.Security.SignatureManager (GenServer) |-- BacenGateway.MQ.DomainManager (GenServer) |-- BacenGateway.MessageProcessor (GenServer) |-- BacenGateway.Consumers.MessageConsumer |-- BacenGatewayWeb.Endpoint (Phoenix) ``` **Message Categories (30 categories, 979 types):** | Category | Name | Count | Handler | Domain | |----------|------|-------|---------|--------| | CAM | Cambio | 111 | CAMHandler | MES03 | | CIR | Meio Circulante | 100 | CIRHandler | MES03 | | CTP | Credito Titulos Publicos | 99 | CTPHandler | SPB02 | | SEL | SELIC | 92 | SELHandler | SPB02 | | STR | Transferencia Reservas | 77 | STRHandler | SPB01 | | LDL | Liquidacao Operacoes | 71 | LDLHandler | SPB02 | | DDA | Debito Direto Autorizado | 55 | DDAHandler | MES03 | | TES | Tesouro | 49 | TESHandler | MES03 | | LFL | Linhas Financeiras Liquidez | 46 | LFLHandler | MES03 | | PAG | Pagamentos | 38 | PAGHandler | MES03 | | GEN | Geral | 26 | GENHandler | SPB01 | | RDC | Registro Debitos/Creditos | 25 | RDCHandler | MES03 | | CCS | Compensacao Cheques | 22 | CCSHandler | MES03 | | BMC | Boleto Mercado Capitais | 22 | BMCHandler | MES03 | | RCO | Recolhimento Compulsorio | 18 | RCOHandler | MES03 | | LTR | Letra do Tesouro | 17 | LTRHandler | MES03 | | LPI | Liquidez Pagtos Instantaneos | 15 | LPIHandler | SPB01 | | COR | Correspondente | 14 | CORHandler | MES03 | | CCR | Conta Custodia Renda | 12 | CCRHandler | MES03 | | SLB | Solicitacao Bloqueio | 10 | SLBHandler | MES03 | | SME | Mensagens Eletronicas | 8 | SMEHandler | MES03 | | ECR | Extrato Conta Reservas | 8 | ECRHandler | MES03 | | SML | Mensagens Liquidacao | 7 | SMLHandler | MES03 | | SLC | Liquidacao Cheques | 7 | SLCHandler | MES03 | | LEI | Leilao Eletronico Informal | 7 | LEIHandler | MES03 | | CMP | Liquidacao COMPE | 7 | CMPHandler | MES03 | | CSD | Custodia Documentos | 6 | CSDHandler | MES03 | | PTX | Protocolo Transmissao | 4 | PTXHandler | MES03 | | CQL | Controle Qualidade Lotes | 4 | CQLHandler | MES03 | | SRC | Registro Contratos | 2 | SRCHandler | MES03 | | | **TOTAL** | **979** | | | ### 3.5 Message Processor (Port 4003) -- Detail The Message Processor implements a simplified high-throughput pipeline using a GenServer (`SimplePipeline`) that subscribes to NATS topics and forwards processed messages to the BACEN Gateway. **Pipeline Architecture:** ``` SimplePipeline (GenServer) |-- Subscribes to: payments.created, messages.received |-- Processes via: BacenProcessor.process() |-- Forwards to: BACEN Gateway (HTTP POST) |-- Errors to: messages.failed (NATS DLQ) ``` **Key Characteristics:** - NATS subscription-based (not Broadway in active deployment) - Auto-reconnect to NATS with 5-second retry interval - Error messages published to `messages.failed` topic - Processing statistics logged every 100 messages ### 3.6 -- 3.11 Domain Services **Transaction Service (4005):** Manages the full lifecycle of STR, LPI, TED, and DOC transactions. Implements a state machine (pending -> processing -> completed/failed/cancelled). Exposes payment CRUD and status update endpoints. **Securities Service (4006):** Handles securities operations across 4 sub-domains: SEL (SELIC operations), CTP (public title custody), RDC (fixed income), and TES (treasury operations). Each sub-domain has its own controller and resource routes. **Settlement Service (4007):** Manages LDL (Liquidacao Diferida Liquida) settlement windows. Provides net position calculation per ISPB per date, and batch settlement processing. Critical for end-of-day settlement cycles. **Forex Service (4008):** Processes CAM (Cambio) currency exchange operations. Supports currency-specific queries and date range filtering for exchange rate history. **Cash Service (4009):** Manages CIR (Meio Circulante) cash operations. Includes vault balance tracking and vault operation history for physical cash management. **Extract Service (4010):** Generates data extractions and conciliation reports. Used for regulatory reporting (Circular 3290, SEL 1612) and internal reconciliation. **User Management (4004):** Complete RBAC system with users, groups, permissions, and entity management. Supports user activation/deactivation, role assignment, group membership, and permission seeding. Manages financial institution entities (ISPB registration). --- ## 4. Frontend Architecture ### 4.1 Technology Stack | Technology | Version | Purpose | |------------|---------|---------| | Vue | 3.5.27 | Reactive UI framework | | TypeScript | 5.9.3 | Type-safe JavaScript | | Vuetify | 3.11.8 | Material Design component library | | Pinia | 3.0.4 | State management | | Vue Router | 4.6.4 | Client-side routing | | vue-i18n | 11.2.8 | Internationalization | | Axios | 1.13.4 | HTTP client | | Vite | 7.3.1 | Build tool | | date-fns | 4.1.0 | Date utilities | **Build & Quality:** - `vue-tsc --build` for strict TypeScript checking - `oxlint` + `eslint` for linting - `prettier` for formatting - `vitest` for unit testing - `nginx` for production serving (port 80, non-root UID 101) ### 4.2 Route Map (106 Routes) #### Admin Portal (41 routes) | Group | Route | Name | View | |-------|-------|------|------| | **Dashboard** | `/admin/dashboard` | admin-dashboard | DashboardView | | **Security** | `/admin/users` | users | UsersView | | | `/admin/groups` | groups | GroupsView | | | `/admin/permissions` | permissions | PermissionsView | | | `/admin/permission-tree` | permission-tree | PermissionTreeView | | | `/admin/password-policy` | password-policy | PasswordPolicyView | | | `/admin/password-resets` | password-resets | PasswordResetsView | | | `/admin/password-history` | password-history | PasswordHistoryView | | | `/admin/session-management` | session-management | SessionManagementView | | | `/admin/mfa-config` | mfa-config | MFAConfigView | | | `/admin/roles` | roles | RoleEditorView | | | `/admin/group-sync` | group-sync | GroupSyncView | | | `/admin/sso-config` | sso-config | SSOConfigView | | | `/admin/user-bulk-import` | user-bulk-import | UserBulkImportView | | | `/admin/emergency-access` | emergency-access | EmergencyAccessView | | | `/admin/audit-trail` | audit-trail | AuditTrailView | | **Registration** | `/admin/entities` | entities | EntitiesView | | | `/admin/messages` | admin-messages | MessagesView | | | `/admin/registration/holidays` | holidays | HolidaysView | | | `/admin/registration/branches` | branches | BranchesView | | | `/admin/registration/tariffs` | tariffs-config | TariffsConfigView | | | `/admin/registration/domains` | domains | DomainsView | | | `/admin/registration/automation` | automation | AutomationRulesView | | | `/admin/registration/blocking` | blocking | MessageBlockingView | | | `/admin/registration/routing` | routing | RoutingRulesView | | | `/admin/registration/sanctions` | sanctions | SanctionsView | | **Configuration** | `/admin/settings` | admin-settings | SettingsView | | | `/admin/system-date` | system-date | SystemDateView | | **Operations** | `/admin/transactions` | admin-transactions | TransactionsView | | | `/admin/reports` | admin-reports | ReportsView | | | `/admin/operations` | admin-operations | OperationsMonitorView | | **Infrastructure** | `/admin/company` | company | CompanyView | | | `/admin/branch-management` | branch-management | BranchManagementView | | | `/admin/queues` | queues | QueueManagementView | | | `/admin/integrations` | integrations | IntegrationSystemsView | | | `/admin/certificates` | certificates | CertificateManagementView | | | `/admin/certificate-authority` | certificate-authority | CertificateAuthorityView | | | `/admin/webhooks` | webhooks | WebhookConfigView | | **Monitoring** | `/admin/connected-users` | connected-users | ConnectedUsersView | | | `/admin/pending-operations` | pending-operations | PendingOperationsView | | | `/admin/health` | system-health | SystemHealthView | | **Compliance** | `/admin/compliance` | compliance | ComplianceExportsView | | | `/admin/audit-reports` | audit-reports | AuditReportView | | | `/admin/sla-config` | sla-config | SLAConfigView | | | `/admin/licenses` | licenses | LicenseManagementView | | **Continuity** | `/admin/dr-plan` | dr-plan | DisasterRecoveryView | | | `/admin/backup-restore` | backup-restore | BackupRestoreView | | | `/admin/retention` | retention | RetentionPolicyView | #### Operator Portal (55 routes) | Group | Route | Name | View | |-------|-------|------|------| | **Dashboard** | `/operator/dashboard` | operator-dashboard | DashboardView | | **Operations** | `/operator/reqgen` | generic-request | GenericRequestView | | | `/operator/payments` | payments | PaymentsView | | | `/operator/messages` | messages | MessagesView | | | `/operator/bacen-messages` | bacen-messages | BacenMessagesView | | **Monitoring** | `/operator/operations` | operator-operations | OperationsMonitorView | | | `/operator/integration` | integration | IntegrationMonitorView | | | `/operator/vistos` | vistos | VistosMonitorView | | **Tariffs** | `/operator/tariffs` | tariff-monitor | TariffMonitorView | | | `/operator/tariffs-interbank` | tariffs-interbank | InterbankTariffView | | **Alerts** | `/operator/alerts/messages` | alert-messages | MessageAlertsView | | | `/operator/alerts/returns` | alert-returns | ReturnAlertsView | | | `/operator/alerts/tracking` | alert-tracking | TrackingAlertsView | | | `/operator/alerts/notices` | notices | NoticeboardView | | **Monitors** | `/operator/duplicates` | duplicates | DuplicateMonitorView | | | `/operator/timeouts` | timeouts | TimeoutMonitorView | | | `/operator/not-processed` | not-processed | NotProcessedView | | **Accounting** | `/operator/accounting/chart` | accounting-chart | ChartOfAccountsView | | | `/operator/accounting/cost-centers` | accounting-cost-centers | CostCentersView | | | `/operator/accounting/events` | accounting-events | AccountingEventsView | | | `/operator/accounting/monitor` | accounting-monitor | AccountingMonitorView | | | `/operator/accounting/reconciliation` | accounting-reconciliation | ReconciliationView | | | `/operator/accounting/reports` | accounting-reports | AccountingReportsView | | **Status** | `/operator/balances` | balances | BalanceDashboardView | | | `/operator/entity-status` | entity-status | ExternalEntityStatusView | | | `/operator/schedule` | schedule | ScheduleGridView | | **Reports** | `/operator/reports` | operator-reports | ReportsView | | **Exports** | `/operator/exports` | exports | ExportsView | | **Historical** | `/operator/historical` | historical | HistoricalQueryView | | **Configuration** | `/operator/alcadas` | alcadas | AlcadaConfigView | | | `/operator/transactions` | transactions | TransactionsView | | **Message Config** | `/operator/config/message-perms` | message-perms | MessagePermissionsView | | | `/operator/config/auto-split` | auto-split | AutoSplitConfigView | | | `/operator/config/send-automation` | send-automation | SendAutomationView | | | `/operator/config/message-blocking` | config-message-blocking | MessageBlockingConfigView | | | `/operator/config/r0-routing` | r0-routing | R0RoutingView | | | `/operator/config/clearings` | clearing-config | ClearingConfigView | | | `/operator/config/message-groups` | message-groups | MessageGroupEditorView | | | `/operator/config/domain-registry` | domain-registry | DomainRegistryView | | | `/operator/config/cip-institutions` | cip-institutions | CIPInstitutionsView | | **Tools** | `/operator/tools/xml-viewer` | xml-viewer | XMLViewerView | | | `/operator/tools/message-search` | message-search | MessageSearchView | | | `/operator/tools/message-trace` | message-trace | MessageTraceView | | | `/operator/tools/queue-monitoring` | queue-monitoring | QueueMonitoringView | | | `/operator/tools/settlements` | settlement-monitor | SettlementMonitorView | | | `/operator/tools/contingency` | contingency | ContingencyView | | | `/operator/tools/error-codes` | error-codes | ErrorCodeBrowserView | | | `/operator/tools/archive-search` | archive-search | ArchiveSearchView | | | `/operator/tools/performance` | performance-analytics | PerformanceAnalyticsView | #### Standalone Routes (10 routes) | Route | Name | View | |-------|------|------| | `/login` | login | LoginView | | `/profile` | profile | ProfileView | | `/settings` | settings | SettingsView | | `/help` | help | HelpView | | `/knowledge-base` | knowledge-base | KnowledgeBaseView | | `/api-docs` | api-docs | APIDocsView | | `/mobile` | mobile-operator | MobileOperatorView | | `/:pathMatch(.*)*` | not-found | NotFoundView | | `/` | (redirect) | Redirects to /login | | `/admin` | (redirect) | Redirects to /admin/dashboard | ### 4.3 Authentication Flow ```mermaid sequenceDiagram participant User participant FE as Frontend (Vue) participant LS as localStorage participant AG as API Gateway participant AS as Auth Service alt SSO Login (from Core Backoffice) User->>FE: Navigate with ?sso_code=xxx FE->>FE: handleSSOCallback() FE->>AG: POST /api/auth/verify {sso_code} AG->>AS: Verify SSO code via MONETARIE_SSO_SECRET AS-->>AG: {token, user, role} AG-->>FE: JWT token + user data FE->>LS: Store token + user FE->>FE: Redirect to /admin/dashboard end alt Direct Login User->>FE: Enter email + password FE->>AG: POST /api/auth/login AG->>AS: Forward credentials AS->>AS: Validate via Guardian AS-->>AG: {token, refresh_token, user} AG-->>FE: JWT tokens FE->>LS: Store tokens end alt Authenticated Request FE->>FE: Axios interceptor adds Bearer token FE->>AG: GET /api/messages (Authorization: Bearer xxx) AG->>AG: SsoAuth plug validates JWT AG->>BG: Forward to BACEN Gateway BG-->>AG: Response AG-->>FE: JSON response end alt Token Expired FE->>AG: Request with expired token AG-->>FE: 401 Unauthorized FE->>FE: Auto-redirect to /login end ``` **Role-Based Route Guards:** | Role | Access | |------|--------| | `super_admin` | All admin + operator routes | | `admin` | All admin + operator routes | | `operator` | Operator routes only (redirected from admin routes to `/operator/dashboard`) | ### 4.4 Pinia Stores | Store | File | State | Actions | |-------|------|-------|---------| | **auth** | `stores/auth.ts` | `token`, `user`, `role`, `isAuthenticated` | `login()`, `logout()`, `restoreSession()`, `verifyToken()` | | **entities** | `stores/entities.ts` | `entities[]`, `loading`, `error` | `fetchEntities()`, `createEntity()`, `updateEntity()`, `deleteEntity()` | | **ui** | `stores/ui.ts` | `sidebarOpen`, `theme`, `notifications[]` | `setSidebarOpen()`, `toggleTheme()`, `addNotification()` | ### 4.5 Sidebar Navigation Structure #### Admin Sidebar (9 groups, 49 items) ``` Dashboard Seguranca (Security) |-- Usuarios (16 items) |-- Grupos |-- Permissoes |-- Arvore de Permissoes |-- Politica de Senhas |-- Reset de Senhas |-- Historico de Senhas |-- Sessoes Ativas |-- Autenticacao MFA |-- Roles Personalizados |-- Sincronizacao AD |-- SSO / SAML |-- Importacao em Massa |-- Acesso Emergencial |-- Trilha de Auditoria Cadastro (Registration) |-- Entidades (9 items) |-- Mensagens |-- Feriados |-- Filiais |-- Tarifas |-- Dominios |-- Automacao |-- Bloqueio |-- Roteamento |-- Sancoes Configuracao (Configuration) |-- Configuracoes (2 items) |-- Data do Sistema Operacoes (Operations) |-- Transacoes (2 items) |-- Relatorios Infraestrutura (Infrastructure) |-- Empresa (7 items) |-- Gestao de Filiais |-- Filas / Streams |-- Sistemas de Integracao |-- Certificados |-- Autoridade Certificadora |-- Webhooks Monitoramento (Monitoring) |-- Usuarios Conectados (3 items) |-- Operacoes Pendentes |-- Saude do Sistema Compliance |-- Exportacoes (4 items) |-- Relatorios de Auditoria |-- SLA / Disponibilidade |-- Licencas Continuidade (Continuity) |-- Plano de DR (3 items) |-- Backup e Restauracao |-- Retencao de Dados ``` #### Operator Sidebar (14 groups, 57 items) ``` Dashboard Operacoes (Operations) |-- Requisicao Generica (4 items) |-- Pagamentos |-- Mensagens |-- Mensagens BACEN Monitoramento (Monitoring) |-- Monitor de Operacoes (3 items) |-- Monitor de Integracao |-- Monitor de Vistos Tarifas (Tariffs) |-- Monitor de Tarifas (2 items) |-- Tarifas Interbancarias Alertas (Alerts) |-- Alertas de Mensagem (4 items) |-- Alertas de Devolucao |-- Rastreamento |-- Avisos Monitores (Monitors) |-- Duplicatas (3 items) |-- Timeouts |-- Nao Processadas Contabilidade (Accounting) |-- Plano de Contas (6 items) |-- Centros de Custo |-- Eventos Contabeis |-- Monitor Contabil |-- Conciliacao |-- Relatorios Contabeis Status |-- Saldos (3 items) |-- Entidades Externas |-- Grade Horaria Relatorios (Reports) Exportacoes (Exports) |-- Circular 3290 (5 items) |-- Planilha TED |-- Exp. Movimento |-- SEL 1612 |-- PAG x STR Consulta Historica (Historical Query) Configuracao (Configuration) |-- Alcadas (2 items) |-- Transacoes Config. Mensagens (Message Config) |-- Permissoes Mensagens (9 items) |-- Desdobro Automatico |-- Automacao de Envio |-- Bloqueio Mensagens |-- Roteamento R0 |-- Clearings |-- Grupos de Mensagem |-- Registro de Dominios |-- Instituicoes CIP Ferramentas (Tools) |-- Visualizador XML (9 items) |-- Busca Avancada |-- Rastreamento |-- Monitor de Filas |-- Monitor Liquidacao |-- Contingencia |-- Codigos de Erro |-- Arquivo Historico |-- Analise de Performance ``` --- ## 5. Messaging Architecture ### 5.1 NATS JetStream Topics | Topic | Publisher | Subscriber | Purpose | |-------|-----------|------------|---------| | `messages.new` | API Gateway | BACEN Gateway (MessageConsumer) | New message submission from frontend | | `messages.validated` | BACEN Gateway | Message Processor | Message passed validation, ready for processing | | `messages.sent` | BACEN Gateway | Transaction Service, Monitoring | MQ send confirmed by IBM MQ | | `messages.confirmed` | BACEN Gateway (inbound) | Transaction Service | BACEN acknowledgment received | | `messages.failed` | Message Processor, Various | Transaction Service, DLQ | Processing failure notification | | `messages.received` | BACEN Gateway (inbound) | Message Processor | Incoming BACEN messages (generic) | | `payments.created` | Transaction Service | Message Processor | New payment request for BACEN submission | | `bacen.message.outbound` | Message Processor | BACEN Gateway (MessageConsumer) | Processed message ready for MQ transmission | | `bacen.message.sent` | BACEN Gateway | Monitoring | Outbound message successfully sent to MQ | | `bacen.message.failed` | BACEN Gateway | Monitoring, ErrorHandler | Outbound message failed to send | | `bacen.message.received.{type}` | BACEN Gateway | Transaction Service, Various | Inbound message by type (e.g., `bacen.message.received.STR0001`) | | `bacen.dlq.added` | DeadLetterQueue | Monitoring | New entry added to dead letter queue | | `bacen.metrics.*` | Metrics (ETS) | Monitoring | Periodic metrics broadcast | **JetStream Configuration:** | Parameter | Value | |-----------|-------| | Store Directory | `/data/jetstream` | | Max Memory | 2 GiB | | Max File Storage | 50 GiB | | Max Connections | 10,000 | | Max Payload | 8 MiB | | Ping Interval | 120s | | Write Deadline | 10s | | Retention | 7-30 days (topic-dependent) | ### 5.2 IBM MQ Domains (5 Domains) All BACEN communication flows through 5 independent IBM MQ Queue Manager connections, each with dedicated send/receive queues and priority levels per BACEN Manual de Redes v9.3. | Domain | QM Name | Port | Channel | Priority | Message Types | Send Queue | Receive Queue | |--------|---------|------|---------|----------|---------------|------------|---------------| | **SPB01** | QM.12345678.01 | 1414 | C12345678.00038166.1 | Platina (highest) | STR, LPI, GEN | QL.REQ.00038166.12345678.01 | QL.RSP.00038166.12345678.01 | | **SPB02** | QM.12345678.05 | 15422 | C12345678.00038166.2 | Ouro (high) | LDL, SEL, CTP, CIP | QL.REQ.00038166.12345678.02 | QL.RSP.00038166.12345678.02 | | **MES01** | QM.12345678.02 | 12422 | C12345678.00038166.3 | Platina (reserved) | Reserved/overflow | QL.REQ.00038166.12345678.03 | QL.RSP.00038166.12345678.03 | | **MES02** | QM.12345678.03 | 13422 | C12345678.00038166.4 | Prata (medium) | General messages | QL.REQ.00038166.12345678.04 | QL.RSP.00038166.12345678.04 | | **MES03** | QM.12345678.04 | 14422 | C12345678.00038166.5 | Bronze (standard) | CAM, CIR, DDA, PAG, TES, all others | QL.REQ.00038166.12345678.05 | QL.RSP.00038166.12345678.05 | **Domain Routing Logic (MessageProcessor.route_to_domain/1):** ```elixir STR* | LPI* -> :spb01 # Real-time gross settlement LDL* | SEL* -> :spb02 # Securities and deferred settlement * -> :mes03 # All other message types ``` ### 5.3 Queue Naming Convention Per BACEN Manual de Redes v9.3: | Queue Type | Pattern | Example | |------------|---------|---------| | **Send (outbound)** | `QL.REQ.{ISPB_BACEN}.{ISPB_LOCAL}.{seq}` | `QL.REQ.00038166.12345678.01` | | **Receive (inbound)** | `QL.RSP.{ISPB_BACEN}.{ISPB_LOCAL}.{seq}` | `QL.RSP.00038166.12345678.01` | | **Retry Send** | `QR.REQ.{ISPB_BACEN}.{ISPB_LOCAL}.{seq}` | `QR.REQ.00038166.12345678.01` | | **Retry Receive** | `QR.RSP.{ISPB_LOCAL}.{ISPB_BACEN}.{seq}` | `QR.RSP.12345678.00038166.01` | | **Dead Letter** | `QL.DLQ.{ISPB_LOCAL}` | `QL.DLQ.12345678` | Where: - `ISPB_LOCAL` = 12345678 (Monetarie) - `ISPB_BACEN` = 00038166 (Central Bank) - `seq` = Domain sequence number (01-05) **Queue Properties:** | Property | Value | |----------|-------| | Max Depth | 1,000,000 messages | | Max Message Length | 4,194,304 bytes (4 MiB) | | Default Persistence | YES (persistent) | | Channel Cipher | ECDHE_RSA_AES_256_GCM_SHA384 | | SSL Client Auth | REQUIRED | | AMQP 1.0 Service | ENABLED | --- ## 6. Database Architecture ### 6.1 Schema Overview The database is PostgreSQL 16 hosted on Google Cloud SQL (`fluxiq-pg-dev`), accessed via Cloud SQL Proxy sidecars on all backend pods. **SQL Migrations (8 files):** | Migration | Description | |-----------|-------------| | `001_security_schema.sql` | Users, roles, permissions, sessions, API keys | | `002_crypto_schema.sql` | Certificates, keys, XMLDSig audit | | `003_core_banking_schema.sql` | Transactions, payments, settlements, institutions | | `004_add_performance_indexes.sql` | Composite indexes for query optimization | | `005_reference_tables.sql` | BACEN reference data, error codes, message catalog | | `alter_existing_tables.sql` | Schema migration patches | | `comprehensive_bacen_schema.sql` | Full BACEN message schema (979 types) | | `modern_schema.sql` | Updated schema with JSONB and partitioning | **Ecto Migrations (6 files):** | Migration | Description | |-----------|-------------| | `20260130_create_dlq_entries` | Dead letter queue entries table | | `20260201_create_bacen_error_codes` | BACEN error code reference (5,306+ codes) | | `20260201_create_bacen_messages` | Core BACEN message storage | | `20260202_add_bacen_message_fields` | Additional message fields (direction, ISPB, correlation) | | `20260202_create_financial_institutions` | Financial institution registry | | `20260205_create_message_templates` | Message templates for 979 types | ### 6.2 Key Tables | Table | Schema/Service | Key Fields | Description | |-------|---------------|------------|-------------| | `bacen_messages` | BACEN Gateway | `id` (UUID), `message_type`, `state`, `category`, `content`, `direction`, `sender_ispb`, `receiver_ispb`, `correlation_id`, `retry_count`, `last_error_code`, `metadata` (JSONB) | Core message store for all 979 BACEN types | | `financial_institutions` | BACEN Gateway | `id`, `ispb`, `name`, `type`, `status` | Registry of all financial institutions | | `dlq_entries` | BACEN Gateway | `id`, `error` (map), `error_code`, `context` (map), `retry_attempts`, `message_type`, `message_data` (map), `processed`, `processed_at` | Dead letter queue for failed messages | | `bacen_error_codes` | BACEN Gateway | `code`, `message`, `severity`, `retryable`, `category` | 5,306+ documented BACEN error codes | | `message_templates` | BACEN Gateway | `message_type`, `template_xml`, `schema_version` | XML templates for each message type | | `users` | Auth/User Mgmt | `id`, `email`, `encrypted_password`, `role`, `active`, `last_login_at` | User accounts | | `groups` | User Mgmt | `id`, `name`, `description`, `permissions[]` | RBAC groups | | `permissions` | User Mgmt | `id`, `code`, `name`, `module`, `description` | Permission definitions | | `audit_logs` | All Services | `id`, `action`, `user_id`, `resource`, `changes` (JSONB), `ip_address` | Audit trail for all operations | | `payment_requests` | Transaction Svc | `id`, `type`, `amount`, `currency`, `sender_ispb`, `receiver_ispb`, `state` | Payment transaction records | | `str_transfers` | Transaction Svc | `id`, `payment_id`, `str_message_type`, `settlement_date`, `state` | STR-specific transfer data | | `settlements` | Settlement Svc | `id`, `settlement_date`, `clearing`, `net_position`, `state` | LDL settlement records | **Message States:** `pending` -> `processing` -> `sent` -> `confirmed` -> `failed` **Valid Categories:** CAM, CTC, DDA, DOC, GRU, LDL, LPI, LTR, PCR, REC, REP, RET, SEL, SLC, STR, TED, CHQ, SIT, ADM, COB, GPS, BCO, CCS, FAT, GEN, INT, PAG, TRF, VAL ### 6.3 Seed Data 22 seed files in the BACEN Gateway providing production-ready reference data: | Seed File | Description | Records | |-----------|-------------|---------| | `001_admin_setup.exs` | Admin users, initial configuration | ~10 | | `002_financial_entities.exs` | Financial institution ISPB data | ~200 | | `004_payment_requests.exs` | Sample payment records | ~50 | | `005_bacen_messages.exs` | Sample BACEN messages | ~100 | | `006_message_templates.exs` | XML templates per message type | ~979 | | `010_bacen_reference_data.exs` | Error codes, domain values | ~5,300 | | `011_transaction_seeds.exs` | Transaction history data | ~200 | | `012_legacy_ispb_domains.exs` | Legacy ISPB domain mapping | ~50 | | `013_message_catalog.exs` | Complete 979-type message catalog | ~979 | | `014_operational_data.exs` | Operational configuration | ~100 | | `020_security_seeds.exs` | Security groups, functionalities | ~850 | | `021_message_group_permissions.exs` | Message group ACLs | ~44 | | `022_alcadas_vistos_seeds.exs` | Authorization tiers (alcadas) | ~30 | | `023_schedule_holidays_seeds.exs` | Brazilian holidays, schedule grid | ~50 | | `024_external_entities_seeds.exs` | External entity registry | ~80 | | `025_accounting_seeds.exs` | Chart of accounts, cost centers | ~150 | | `bacen_error_codes.exs` | BACEN error code reference | ~5,306 | | `financial_institutions.exs` | Basic institution data | ~50 | | `production_institutions.exs` | Production-grade ISPB data | ~200 | | `production_seed.exs` | Full production seed runner | -- | | `run_all_seeds.exs` | Master seed executor | -- | ### 6.4 Performance Indexes From `004_add_performance_indexes.sql`: | Index | Table | Columns | Purpose | |-------|-------|---------|---------| | `idx_bacen_messages_type_state` | bacen_messages | (message_type, state) | Fast filtering by type and state | | `idx_bacen_messages_category` | bacen_messages | (category) | Category-based queries | | `idx_bacen_messages_sender` | bacen_messages | (sender_ispb) | Sender lookups | | `idx_bacen_messages_receiver` | bacen_messages | (receiver_ispb) | Receiver lookups | | `idx_bacen_messages_created` | bacen_messages | (inserted_at DESC) | Time-based queries | | `idx_bacen_messages_correlation` | bacen_messages | (correlation_id) | Message correlation | | `idx_dlq_entries_processed` | dlq_entries | (processed, inserted_at) | Unprocessed DLQ scan | | `idx_dlq_entries_error_code` | dlq_entries | (error_code) | Error code distribution | | `idx_audit_logs_user_action` | audit_logs | (user_id, action, inserted_at) | Audit trail queries | | `idx_financial_institutions_ispb` | financial_institutions | (ispb) UNIQUE | ISPB lookups | --- ## 7. Security Architecture ### 7.1 Authentication | Mechanism | Technology | Scope | |-----------|-----------|-------| | **JWT Tokens** | Guardian (Elixir) | All API requests | | **SSO Code Exchange** | Custom (MONETARIE_SSO_SECRET) | Cross-system authentication from Core Backoffice | | **Azure AD OAuth** | Ueberauth (Elixir) | Enterprise SSO integration | | **Token Storage** | localStorage (frontend) | Client-side session persistence | | **Token Validation** | SsoAuth plug (API Gateway) | Every authenticated request | **Token Lifecycle:** - Access token: Short-lived (configurable TTL) - Refresh token: Longer-lived for session continuity - Auto-redirect to `/login` on 401 responses ### 7.2 Encryption | Layer | Technology | Configuration | |-------|-----------|---------------| | **XMLDSig** | RSA-SHA256 (ICP-Brasil) | 3 references (KeyInfo, AppHdr, Document), C14N canonicalization | | **MQ TLS** | TLS 1.2/1.3 | Cipher: ECDHE_RSA_AES_256_GCM_SHA384, mTLS required | | **Security Header** | 588-byte binary | Prepended to every MQ message | | **Certificate Storage** | K8s Secrets | `icp-brasil-cert`, `icp-brasil-key`, CA certificates | | **HTTPS** | Let's Encrypt | Wildcard cert for `*.dev.fluxiq.com.br` | | **Redis Auth** | Password-protected | `requirepass` in redis.conf | **XMLDSig Signing Process:** ```mermaid graph TD A[ISO 20022 XML] --> B[C14N Canonicalization] B --> C[SHA-256 Digest of Document] C --> D[Build SignedInfo element] D --> E[RSA-SHA256 Sign with ICP-Brasil private key] E --> F[Embed SignatureValue + X509Certificate] F --> G[Signed XML ready for MQ] ``` ### 7.3 Network Security 10 Kubernetes NetworkPolicies enforce zero-trust communication: | Policy | Pod | Allowed Ingress | Allowed Egress | |--------|-----|-----------------|----------------| | `frontend-network-policy` | frontend | Ingress Controller (:80) | API Gateway (:4000), DNS | | `api-gateway-network-policy` | api-gateway | Frontend (:4000), Ingress Controller (:4000) | All backend services, NATS (:4222), PostgreSQL (:5432), HTTPS (:443) | | `bacen-gateway-network-policy` | bacen-gateway | API Gateway (:4002), Message Processor (:4002) | IBM MQ (:1414), NATS (:4222), PostgreSQL (:5432), HTTPS (:443) | | `auth-service-network-policy` | auth-service | API Gateway (:4001) | PostgreSQL (:5432), NATS (:4222), HTTPS (:443) | | `message-processor-network-policy` | message-processor | API Gateway (:4003) | NATS (:4222), BACEN Gateway (:4002), PostgreSQL (:5432) | | `transaction-service-network-policy` | transaction-service | API Gateway (:4004) | NATS (:4222), PostgreSQL (:5432) | | `user-management-network-policy` | user-management | API Gateway (:4005) | NATS (:4222), PostgreSQL (:5432) | | `nats-network-policy` | nats | All backend services (:4222, :6222, :8222) | DNS, NATS cluster (:6222) | | `ibmmq-network-policy` | ibmmq | BACEN Gateway only (:1414), Admin pods (:9443) | DNS, HTTPS (:443) | | `intra-namespace` | `{}` (all pods) | All pods in namespace | All pods in namespace | **Pod Security Contexts:** | Setting | Value | |---------|-------| | `runAsNonRoot` | true | | `runAsUser` | 1000 (backend), 101 (frontend/nginx) | | `fsGroup` | 1000 | | `allowPrivilegeEscalation` | false | | `readOnlyRootFilesystem` | true (frontend), false (backend) | | `capabilities.drop` | ALL | ### 7.4 Audit | Requirement | Implementation | Retention | |-------------|---------------|-----------| | ICOM Messages | `bacen_messages` table with full XML content | 10 years | | DICT Reads | Audit log entries for every DICT query | 2 years | | User Actions | `audit_logs` table with JSONB change tracking | 5 years | | Authentication Events | Auth service event logging | 2 years | | MQ Message Delivery | DomainManager logging + Metrics ETS | 1 year | | Configuration Changes | Audit trail with before/after snapshots | 5 years | --- ## 8. Failure Analysis & Resilience ### 8.1 Service Failure Impact Matrix | Service Down | Impact | Blast Radius | Recovery Strategy | RTO | |-------------|--------|-------------|-------------------|-----| | **Frontend** | No UI access for end users | End users only | CDN cached static assets serve stale content. HPA auto-scales from 2 to 10 replicas. PDB ensures min 1 pod during updates. | < 30s | | **API Gateway** | No external API access | All users and integrations | 2+ replicas with HPA. PDB protects against simultaneous pod eviction. Ingress health checks route away from unhealthy pods. | < 30s | | **Auth Service** | No new logins; existing JWT tokens continue working until expiry | New authentication sessions | 2 replicas. Cached JWT validation in API Gateway reduces dependency. Restart restores service. | < 60s | | **BACEN Gateway** | No BACEN communication in either direction | All BACEN message processing | DLQ stores failed outbound messages. NATS JetStream buffers inbound events. DomainManager auto-reconnects per domain every 5s. 2+ replicas. | < 5s per domain | | **DomainManager** (per domain) | Single MQ domain disconnected | Messages routed to that specific domain | Auto-reconnect with 5s interval per domain. Other 4 domains unaffected. DLQ captures failed messages for retry. | 5s | | **Message Processor** | Processing pipeline stops; NATS queues build up | Outbound message pipeline | NATS JetStream durability preserves all messages. Catch-up processing on restart. 2-3 replicas with HPA. | < 30s | | **IBM MQ** | No BACEN communication (all 5 domains) | All BACEN I/O | NATS buffers all messages. DLQ stores failures. IBM MQ StatefulSet with persistent volume (20 GiB). Messages are persistent (DEFPSIST YES). | < 90s | | **NATS** | All internal messaging stops | All inter-service communication | Currently single node; scalable to 3-node cluster. JetStream file-based storage survives pod restart. 50 GiB persistent volume. | < 10s | | **PostgreSQL** | All database operations fail | All services | Cloud SQL HA with automatic failover. Connection via PgBouncer pool. Point-in-time recovery available. | < 60s | | **Redis** | Cache misses; BACEN Gateway falls back to DB queries | BACEN Gateway performance | StatefulSet with 10 GiB persistent volume. RDB snapshots (save 900 1, save 300 10, save 60 10000). Auto-reconnect via Redix. | < 10s | | **Transaction Service** | No payment processing; payments queue in NATS | Payment operations only | 2 replicas. Messages preserved in NATS JetStream until service recovers. | < 30s | | **User Management** | No user CRUD operations; cached users still work | Administrative operations | 2 replicas. Non-critical path (auth tokens remain valid). | < 30s | ### 8.2 Circuit Breaker Patterns **DomainManager (per-domain reconnection):** ``` CONNECTED --[connection closed]--> DISCONNECTED DISCONNECTED --[5s timer]--> CONNECTING CONNECTING --[success]--> CONNECTED CONNECTING --[failure]--> DISCONNECTED --[schedule reconnect 5s]--> ``` Each of the 5 domains operates independently. A failure in SPB01 does not affect MES03. **ErrorHandler (exponential backoff):** | Attempt | Backoff (exponential) | Backoff (linear) | |---------|----------------------|-------------------| | 1 | 1,000ms | 1,000ms | | 2 | 2,000ms | 2,000ms | | 3 | 4,000ms | 3,000ms | | Max (3) | Send to DLQ | Send to DLQ | STR messages get 5 retry attempts; all others get 3. **ErrorHandler Error Categories:** | Range | Category | Retryable | Examples | |-------|----------|-----------|----------| | 1000-1999 | Validation | No | Invalid format, missing fields, schema failure | | 2000-2999 | Authentication | No | Invalid/expired/revoked certificate, bad signature | | 3000-3999 | Authorization | No | Insufficient permissions, institution not authorized | | 4000-4999 | Business Logic | Mostly No | Insufficient funds, duplicate transaction, invalid time (retryable) | | 5000-5999 | System | Yes | Internal error, DB error, service unavailable, queue full | | 6000-6999 | Network | Mostly Yes | Connection timeout/refused, network unreachable, SSL error (not retryable) | | 7000-7999 | Timeout | Yes | Request/response/processing timeout | ### 8.3 Data Loss Prevention | Component | Durability Mechanism | Recovery | |-----------|---------------------|----------| | **NATS JetStream** | File-based storage on 50 GiB PV, at-least-once delivery, durable subscriptions | Replay from last acknowledged position | | **IBM MQ** | DEFPSIST YES (persistent messages), 20 GiB PV, DLQ (`QL.DLQ.12345678`) | Messages survive pod restart; DLQ retry | | **PostgreSQL** | Cloud SQL WAL replication, daily backups, 30-day retention, PITR | Point-in-time recovery | | **Redis** | RDB snapshots (save 900 1, save 300 10, save 60 10000), 10 GiB PV | Snapshot restore; cache rebuild from DB | | **Dead Letter Queue** | Ecto-backed (`dlq_entries` table), never silently dropped | Manual retry via `DeadLetterQueue.retry_entry/1` | | **Audit Trail** | Append-only `audit_logs` table, PostgreSQL WAL | Database restore | --- ## 9. Monitoring & Observability ### 9.1 Prometheus Metrics All backend services expose Prometheus-compatible metrics via `/metrics` endpoint. **HTTP Metrics:** ``` http_request_duration_seconds{service, endpoint, method} http_request_total{service, endpoint, method, status} ``` **BACEN Gateway Metrics (ETS-based):** ``` bacen_messages_sent_total{message_type, domain} bacen_messages_received_total{message_type} bacen_messages_failed_total{message_type, error_code} bacen_processing_duration_seconds{message_type, direction} bacen_dlq_entries_total{message_type} bacen_domain_status{domain, status} bacen_retry_total{message_type} bacen_error_count{error_code, category} ``` **Broadway Pipeline Metrics (available but not active):** ``` broadway_messages_received_total{pipeline} broadway_messages_processed_total{pipeline} broadway_messages_failed_total{pipeline} broadway_processing_duration_seconds{pipeline} ``` **NATS Metrics:** ``` nats_messages_published_total{subject} nats_messages_consumed_total{subject} nats_jetstream_ack_duration_seconds{stream} ``` ### 9.2 Health Checks | Service | Liveness Probe | Readiness Probe | Initial Delay | Period | |---------|---------------|-----------------|---------------|--------| | frontend | GET / :80 | GET / :80 | 10s / 5s | 30s / 10s | | api-gateway | GET /health :4000 | GET /health :4000 | 30s / 20s | 10s / 5s | | bacen-gateway | GET /health :4002 | GET /ready :4002 | 30s / 20s | 10s / 5s | | auth-service | GET /health :4001 | GET /health :4001 | 30s / 20s | 10s / 5s | | message-processor | GET /health :4003 | GET /ready :4003 | 30s / 20s | 10s / 5s | | transaction-service | GET /health :4005 | GET /ready :4005 | 30s / 20s | 10s / 5s | | user-management | GET /health :4004 | GET /ready :4004 | 30s / 20s | 10s / 5s | | nats | GET /healthz :8222 | GET /healthz :8222 | 10s / 10s | 10s / 10s | | ibmmq | TCP :1414 | TCP :1414 | 90s / 60s | 30s / 10s | | redis | redis-cli PING | redis-cli PING | 10s / 5s | 10s / 5s | ### 9.3 Alert Rules Defined in `prometheus-rules-phase2.yaml`: | Alert | Expression | Duration | Severity | |-------|-----------|----------|----------| | **RedisDown** | `up{job="redis-exporter"} == 0` | 1m | Critical | | **RedisCacheHitRateLow** | Cache hit rate < 50% | 5m | Warning | | **RedisMemoryHigh** | Memory > 90% of max | 5m | Warning | | **DatabaseConnectionsHigh** | Connections > 80% of max | 5m | Warning | | **DatabaseReplicationLag** | Replication lag > 10s | 5m | Warning | ### 9.4 Grafana Dashboards Available at `monitoring-dev.fluxiq.com.br` (admin/Monetarie#Adm@2026). Key dashboards: - **SPB Message Overview**: Total messages by type, state distribution, processing latency - **BACEN Gateway**: Domain connection status, message throughput per domain, DLQ depth - **Service Health**: Pod status, CPU/memory per service, restart count - **NATS JetStream**: Stream depth, consumer lag, publish/subscribe rates - **IBM MQ**: Queue depth, connection status, message rates per channel - **Redis**: Hit rate, memory usage, key count, persistence status - **PostgreSQL**: Connection pool, query latency, replication lag --- ## 10. Deployment Architecture ### 10.1 Image Registry All images are stored in Google Artifact Registry: ``` southamerica-east1-docker.pkg.dev/fluxiqbr/fluxiq/{system}-{component}:{tag} ``` | Component | Image Name | Example Tag | |-----------|-----------|-------------| | Frontend | `fluxiq/spb-frontend` | `dafb4b9` | | BACEN Gateway | `monetarie/spb-backend` | `latest` | | API Gateway | `monetarie/spb-backend` | `latest` | | Auth Service | `monetarie/spb-backend` | `latest` | | Message Processor | `monetarie/spb-backend` | `latest` | | BACEN Simulator | `fluxiq/spb-simulator` | `latest` | | NATS | `nats:2.10-alpine` | Official | | IBM MQ | `icr.io/ibm-messaging/mq:9.4.0.0-r1` | Official | | Redis | `redis:7.2-alpine` | Official | | Cloud SQL Proxy | `gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.8.2` | Official | ### 10.2 Cloud Build Pipeline ```mermaid graph LR A[Developer Push] --> B[gcloud builds submit] B --> C[npm install] C --> D[npm run build] D --> E[docker build] E --> F[docker push to AR] F --> G[Connect Gateway credentials] G --> H[kubectl set image] H --> I[Rolling Update on GKE] ``` **Build Command:** ```bash cd frontend-vue/ gcloud builds submit --config=cloudbuild.yaml \ --substitutions=SHORT_SHA=$(git rev-parse --short HEAD) \ --project=fluxiqbr ``` **GKE Access (mandatory Connect Gateway):** ```bash # Step 1: Get credentials via Connect Gateway (ALWAYS required) gcloud container fleet memberships get-credentials fluxiq-dev \ --project=fluxiqbr \ --location=southamerica-east1 # Step 2: kubectl now works through the gateway kubectl get pods -n spb ``` The GKE cluster is private. Direct `kubectl` access from local machines or Cloud Build workers is blocked. Connect Gateway bypasses all network restrictions. ### 10.3 Deployment Order Deployments must follow this dependency order: ``` 1. Namespace + Secrets + ConfigMaps (00, 01, 02) 2. Infrastructure (NATS, IBM MQ, Redis, PgBouncer) (03) 3. BACEN Gateway (04) -- core dependency 4. API Gateway (05) 5. Auth Service (07, 11) 6. Backend Services (Transaction, User Mgmt, etc.) (07, 12-15) 7. Message Processor (14) 8. Frontend (06) 9. Ingress (08, 10) 10. BACEN Simulator (optional) (09) ``` ### 10.4 HPA Configuration | Service | Min Replicas | Max Replicas | CPU Target | Memory Target | Scale-Down Window | |---------|-------------|-------------|-----------|--------------|------------------| | frontend | 2 | 10 | 70% | 80% | 300s | | api-gateway | 2 | 10 | 70% | 80% | 300s | | bacen-gateway | 2 | 10 | 70% | 80% | 300s | | message-processor | 2 | 10 | 70% | 80% | 300s | **Scale-Up Policy:** Max(100% increase OR +2 pods) per 30s window, no stabilization delay. **Scale-Down Policy:** Max 50% decrease per 60s window, 300s stabilization. **Pod Disruption Budgets:** | Service | minAvailable | |---------|-------------| | frontend | 1 | | bacen-gateway | 1 | | message-processor | 1 | ### 10.5 Resource Allocation | Service | CPU Request | CPU Limit | Memory Request | Memory Limit | Storage | |---------|-----------|----------|---------------|-------------|---------| | **frontend** | 100m | 500m | 256 MiB | 512 MiB | -- | | **api-gateway** | 200m | 500m | 256 MiB | 1 GiB | -- | | **bacen-gateway** | 250m | 1,000m | 512 MiB | 2 GiB | -- | | **auth-service** | 200m | 500m | 256 MiB | 1 GiB | -- | | **message-processor** | 250m | 1,000m | 512 MiB | 2 GiB | -- | | **transaction-service** | 200m | 500m | 256 MiB | 1 GiB | -- | | **user-management** | 200m | 500m | 256 MiB | 1 GiB | -- | | **nats** | 500m | 2,000m | 1 GiB | 4 GiB | 50 GiB SSD | | **ibmmq** | 500m | 2,000m | 1 GiB | 4 GiB | 20 GiB SSD | | **redis** | 250m | 1,000m | 512 MiB | 2 GiB | 10 GiB SSD | | **cloud-sql-proxy** (sidecar) | 100m | 200m | 128 MiB | 256 MiB | -- | **Total Cluster Resources (minimum):** - CPU: ~4.5 cores (requests), ~12 cores (limits) - Memory: ~7 GiB (requests), ~24 GiB (limits) - Storage: 80 GiB SSD (NATS + IBM MQ + Redis) --- ## 11. Environment Configuration ### 11.1 Required Environment Variables #### Common (all services via `service-config` ConfigMap) | Variable | Value | Source | |----------|-------|--------| | `NATS_URL` | `nats://nats.spb.svc.cluster.local:4222` | ConfigMap | | `IBM_MQ_HOST` | `ibmmq.spb.svc.cluster.local` | ConfigMap | | `IBM_MQ_PORT` | `5672` | ConfigMap | | `IBM_MQ_QMGR` | `QM.12345678.01` | ConfigMap | | `IBM_MQ_CHANNEL` | `C12345678.00038166.1` | ConfigMap | | `ISPB_LOCAL` | `12345678` | ConfigMap | | `ISPB_BACEN` | `00038166` | ConfigMap | | `DATABASE_HOST` | `127.0.0.1` (Cloud SQL Proxy) | ConfigMap | | `DATABASE_PORT` | `5432` | ConfigMap | | `DATABASE_NAME` | `spbcabin_prod` | ConfigMap | | `DATABASE_POOL_SIZE` | `10` | ConfigMap | | `MIX_ENV` | `prod` | ConfigMap | | `LOG_LEVEL` | `info` | ConfigMap | #### Service-Specific Internal URLs (ConfigMap) | Variable | Value | |----------|-------| | `API_GATEWAY_URL` | `http://api-gateway.spb.svc.cluster.local:4000` | | `AUTH_SERVICE_URL` | `http://auth-service.spb.svc.cluster.local:4001` | | `BACEN_GATEWAY_URL` | `http://bacen-gateway.spb.svc.cluster.local:4002` | | `MESSAGE_PROCESSOR_URL` | `http://message-processor.spb.svc.cluster.local:4003` | | `TRANSACTION_SERVICE_URL` | `http://transaction-service.spb.svc.cluster.local:4004` | | `USER_MANAGEMENT_URL` | `http://user-management.spb.svc.cluster.local:4005` | #### API Gateway Secrets | Variable | Source | Description | |----------|--------|-------------| | `PORT` | Deployment | `4000` | | `SECRET_KEY_BASE` | `api-gateway-secrets` | Phoenix secret (64+ bytes) | | `GUARDIAN_SECRET_KEY` | `api-gateway-secrets` | JWT signing key | | `JWT_SECRET` | `api-gateway-secrets` | Token encryption | | `DATABASE_USER` | `db-credentials` | PostgreSQL username | | `DATABASE_PASSWORD` | `db-credentials` | PostgreSQL password | #### Auth Service Secrets | Variable | Source | Description | |----------|--------|-------------| | `PORT` | Deployment | `4001` | | `SECRET_KEY_BASE` | `auth-service-secrets` | Phoenix secret | | `GUARDIAN_SECRET_KEY` | `auth-service-secrets` | JWT signing key | | `OAUTH_CLIENT_ID` | `auth-service-secrets` | Azure AD client ID | | `OAUTH_CLIENT_SECRET` | `auth-service-secrets` | Azure AD client secret | | `DATABASE_USER` | `db-credentials` | PostgreSQL username | | `DATABASE_PASSWORD` | `db-credentials` | PostgreSQL password | #### BACEN Gateway Secrets | Variable | Source | Description | |----------|--------|-------------| | `PORT` | Deployment | `4002` | | `SECRET_KEY_BASE` | `bacen-gateway-secrets` | Phoenix secret | | `ICP_BRASIL_CERT` | `bacen-gateway-secrets` | ICP-Brasil X.509 certificate (PEM) | | `ICP_BRASIL_KEY` | `bacen-gateway-secrets` | ICP-Brasil private key (PEM) | | `IBM_MQ_PASSWORD` | `bacen-gateway-secrets` | MQ app password | | `BACEN_PRIVATE_KEY_PATH` | Deployment | `/etc/ssl/private/bacen-key.pem` | | `BACEN_CERTIFICATE_PATH` | Deployment | `/etc/ssl/certs/bacen-cert.pem` | | `BACEN_CA_CERT_PATH` | Deployment | `/etc/ssl/certs/bacen-ca.pem` | | `DATABASE_USER` | `db-credentials` | PostgreSQL username | | `DATABASE_PASSWORD` | `db-credentials` | PostgreSQL password | #### IBM MQ Secrets | Variable | Source | Description | |----------|--------|-------------| | `MQ_ADMIN_PASSWORD` | `ibmmq-secrets` | MQ admin console password | | `MQ_APP_PASSWORD` | `ibmmq-secrets` | MQ application connection password | #### Frontend ConfigMap | Variable | Value | Description | |----------|-------|-------------| | `REACT_APP_API_URL` | `http://api-gateway.spb.svc.cluster.local:4000` | API base URL | | `REACT_APP_GRAPHQL_ENDPOINT` | `http://api-gateway.spb.svc.cluster.local:4000/graphql` | GraphQL endpoint | | `REACT_APP_WS_ENDPOINT` | `ws://api-gateway.spb.svc.cluster.local:4000/socket` | WebSocket endpoint | | `REACT_APP_ENVIRONMENT` | `production` | Environment identifier | | `REACT_APP_LOG_LEVEL` | `warn` | Client-side log level | ### 11.2 Secrets Management All secrets are stored as Kubernetes Secret resources in the `spb` namespace: | Secret Name | Keys | Used By | |-------------|------|---------| | `db-credentials` | `connection-name`, `username`, `password`, `database` | All backend services | | `api-gateway-secrets` | `secret-key-base`, `guardian-secret-key`, `jwt-secret` | API Gateway | | `auth-service-secrets` | `secret-key-base`, `guardian-secret-key`, `oauth-client-id`, `oauth-client-secret` | Auth Service | | `bacen-gateway-secrets` | `secret-key-base`, `icp-brasil-cert`, `icp-brasil-key`, `ibmmq-password` | BACEN Gateway | | `ibmmq-secrets` | `admin-password`, `app-password` | IBM MQ StatefulSet | | `message-processor-secrets` | `secret-key-base` | Message Processor | **Security Practices:** - All secret values are marked as `CHANGE_ME_*` in YAML templates and must be replaced before deployment - ICP-Brasil certificates and private keys are stored as multi-line PEM strings - Secret references use `valueFrom.secretKeyRef` (never hardcoded in pod specs) - `.gitignore` excludes `**/production_users.exs`, `**/003_users_api_keys.exs`, `**/007_webhook_config.exs` - Redis password is embedded in ConfigMap (should be migrated to Secret for production) --- ## Appendix A: Quick Reference ### Service Endpoints (Development) | Service | URL | |---------|-----| | SPB Admin Frontend | `https://spbadmin-dev.fluxiq.com.br` | | SPB API Gateway | `https://spbadmin-dev.fluxiq.com.br/api` | | Grafana Monitoring | `https://monitoring-dev.fluxiq.com.br` | | NATS Monitoring | `http://nats.spb.svc.cluster.local:8222` | | IBM MQ Console | `https://ibmmq.spb.svc.cluster.local:9443` | ### Key Commands ```bash # GKE Access gcloud container fleet memberships get-credentials fluxiq-dev \ --project=fluxiqbr --location=southamerica-east1 # Check pods kubectl get pods -n spb # View BACEN Gateway logs kubectl logs -n spb -l app=bacen-gateway -f # Check NATS JetStream kubectl exec -n spb nats-0 -- nats-server --signal ldm # Build and deploy frontend cd frontend-vue/ gcloud builds submit --config=cloudbuild.yaml \ --substitutions=SHORT_SHA=$(git rev-parse --short HEAD) \ --project=fluxiqbr # Check DLQ entries kubectl exec -n spb deploy/bacen-gateway -- \ bin/bacen_gateway rpc "BacenGateway.DeadLetterQueue.get_statistics()" ``` ### BACEN Test Credentials | Parameter | Value | |-----------|-------| | ISPB Local | 12345678 | | ISPB BACEN | 00038166 | | GEN0001 Test | Connection test message | | Simulator | Built-in at port 4011 | --- *Document generated from codebase analysis on 2026-02-07.* *Source: `/Users/luizpenha/monetarie/spb/` -- 11 services, 979 message types, 106 frontend routes.*