Getting Started

This guide walks you through setting up the FluxiQ SPB platform for local development and connecting to the BACEN simulator.

Prerequisites

Before you begin, ensure you have the following installed:

Tool	Version	Purpose
Elixir	>= 1.16	Microservice runtime
Erlang/OTP	>= 26	BEAM virtual machine
Node.js	>= 22	Vue 3 frontend
Docker	>= 24	Container runtime
Docker Compose	>= 2.20	Local orchestration
PostgreSQL	>= 16	Primary database
IBM MQ	>= 9.3	BACEN message queue (or use the simulator)

Quick Start with Docker Compose

The fastest way to get the entire platform running locally is with Docker Compose. This starts all 11 services, the Vue 3 frontend, the BACEN simulator, PostgreSQL, and IBM MQ.

# Clone the repository
git clone https://github.com/fluxiq/spb.git
cd spb

# Copy the example environment file
cp .env.example .env

# Start all services
docker compose up -d

# Verify all services are healthy
docker compose ps

After startup, the following endpoints are available:

Service	URL	Description
Vue 3 Frontend	http://localhost:3000	Web application
API Gateway	http://localhost:4000	REST/GraphQL entry point
Auth Service	http://localhost:4001	Authentication endpoints
BACEN Gateway	http://localhost:4002	BACEN message interface
Message Processor	http://localhost:4003	Broadway pipeline metrics
BACEN Simulator	http://localhost:4020	Simulated BACEN/RSFN
Grafana	http://localhost:3001	Observability dashboards

Environment Configuration

The .env file controls runtime behavior. Key variables:

# Database
DATABASE_URL=ecto://postgres:postgres@localhost:5432/spb_dev

# Authentication
JWT_SECRET=your-secret-key-min-64-chars
JWT_TTL=3600

# BACEN Connection
BACEN_MODE=simulator           # "simulator" or "production"
BACEN_ISPB=12345678            # Your institution's ISPB code
BACEN_MQ_HOST=localhost
BACEN_MQ_PORT=1414
BACEN_MQ_CHANNEL=BACEN.SVRCONN
BACEN_MQ_QUEUE_MANAGER=QM1

# Message Processing
BROADWAY_CONCURRENCY=10
BROADWAY_MAX_DEMAND=50

First API Call

Once the platform is running, authenticate and send your first request:

# 1. Authenticate to get a JWT token
TOKEN=$(curl -s -X POST http://localhost:4000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin@fluxiq.dev", "password": "admin123"}' \
  | jq -r '.data.token')

# 2. Check your institution's STR balance
curl -s http://localhost:4000/api/v1/str/balance \
  -H "Authorization: Bearer $TOKEN" \
  | jq .

# 3. Send a TED transfer
curl -s -X POST http://localhost:4000/api/v1/transactions/ted \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_ispb": "12345678",
    "receiver_ispb": "87654321",
    "amount": "15000.00",
    "purpose": "payment",
    "sender_account": "00012345",
    "receiver_account": "00098765"
  }' | jq .

Running Individual Services

For development, you may want to run individual services outside Docker:

# Start a single service (e.g., api_gateway)
cd services/api_gateway
mix deps.get
mix ecto.setup
mix phx.server

# Run tests
mix test

# Run with IEx for interactive debugging
iex -S mix phx.server

Using the BACEN Simulator

The BACEN simulator replicates the behavior of BACEN's RSFN network, including:

• Message validation against official XSD schemas
• Settlement window timing (STR operates 06:30 to 17:30 BRT)
• Response message generation (R1, R2, R3 responses)
• Error scenarios and rejection codes

# Access the simulator dashboard
open http://localhost:4020

# Trigger a simulated BACEN settlement window
curl -X POST http://localhost:4020/simulator/settlement-window/open

# Inject a simulated BACEN message
curl -X POST http://localhost:4020/simulator/inject \
  -H "Content-Type: application/xml" \
  -d @test/fixtures/bacen/str0001.xml

Next Steps

• Read the Architecture Overview to understand how the 11 services interact
• Learn about BACEN Message Types supported by the platform
• Explore the API Reference for all available endpoints
• Set up Docker deployment for staging environments