Architecture Overview

FluxiQ SPB is a cloud-native platform composed of 11 Elixir microservices, a Vue 3 frontend, and a BACEN simulator. The architecture follows domain-driven design principles aligned with the settlement systems defined by the Brazilian Central Bank (BACEN).

System Diagram

                          +-------------------+
                          |   Vue 3 Frontend  |
                          |    (port 3000)    |
                          +---------+---------+
                                    |
                          +---------v---------+
                          |   API Gateway     |
                          |    (port 4000)    |
                          |  REST / GraphQL   |
                          +---------+---------+
                                    |
                 +------------------+------------------+
                 |                  |                   |
       +---------v------+  +-------v--------+  +------v---------+
       | Auth Service   |  | User Mgmt      |  | Extract Service|
       | (port 4001)    |  | (port 4004)    |  | (port 4010)    |
       | JWT / mTLS     |  | RBAC / Tenant  |  | Data Export    |
       +----------------+  +----------------+  +----------------+
                 |
    +------------+-------------+------------------+
    |            |             |                   |
+---v-------+ +-v----------+ +v-----------+ +----v--------+
|Transaction| |Securities  | |Settlement  | |Forex        |
|Service    | |Service     | |Service     | |Service      |
|(port 4005)| |(port 4006) | |(port 4007) | |(port 4008)  |
|STR/LPI/   | |SEL/CTP     | |LDL         | |CAM          |
|TED/DOC    | |            | |            | |             |
+-----------+ +------------+ +------------+ +----+--------+
                                                  |
                                           +------v--------+
                                           |Cash Service   |
                                           |(port 4009)    |
                                           |CIR            |
                                           +---------------+
    +-----------------------------------------------------------+
    |                  Message Processor (port 4003)             |
    |               Broadway Pipelines / GenStage                |
    +----------------------------+------------------------------+
                                 |
                      +----------v----------+
                      |   BACEN Gateway     |
                      |    (port 4002)      |
                      |  979 Message Types  |
                      |  IBM MQ / RSFN      |
                      +----------+----------+
                                 |
                      +----------v----------+
                      |      BACEN/RSFN     |
                      |   (or Simulator)    |
                      +---------------------+

Service Inventory

All services are built with Elixir and the Phoenix framework, running on the BEAM virtual machine for fault tolerance and concurrency.

Service	Port	Domain	Technology
api_gateway	4000	Request routing, rate limiting	Phoenix, Absinthe (GraphQL)
auth_service	4001	Authentication, token management	Guardian, Bcrypt, JOSE
bacen_gateway	4002	BACEN/RSFN message exchange	IBM MQ client, XML builder
message_processor	4003	Async message pipeline	Broadway, GenStage
user_management	4004	Users, roles, tenants	Ecto, RBAC
transaction_service	4005	STR, LPI, TED, DOC transfers	Ecto, Saga pattern
securities_service	4006	SEL, CTP securities settlement	Ecto, Event sourcing
settlement_service	4007	LDL deferred net settlement	GenServer, ETS
forex_service	4008	CAM currency exchange	PTAX integration
cash_service	4009	CIR cash operations	Ecto
extract_service	4010	Reports, data extraction	NimbleCSV, Flow

Communication Patterns

Synchronous (Request/Response)

Services communicate synchronously via HTTP for queries and commands that require immediate feedback. The API Gateway routes external requests to the appropriate service.

# API Gateway routing example
scope "/api/v1", ApiGateway.Router do
  pipe_through [:api, :authenticated]

  forward "/transactions", TransactionService.Proxy
  forward "/securities", SecuritiesService.Proxy
  forward "/settlements", SettlementService.Proxy
  forward "/forex", ForexService.Proxy
  forward "/cash", CashService.Proxy
end

Asynchronous (Message-Based)

For BACEN message processing, services communicate through Broadway pipelines. The Message Processor service acts as the central message bus.

# Broadway pipeline for BACEN messages
defmodule MessageProcessor.Pipeline do
  use Broadway

  def start_link(_opts) do
    Broadway.start_link(__MODULE__,
      name: __MODULE__,
      producer: [
        module: {BroadwayRabbitMQ.Producer,
          queue: "bacen_inbound",
          connection: [host: "localhost"],
          on_failure: :reject_and_requeue
        },
        concurrency: 10
      ],
      processors: [
        default: [concurrency: 50, max_demand: 1]
      ],
      batchers: [
        str: [concurrency: 5, batch_size: 100, batch_timeout: 200],
        ted: [concurrency: 10, batch_size: 200, batch_timeout: 500],
        default: [concurrency: 5, batch_size: 50, batch_timeout: 1000]
      ]
    )
  end
end

Event Sourcing

The securities_service and settlement_service use event sourcing to maintain an immutable audit trail of all settlement operations, as required by BACEN regulations.

Data Architecture

Each service owns its own PostgreSQL schema, enforcing data isolation:

spb_dev database
  ├── auth_schema        (auth_service)
  ├── users_schema       (user_management)
  ├── transactions_schema (transaction_service)
  ├── securities_schema  (securities_service)
  ├── settlements_schema (settlement_service)
  ├── forex_schema       (forex_service)
  ├── cash_schema        (cash_service)
  ├── messages_schema    (message_processor)
  ├── bacen_schema       (bacen_gateway)
  └── extracts_schema    (extract_service)

Fault Tolerance

The platform leverages OTP supervision trees for fault isolation. Each service has a supervision hierarchy:

Application
  ├── Endpoint (Phoenix)
  ├── Repo (Ecto)
  ├── Cache (ETS/Cachex)
  ├── TaskSupervisor
  ├── Broadway Pipeline
  └── HealthCheck (periodic)

If a Broadway pipeline crashes, the supervisor restarts it without affecting HTTP request handling. This "let it crash" philosophy ensures that transient failures do not cascade across the system.

Observability

All services export telemetry via OpenTelemetry:

• Metrics: Prometheus-compatible metrics exposed on /metrics per service
• Traces: Distributed tracing across service boundaries with W3C Trace Context
• Logs: Structured JSON logging with correlation IDs

Grafana dashboards provide visibility into:

• Message throughput per settlement system (STR, TED, LDL, etc.)
• End-to-end latency from API Gateway to BACEN response
• Settlement window status and deadlines
• Error rates and circuit breaker states

Security Architecture

• mTLS: All inter-service communication uses mutual TLS
• JWT: External API access requires JWT tokens issued by auth_service
• HSM: Cryptographic signing of BACEN messages uses Hardware Security Module integration
• Encryption: All data at rest encrypted with AES-256-GCM
• Audit: Every state change is logged with user, timestamp, and correlation ID