Architecture

FluxiQ Core uses a modern, event-driven architecture designed for high-throughput financial transactions with strong consistency guarantees.

System Overview

                    ┌─────────────────────────────────────┐
                    │           Load Balancer              │
                    │        (GCP HTTPS L7 LB)             │
                    └────────────┬────────────────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              │                  │                  │
      ┌───────▼──────┐  ┌───────▼──────┐  ┌───────▼──────┐
      │  Banking UI  │  │  Admin UI    │  │ Merchant UI  │
      │  (Vue 3)     │  │  (Vue 3)     │  │ (Vue 3)      │
      └───────┬──────┘  └───────┬──────┘  └───────┬──────┘
              │                  │                  │
              └──────────────────┼──────────────────┘
                                 │ REST / WebSocket
                    ┌────────────▼────────────────────┐
                    │     Phoenix API Gateway          │
                    │     (Elixir/OTP)                 │
                    └──┬─────────┬──────────┬─────────┘
                       │         │          │
              ┌────────▼──┐  ┌──▼────┐  ┌──▼──────────┐
              │TigerBeetle│  │ Redis │  │    NATS      │
              │  (Ledger)  │  │(Cache)│  │ (JetStream)  │
              └────────────┘  └───────┘  └─────────────┘
                       │                        │
              ┌────────▼────────────────────────▼──────┐
              │            PostgreSQL 16                │
              │     (Accounts, Users, Metadata)        │
              └────────────────────────────────────────┘

Technology Stack

Backend: Elixir/Phoenix

The API server is built with Elixir and Phoenix Framework, chosen for:

• Concurrency — Erlang/OTP lightweight processes handle millions of concurrent connections
• Fault Tolerance — Supervisor trees automatically restart failed processes
• Real-time — Phoenix Channels provide WebSocket support for live updates
• Performance — Sub-millisecond message passing between processes

Key libraries:

• Phoenix — Web framework with REST and WebSocket support
• Ecto — Database wrapper with migrations and query builder
• Guardian — JWT authentication
• Oban — Background job processing with PostgreSQL backing

Frontend: Vue 3

Three Vue 3 applications share a common component library:

App	Purpose	Port
Banking	Internet banking (PIX send/receive, statements, transfers)	3000
Admin	Operations console (user management, monitoring, CCS)	3001
Merchant	Merchant portal (API keys, transactions, settlements)	3002

Shared stack:

• Vue 3 with Composition API and <script setup>
• TypeScript for type safety
• Vite for fast development and optimized builds
• Tailwind CSS for styling
• Pinia for state management
• Vue Router for client-side navigation

Ledger: TigerBeetle

TigerBeetle is the purpose-built financial ledger providing:

• 77,000+ TPS sustained throughput (validated via load testing)
• Double-entry bookkeeping — Every transfer has balanced debits and credits
• Strong serializability — Viewstamped Replication consensus protocol
• Immutable transfers — Financial safety guarantees, no edits or deletes
• Deterministic execution — Same inputs always produce same outputs

The ledger handles all account balances and transfer records. PostgreSQL stores metadata (user profiles, merchant configs, API keys).

Automatic Failover

A circuit breaker pattern provides automatic failover from TigerBeetle to a PostgreSQL-based fallback ledger:

Normal:     Request → TigerBeetle (10K TPS, <10ms)
Failover:   Request → PostgreSQL Ledger (2K TPS, 45ms)
Recovery:   Request → TigerBeetle (automatic after health check passes)

Circuit states:

• Closed — All traffic to TigerBeetle (normal operation)
• Open — All traffic to PostgreSQL (after 3 consecutive failures)
• Half-Open — Test request to TigerBeetle (after 30s timeout)

Messaging: NATS JetStream

NATS with JetStream handles asynchronous event processing:

• PIX In/Out workflows — Multi-step payment processing
• Webhook delivery — Reliable notification dispatch with retries
• Ledger events — Account balance change notifications
• Audit logging — Immutable event stream for compliance

Streams configured:

• FLUXIQ — Main event stream (PIX transactions, account events)
• FLUXIQ_LEDGER — Ledger-specific events (balance changes, transfers)

Cache: Redis 7.2

Redis provides:

• Session caching — JWT token blacklisting and session data
• Rate limiting — Per-IP and per-API-key request throttling
• Idempotency keys — SHA256 hash caching for duplicate prevention (30-day TTL)
• Real-time data — Exchange rates, provider status, feature flags

Database: PostgreSQL 16

PostgreSQL stores all persistent data except ledger balances:

• Users, merchants, and role-based permissions
• Account metadata and product definitions
• Transaction metadata and audit trails
• COSIF chart of accounts (59 accounts, 5 types)
• CCS compliance records

Data Flow: PIX Payment

PIX In (Receiving a Payment)

1. Provider Webhook → Phoenix API
2. Validate signature (HMAC-SHA256)
3. Publish to NATS (FLUXIQ.pix.in)
4. Worker picks up event
5. Create transfer in TigerBeetle (debit provider, credit merchant)
6. Update PostgreSQL metadata
7. Notify merchant via webhook
8. Push real-time update via WebSocket

PIX Out (Sending a Payment)

1. Merchant API request → Phoenix API
2. Validate balance in TigerBeetle
3. Create pending transfer (debit merchant, credit provider)
4. Publish to NATS (FLUXIQ.pix.out)
5. Worker sends to PIX provider
6. Provider confirms → update transfer status
7. Notify merchant via webhook

Security

• mTLS — Mutual TLS for provider communication
• JWT — Token-based API authentication with refresh rotation
• RBAC — Role-based access control (owner/manager/operator)
• Rate Limiting — Per-IP and per-key limits with Redis backing
• Encryption — AES-256-GCM for sensitive data at rest
• Audit Trail — Complete operation logging for 5-year retention

Multi-Tenant Architecture

Institution A (ISPB: 12345678) ─┐
Institution B (ISPB: 87654321) ─┼─→ FluxiQ Core ─→ BACEN (PIX/CCS/COSIF)
Institution N (ISPB: nnnnnnnn) ─┘

Each institution has isolated:

• Database schemas (logical separation)
• TigerBeetle ledger codes
• NATS subject prefixes
• Redis key namespaces
• Monitoring dashboards