# Monetarie SPB - Ecosystem Documentation **Version**: 1.0 **Date**: 2026-02-07 **Classification**: Internal - Engineering & Operations --- ## 1. Executive Summary Monetarie SPB is a cloud-native platform for integration with Brazil's Central Bank (BACEN) Sistema de Pagamentos Brasileiro (SPB). It replaces the legacy CRK/EvolutionPro on-premises system with a modern, horizontally-scalable architecture running on Google Kubernetes Engine (GKE). The system processes BACEN messages (ISO 20022/XML) across 10 clearing systems (STR, LPI, CIP, SELIC, NPC, etc.), handling the full lifecycle: message creation, XMLDSig signing, routing via IBM MQ to BACEN's RSFN network, response processing, settlement tracking, and audit logging. **Key Numbers**: - 979 BACEN message types (Catalogo de Mensagens v5.11) - 5,306+ error codes mapped with retry policies - 37 database tables - 53 REST API endpoints across 17 controllers - 5 IBM MQ domains for BACEN communication - 3-node NATS JetStream cluster for internal messaging - 3-node TigerBeetle cluster for financial ledger --- ## 2. Infrastructure Topology ### 2.1 Network Architecture ``` INTERNET | [Cloud Load Balancer] (GCE Ingress + TLS) | +----------------+----------------+ | | | spbadmin-dev spbapi-dev spbdocs-dev .fluxiq.com.br .fluxiq.com.br .fluxiq.com.br | | | +--------+--------+------+------+---------+--------+ | GKE Cluster (fluxiq-dev) | southamerica-east1 | | VPC: fluxiq-dev-vpc | Subnet: 10.10.20.0/24 | | | | | +---------------------------+ | | | Namespace: spb | | | | | | | | [spb-frontend x2] | | | | [spb-backend x2]---+ | | | | [spb-docs x1] | | | | | [spb-simulator x1] | | | | | [ibmmq x1] | | | | +---------------------------+ | | | | | | Cloud SQL IBM MQ | | Proxy :1414 | | (sidecar) | +-------------------------------------------------------+ | | +--------+--------+ +-------+---------+ | VM Subnet | | Cloud SQL | | 10.10.40.0/24 | | (Private IP) | | | | | | NATS Cluster: | | fluxiq-pg-dev | | nats-dev-1 :5 | | PG16 | | nats-dev-2 :7 | | 10.140.241.2 | | nats-dev-3 :4 | +-----------------+ | | | TigerBeetle: | | tb-dev-1 :2 | | tb-dev-2 :6 | | tb-dev-3 :3 | +------------------+ ``` ### 2.2 GKE Cluster | Property | Value | |----------|-------| | Cluster Name | `fluxiq-dev` | | Region | `southamerica-east1` | | Type | Private (no public endpoint) | | Access | Connect Gateway only | | Node Pool | `np-system-dev` (3 nodes) | | Node Machine | e2-standard-4 | | Kubernetes Version | 1.30.x | **GKE Nodes:** | Node | Zone | Internal IP | |------|------|-------------| | gke-fluxiq-dev-np-system-dev-d3f5702a-c7c9 | southamerica-east1-a | 10.10.20.5 | | gke-fluxiq-dev-np-system-dev-d4774ae9-jzt2 | southamerica-east1-b | 10.10.20.6 | | gke-fluxiq-dev-np-system-dev-1a6aaba4-vh5n | southamerica-east1-c | 10.10.20.7 | **Access (mandatory pattern):** ```bash gcloud container fleet memberships get-credentials fluxiq-dev \ --project=fluxiqbr --location=southamerica-east1 kubectl get pods -n spb ``` ### 2.3 VM Instances (Stateful Services) #### NATS JetStream Cluster | VM | Zone | IP | Port | Server Name | |----|------|----|------|-------------| | nats-dev-1 | southamerica-east1-a | 10.10.40.5 | 4222 | nats-dev-1 | | nats-dev-2 | southamerica-east1-b | 10.10.40.7 | 4222 | nats-dev-2 | | nats-dev-3 | southamerica-east1-c | 10.10.40.4 | 4222 | nats-dev-3 | - Cluster Name: `monetarie-nats` - NATS Version: 2.10.11 - JetStream: Enabled - Max Payload: 1MB #### TigerBeetle Financial Ledger Cluster | VM | Zone | IP | Machine Type | Storage | |----|------|----|-------------|---------| | tb-dev-1 | southamerica-east1-a | 10.10.40.2 | c2-standard-8 | Local NVMe SSD | | tb-dev-2 | southamerica-east1-b | 10.10.40.6 | c2-standard-8 | Local NVMe SSD | | tb-dev-3 | southamerica-east1-c | 10.10.40.3 | c2-standard-8 | Local NVMe SSD | - Port: 3001 - Cluster ID: 0 - Replicas: 3 - Storage: ext4 on NVMe, mounted at `/data/tigerbeetle` ### 2.4 Cloud SQL | Property | Value | |----------|-------| | Instance | `fluxiq-pg-dev` | | Engine | PostgreSQL 16 | | Machine | 8 vCPUs, 32GB RAM | | Private IP | 10.140.241.2 | | Database | `spb_dev` | | Max Connections | 5,000 | | Pool Size (per pod) | 500 | | Access | Cloud SQL Proxy sidecar (localhost:5432) | ### 2.5 Kubernetes Services (spb namespace) | Service | Type | ClusterIP | Port | |---------|------|-----------|------| | spb-backend | ClusterIP | 10.24.14.137 | 4000 | | spb-frontend | ClusterIP | 10.24.1.212 | 80 | | spb-docs | ClusterIP | 10.24.6.202 | 80 | | spb-simulator | ClusterIP | 10.24.14.62 | 80 | | ibmmq | ClusterIP | 10.24.1.129 | 1414, 5672, 9443 | ### 2.6 Pods | Pod | Containers | Replicas | Image | |-----|-----------|----------|-------| | spb-backend | spb-backend + cloud-sql-proxy | 2 | `spb-backend:55c6887` | | spb-frontend | spb-frontend | 2 | `spb-frontend:38dd38d` | | spb-docs | spb-docs | 1 | - | | spb-simulator | spb-simulator | 1 | - | | ibmmq | ibmmq | 1 | `ibm-mq:9.4.2.0-r1` | --- ## 3. Technology Stack ### 3.1 Backend | Layer | Technology | Version | Purpose | |-------|-----------|---------|---------| | Language | Elixir | 1.17.3 | Functional, concurrent, fault-tolerant | | Framework | Phoenix | 1.8.3 | HTTP/WebSocket server | | ORM | Ecto | 3.13.5 | Database access (used minimally) | | Database Driver | Postgrex | - | PostgreSQL protocol | | JSON | Jason | - | JSON encoding/decoding | | Auth | Bcrypt | - | Password hashing | | JWT | Erlang :crypto | - | HMAC-SHA256 (no external deps) | | NATS | Gnat | - | NATS client with connection supervisor | | HTTP Client | :httpc | - | Erlang built-in (for IBM MQ sidecar) | | XML | SweetXml | - | XPath queries | | Crypto | XMLDSig (custom) | - | RSA-SHA256 XML signatures | ### 3.2 Frontend | Layer | Technology | Version | Purpose | |-------|-----------|---------|---------| | Framework | Vue | 3.5.27 | Reactive UI framework | | Language | TypeScript | 5.9 | Strict typing (no `any`) | | UI Library | Vuetify | 3.11.8 | Material Design components | | State | Pinia | - | Reactive stores | | Router | Vue Router | 4 | SPA routing | | HTTP | Axios | - | API client | | Build | Vite | - | Fast build tool | | i18n | vue-i18n | - | Portuguese/English | | Testing | Playwright | - | E2E tests | ### 3.3 Infrastructure | Component | Technology | Purpose | |-----------|-----------|---------| | Cloud | Google Cloud Platform | Hosting | | Orchestration | GKE (Kubernetes) | Container orchestration | | Database | Cloud SQL (PostgreSQL 16) | Relational data | | Internal Messaging | NATS JetStream 2.10.11 | Async pub/sub | | External Messaging | IBM MQ 9.4.2 | BACEN RSFN communication | | Financial Ledger | TigerBeetle | Double-entry accounting | | Container Registry | Artifact Registry | Docker images | | CI/CD | Cloud Build | Build + deploy pipelines | | DNS | Cloud DNS | Domain management | | TLS | Let's Encrypt | HTTPS certificates | | Secrets | Kubernetes Secrets | Credentials storage | --- ## 4. Database Schema ### 4.1 Table Overview (37 Tables) #### Core Tables | Table | Records | Purpose | Key Columns | |-------|---------|---------|-------------| | `bacen_messages` | 40,000 | BACEN message lifecycle | message_id, message_type, message_category, state, direction, institution_ispb, content (JSONB), xml_content | | `institutions` | 49 | Financial institutions (ISPB) | ispb, cnpj, name, short_name, type, spb_participant, str_participant | | `users` | 50 | System users | email, username, password_hash, role, institution_ispb | | `clearings` | 8 | Clearing/settlement systems | name, type, online | | `bacen_tariffs` | 18 | BACEN service tariffs | code, description, amount | #### Operations Tables | Table | Purpose | |-------|---------| | `payment_requests` | TED/DOC/Boleto payment tracking (20,000 records) | | `accounts` | Bank accounts (500 records) | | `str_transfers` | STR domain transactions | | `lpi_operations` | LPI (instant payment) operations | | `settlements` | Settlement/clearing operations | | `forex_operations` | Foreign exchange operations | | `securities_operations` | Securities (SELIC) trading | | `cash_operations` | Cash management (CIR) | | `custody_operations` | Custody operations (CTP) | #### Configuration Tables | Table | Records | Purpose | |-------|---------|---------| | `system_config` | 10 | Key-value system configuration | | `message_groups` | - | BACEN message type groupings | | `message_templates` | 20 | XML templates for BACEN messages | | `operation_statuses` | - | Valid state values | | `status_transitions` | - | State machine rules | | `functionalities` | - | RBAC permission tree | #### Security Tables | Table | Purpose | |-------|---------| | `sessions` | Active user sessions | | `audit_logs` | All user actions (10-year retention) | | `api_keys` | API key management (20 keys) | | `alcadas` | Authorization levels (4 tiers) | | `vistos` | Approval/visto workflow | #### Reference Tables | Table | Records | Purpose | |-------|---------|---------| | `bacen_error_codes` | 85 | BACEN error codes with retry policies | | `bacen_holidays` | - | BACEN operating calendar | | `bacen_operating_schedule` | - | BACEN operating hours per system | ### 4.2 Key Relationships ``` institutions (ispb PK) | +-- users (institution_ispb FK) +-- bacen_messages (institution_ispb FK) +-- payment_requests (payer_ispb, beneficiary_ispb) +-- accounts (institution_ispb FK) +-- api_keys (institution_ispb FK) +-- webhook_configs (institution_ispb - logical FK) bacen_messages (id PK, message_id UNIQUE) | +-- payment_requests (message_id FK) +-- message_state_history (message_id FK) +-- dlq_entries (message_id FK) users (id PK, email UNIQUE) | +-- sessions (user_id FK) +-- audit_logs (user_id FK) +-- alcadas (user assignments) +-- vistos (requestor_id, approver_id) ``` ### 4.3 Code-Database Relationship The backend uses two patterns for database access: **Pattern 1: Raw SQL via SqlHelpers (preferred, used by 15 controllers)** ```elixir # In any controller import BacenGatewayWeb.SqlHelpers def index(conn, params) do result = query!("SELECT * FROM institutions WHERE active = true ORDER BY name", []) data = rows_to_maps(result) json(conn, %{success: true, data: data}) end ``` `SqlHelpers` provides: `query!/2`, `rows_to_maps/1`, pagination helpers. This is the standard pattern — no Ecto schemas required. **Pattern 2: Ecto Schema (used only for BacenMessage)** ```elixir # Only BacenMessage uses Ecto schema for complex queries alias BacenGateway.BacenMessage Repo.all(from m in BacenMessage, where: m.state == "pending", limit: 100) ``` **Rule**: New controllers MUST use SqlHelpers. Ecto schemas are only added when complex query composition is required. --- ## 5. Service Architecture & Communication ### 5.1 Service Map ``` [Browser / Admin Portal] | [GCE Ingress + TLS] | +------------+------------+ | | [spb-frontend] [spb-backend] Vue 3 + Vuetify Elixir/Phoenix Static SPA 53 REST endpoints | +---------------+---------------+ | | | [Cloud SQL] [NATS Cluster] [IBM MQ] PostgreSQL Internal Msgs BACEN RSFN 37 tables JetStream 5 domains | [TigerBeetle] Financial Ledger ``` ### 5.2 Backend (spb-backend) — 17 Controllers, 53 Endpoints | Controller | Endpoints | Purpose | |------------|-----------|---------| | HealthController | 2 | `/health`, `/ready` (K8s probes) | | AuthController | 3 | Login (JWT), verify, logout | | DashboardController | 5 | Stats, recent activity, balances, clearings, vistos count | | MessagesController | 7 | BACEN message CRUD + categories + states | | StatsController | 2 | Message statistics by state and category | | OperationsController | 7 | Operation lifecycle (create, send, cancel, retry, state transition) | | AlcadasController | 4 | Authorization level CRUD | | VistosController | 4 | Approval workflow (approve, reject, batch) | | ClearingsController | 2 | Clearing system status | | TariffsController | 2 | Tariff lookup and calculation | | MessageTemplatesController | 2 | XML message templates | | MessageGroupsController | 1 | Message type groupings | | OperationStatusesController | 2 | State machine definition | | FunctionalitiesController | 1 | RBAC permission tree | | ReportsController | 4 | Audit log, message movement, reserve statement, message stats | | SettingsController | 2 | System configuration | | UsersController | 5 | User CRUD | | InstitutionsController | 2 | Institution lookup (alias: `/entities`) | ### 5.3 Internal Messaging — NATS JetStream NATS handles all internal async communication. Messages are published as JSON. **Key Topics:** | Topic Pattern | Publisher | Consumer | Purpose | |--------------|-----------|----------|---------| | `spb.messages.new` | Backend (on message create) | MessageProcessor | New message for processing | | `spb.messages.validated` | Backend (after validation) | MessageProcessor | Validated, ready to send | | `spb.messages.sent` | Backend (after IBM MQ send) | Transaction Service | Message sent to BACEN | | `spb.messages.confirmed` | Backend (on BACEN response) | Transaction Service | BACEN confirmed | | `spb.messages.failed` | Backend (on failure) | Dead Letter Queue | Failed message | | `bacen.mq.outbound.*` | DomainManager | Simulator (dev) | MQ-bound messages (dev routing via NATS) | **Connection Config:** ```elixir # application.ex supervision tree {Gnat.ConnectionSupervisor, %{ name: :bacen_gateway_nats, connection_settings: [ %{host: "10.10.40.5", port: 4222} ] }} ``` ### 5.4 External Messaging — IBM MQ Series (BACEN RSFN) IBM MQ is the interface to BACEN's Rede do Sistema Financeiro Nacional (RSFN). All communication with BACEN goes through IBM MQ queues following the BACEN Manual de Redes v9.3. **5 BACEN Domains:** | Domain | Seq | Priority | Queue Manager | Port | Purpose | |--------|-----|----------|---------------|------|---------| | SPB01 | 01 | Platina | QM.12345678.01 | 1414 | STR/LPI (critical) | | SPB02 | 02 | Ouro | QM.12345678.05 | 15422 | CIP/Settlement | | MES01 | 03 | Platina | QM.12345678.02 | 12422 | Reserved | | MES02 | 04 | Prata | QM.12345678.03 | 13422 | General | | MES03 | 05 | Bronze | QM.12345678.04 | 14422 | General (low priority) | **Queue Naming Convention:** ``` Outbound (send to BACEN): QL.REQ.{ISPB_BACEN}.{ISPB_LOCAL}.{seq} Inbound (receive from BACEN): QL.RSP.{ISPB_BACEN}.{ISPB_LOCAL}.{seq} Remote Request: QR.REQ.{ISPB_BACEN}.{ISPB_LOCAL}.{seq} Remote Response: QR.RSP.{ISPB_LOCAL}.{ISPB_BACEN}.{seq} Dead Letter: QL.DLQ.{ISPB_LOCAL} ``` Example for Monetarie (ISPB 12345678) sending to BACEN (ISPB 00038166) on domain SPB01: - Send: `QL.REQ.00038166.12345678.01` - Receive: `QL.RSP.00038166.12345678.01` **Message Flow (BACEN Communication):** ``` 1. Application creates BACEN message (ISO 20022 XML) 2. Canonicalize XML (C14N) 3. Sign with XMLDSig (RSA-SHA256, ICP-Brasil certificate) 4. DomainManager selects domain by priority/message type 5. Send to QL.REQ queue via IBM MQ 6. BACEN processes and responds 7. Receive from QL.RSP queue 8. Verify XMLDSig signature 9. Parse response, update message state 10. Publish result to NATS for internal processing ``` **Development Mode:** When `IBM_MQ_ENABLED=false` (default in dev), the DomainManager routes messages via NATS instead of IBM MQ. The simulator consumes these NATS messages and generates mock BACEN responses. ### 5.5 Message Processing Pipeline ``` [API Request / NATS Event] | [MessageProcessor] | +----+----+ | | Validate Parse XML | | Sign (XMLDSig RSA-SHA256) | Route to Domain (SPB01-SPB02, MES01-MES03) | +----+----+ | | [IBM MQ] [NATS] (prod vs dev) | | [BACEN] [Simulator] | | Response | | | Verify Signature | Update DB State | Publish to NATS (confirmed/failed) | [Audit Log] ``` --- ## 6. Security Architecture ### 6.1 Authentication - **JWT (HMAC-SHA256)**: No external dependencies — uses Erlang `:crypto` directly - Tokens contain: `sub` (user ID), `email`, `role`, `iss` (monetarie_spb), `exp`, `iat` - Token TTL: 24 hours - Login: `POST /api/auth/login` with email + bcrypt password - Failed login tracking with account lockout ### 6.2 Authorization (RBAC) | Role | Capabilities | |------|-------------| | `super_admin` | Full access to all systems | | `admin` | User management, configuration, all operations | | `operator` | Message operations, monitoring, limited config | | `auditor` | Read-only access to all data for compliance | | `api_user` | Programmatic access via API keys | Alcadas (authorization levels) provide value-based approval tiers: - Level 1: Up to R$ 500,000 - Level 2: Up to R$ 5,000,000 - Level 3: Up to R$ 500,000,000 - Level 4: Unlimited (director approval) Vistos (approvals) require multiple signatures for high-value transactions. ### 6.3 Network Security - **Private GKE cluster**: No public Kubernetes API endpoint - **Cloud SQL**: Private IP only, accessed via Cloud SQL Proxy sidecar - **NATS**: Internal VPC only (10.10.40.x subnet) - **TigerBeetle**: Internal VPC only - **IBM MQ**: ClusterIP service (no external exposure) - **TLS**: Let's Encrypt for all external endpoints ### 6.4 BACEN Compliance - **XMLDSig**: RSA-SHA256 signatures on all BACEN messages - **ICP-Brasil**: Certificate authority for production keys - **Audit Trail**: 10-year retention for all message state transitions - **Alcadas/Vistos**: Multi-level approval for high-value operations --- ## 7. Frontend Architecture ### 7.1 Structure ``` frontend-vue/src/ apps/ admin/views/ # Admin portal views (~40 routes) operator/views/ # Operator portal views (~35 routes) components/ # Reusable components composables/ # Vue composables locales/ # i18n (pt-BR, en-US, zh-CN) router/ # Route definitions services/ api.ts # Axios client (base: spbapi-dev.fluxiq.com.br/api) stores/ # Pinia stores (auth, entities, ui) types/ # TypeScript interfaces views/ # Shared views (login, dashboard, settings) ``` ### 7.2 Key Design Rules - **NO MOCK DATA**: All data from backend API. Empty arrays as initial state. - **NO `any` type**: Strict TypeScript throughout. - **Composition API only**: `