Getting Started

This guide walks you through setting up the FluxiQ PIX platform for local development.

Prerequisites

Ensure the following tools are installed on your development machine:

Tool	Version	Purpose
Elixir	>= 1.16	Backend services runtime
Erlang/OTP	>= 26	BEAM virtual machine
PostgreSQL	>= 15	Primary database
Redis	>= 7.0	Caching and session storage
NATS	>= 2.10	Inter-service messaging
Node.js	>= 22	Frontend build tooling
Docker	>= 24	Containerization

Repository Structure

The PIX project is organized as an Elixir umbrella application with separate frontend portals:

pix/
├── apps/
│   ├── shared/              # Shared schemas, BACEN client, auth
│   ├── dict_service/        # DICT API - PIX key directory (port 4001)
│   ├── spi_service/         # SPI - instant payments (port 4002)
│   └── settlement_service/  # Settlement + API gateway (port 4003)
├── frontend/
│   ├── admin/               # Admin portal (Vue 3 + PrimeVue)
│   └── user/                # User portal (Vue 3 + PrimeVue)
├── config/                  # Environment configuration
├── certs/                   # ICP-Brasil certificates (not in VCS)
├── docs-site/               # This documentation site
├── mix.exs                  # Umbrella project config
└── docker-compose.yml       # Local development stack

Quick Start

1. Clone and Install Dependencies

git clone https://github.com/fluxiq/pix.git
cd pix

# Install Elixir dependencies
mix deps.get

# Install frontend dependencies
cd frontend/admin && npm install && cd ../..
cd frontend/user && npm install && cd ../..

2. Start Infrastructure Services

docker compose up -d postgres redis nats

This starts PostgreSQL on port 5432, Redis on port 6379, and NATS on port 4222.

3. Set Up the Database

mix ecto.create
mix ecto.migrate
mix run apps/shared/priv/repo/seeds.exs

4. Configure Certificates

For local development, generate self-signed certificates:

mkdir -p certs
mix pix.gen.certs --env dev

For homologation or production, place your ICP-Brasil certificates in the certs/ directory:

certs/
├── client.pem        # Client certificate
├── client_key.pem    # Client private key
├── ca_chain.pem      # CA certificate chain
└── bacen_ca.pem      # BACEN root CA

5. Start the Backend Services

# Start all services in the umbrella
mix phx.server

# Or start individual services
cd apps/dict_service && mix phx.server     # Port 4001
cd apps/spi_service && mix phx.server      # Port 4002
cd apps/settlement_service && mix phx.server # Port 4003

6. Start the Frontend Portals

# Admin portal
cd frontend/admin
npm run dev    # http://localhost:3000

# User portal
cd frontend/user
npm run dev    # http://localhost:3001

7. Verify the Setup

Once all services are running, verify the health endpoints:

# DICT Service
curl http://localhost:4001/health

# SPI Service
curl http://localhost:4002/health

# Settlement Service
curl http://localhost:4003/health

Environment Variables

Key environment variables for local development:

# Database
DATABASE_URL=postgres://postgres:postgres@localhost:5432/pix_dev

# Redis
REDIS_URL=redis://localhost:6379/0

# NATS
NATS_URL=nats://localhost:4222

# BACEN endpoints (homologation)
DICT_BASE_URL=https://dict-h.pi.rsfn.net.br:16522/api/v2
SPI_BASE_URL=https://spi-h.pi.rsfn.net.br:16522

# mTLS certificates
CERT_PATH=./certs/client.pem
KEY_PATH=./certs/client_key.pem
CA_PATH=./certs/ca_chain.pem

# ISPB (your institution's identifier)
ISPB=12345678

# Secret key base
SECRET_KEY_BASE=your-secret-key-base-here

Running Tests

# Run all tests
mix test

# Run tests for a specific app
mix test --app dict_service
mix test --app spi_service
mix test --app settlement_service

# Run with coverage
mix test --cover

# Run frontend tests
cd frontend/admin && npm test
cd frontend/user && npm test

Next Steps

• Read the Architecture Overview to understand the system design
• Learn about BACEN Integration for PIX connectivity
• Explore the DICT Service for key management
• Review the API Reference for endpoint details