# Introduction to FluxiQ PIX

A complete platform for processing PIX instant payments, designed for financial institutions and payment service providers requiring full compliance with Banco Central do Brasil (BCB) regulations.

## What is FluxiQ PIX

FluxiQ PIX is a financial infrastructure solution that implements the complete PIX instant payment ecosystem as defined by Brazil's Central Bank. The platform processes real-time transactions targeting 5,000 TPS sustained and 7,500 TPS burst, meeting the Service Level Agreement (ANS) requirement of settlement within 1.6 seconds.

## Problems FluxiQ PIX Solves

- **Regulatory complexity**: Complete implementation of DICT v2.10.0, SPI (ISO 20022), MED 2.0, and ANS protocols, eliminating the need for in-house development of these integrations
- **High availability**: Distributed architecture with circuit breakers, adaptive backpressure, and parallel NATS workers for 24/7/365 operation
- **Security**: Granular RBAC, MFA (TOTP), mTLS with ICP-Brasil certificates, XMLDSig RSA-SHA256, token blacklist, and rate limiting
- **Multi-cloud**: Deploy on AWS, GCP, Azure, OCI, or on-premises with Docker Compose or Kubernetes
- **Integrated accounting**: COSIF chart of accounts (BCB Circular 4010) with 44 accounts and double-entry journal postings
- **Real-time monitoring**: WebSocket dashboard, Prometheus metrics, health checks, and infrastructure alerts

## Core Capabilities

| Capability | Description |
|------------|-------------|
| **DICT** | Transactional Account Identifier Directory -- registration, lookup, claim, and portability of PIX keys (CPF, CNPJ, phone, email, EVP) |
| **SPI** | Instant Payment System -- processing ISO 20022 messages (pacs.008, pacs.002, pacs.004, pacs.028) |
| **MED 2.0** | Special Return Mechanism -- opening, analysis, and closing of infraction reports for fraud recovery |
| **Settlement** | Settlement cycles, netting, reconciliation, and balance management between participants |
| **Accounting** | COSIF chart of accounts, double-entry journal postings, cost centers, accounting events |
| **Monitoring** | Real-time dashboard with 6 WebSocket channels, Prometheus metrics, health checks, infrastructure alerts |
| **BACEN Simulator** | Integrated simulator for testing without real Central Bank connectivity (8 pre-configured scenarios) |

## Target Audience

- **Financial institutions** (banks, credit unions, finance companies) operating as direct SPI participants
- **Payment service providers (PSPs)** processing PIX as indirect participants
- **Fintechs** requiring complete PIX infrastructure and regulatory compliance
- **System integrators** implementing PIX solutions for financial sector clients

## Prerequisites

To use this documentation, you should have basic knowledge of:

- PIX ecosystem concepts (DICT, SPI, participants)
- Docker and container orchestration (Docker Compose or Kubernetes)
- PostgreSQL database administration
- HTTP/REST protocols and messaging (NATS JetStream)

## Architecture Overview

FluxiQ PIX consists of 4 Elixir/Phoenix applications in an umbrella architecture, a Vue 3 admin portal, and external integrations with the Central Bank, Core Banking, and API clients.

```mermaid
graph TB
    subgraph Clients
        WEB[Admin Portal<br/>Vue 3 + Tailwind]
        API_CLIENT[API Clients<br/>REST / Webhook]
    end

    subgraph FluxiQ PIX
        GW[Settlement Service<br/>API Gateway :4003]
        DICT[Dict Service<br/>DICT v2.10 :4001]
        SPI[SPI Service<br/>ISO 20022 :4002]
        SHARED[Shared<br/>Auth, Crypto, DB, NATS]

        GW --> DICT
        GW --> SPI
        DICT --> SHARED
        SPI --> SHARED
        GW --> SHARED
    end

    subgraph Infrastructure
        PG[(PostgreSQL 16<br/>8 schemas)]
        REDIS[(Redis 7<br/>Cache + Rate Limit)]
        NATS[NATS JetStream<br/>7 streams]
    end

    subgraph External Integrations
        BACEN[Central Bank<br/>DICT API + SPI]
        CORE[Core Banking<br/>NATS Events]
    end

    WEB -->|HTTPS + WSS| GW
    API_CLIENT -->|HTTPS + Webhook| GW

    GW --> PG
    GW --> REDIS
    GW --> NATS

    DICT --> PG
    SPI --> PG
    SPI --> NATS

    DICT -.->|mTLS + XMLDSig| BACEN
    SPI -.->|mTLS + XMLDSig| BACEN
    NATS <-.->|JetStream Events| CORE
```

## Expected Outcome

After reading this introduction, you will have an overview of the FluxiQ PIX platform capabilities and be ready to explore the following topics:

- [System Architecture](./architecture.md) -- technical details of the internal architecture
- [Requirements](./requirements.md) -- hardware, software, and certificate requirements
- [Quick Start](./quick-start.md) -- deploy in 15 minutes with Docker Compose
- [PIX Concepts](./concepts.md) -- glossary and fundamental PIX ecosystem concepts