Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• Elixir 1.17+ and Erlang/OTP 27+
• Node.js 20+ and pnpm 9+
• Docker and Docker Compose v2
• PostgreSQL 16 (or use Docker)
• Redis 7.2 (or use Docker)

Project Structure

fluxiq-core/
├── apps/
│   ├── banking/          # Vue 3 internet banking UI
│   ├── admin/            # Vue 3 admin console
│   └── merchant/         # Vue 3 merchant portal
├── backend/              # Elixir/Phoenix API server
├── packages/
│   └── shared/           # Shared TypeScript utilities
├── docs-site/            # VitePress documentation (you are here)
├── infrastructure/
│   ├── docker/           # Docker Compose for local dev
│   ├── k8s/              # Kubernetes manifests
│   └── monitoring/       # Grafana dashboards and alerts
├── docker-compose.yml    # Root compose (infra + apps)
└── pnpm-workspace.yaml   # Monorepo workspace config

Quick Start

1. Clone the Repository

git clone https://github.com/fluxiq/fluxiq-core.git
cd fluxiq-core

2. Start Infrastructure Services

Launch PostgreSQL, Redis, NATS, and TigerBeetle:

docker compose -f infrastructure/docker/docker-compose.yml up -d

Verify all services are running:

docker compose -f infrastructure/docker/docker-compose.yml ps

3. Set Up the Backend

cd backend

# Install Elixir dependencies
mix deps.get

# Create and migrate the database
mix ecto.setup

# Start the Phoenix server
mix phx.server

The API will be available at http://localhost:4000.

4. Set Up the Frontend Apps

# From the root directory
pnpm install

# Start all frontend apps in parallel
pnpm dev

# Or start individual apps
pnpm dev:banking   # Internet banking UI on port 3000
pnpm dev:admin     # Admin console on port 3001
pnpm dev:merchant  # Merchant portal on port 3002

5. Start the Documentation Site

pnpm dev:docs

The docs will be available at http://localhost:5173.

Environment Variables

Create a .env file in the backend directory:

# Database
DATABASE_URL=postgres://fluxiq:fluxiq@localhost:5432/fluxiq_dev

# Redis
REDIS_URL=redis://localhost:6379

# NATS
NATS_URL=nats://localhost:4222

# TigerBeetle
TIGERBEETLE_ADDRESSES=localhost:3001

# Authentication
SECRET_KEY_BASE=your-secret-key-base-at-least-64-chars
GUARDIAN_SECRET_KEY=your-guardian-jwt-secret

# PIX Provider (development)
PIX_PROVIDER=sandbox
PIX_PROVIDER_API_URL=https://api-sandbox.provider.com.br
PIX_PROVIDER_CLIENT_ID=your-client-id
PIX_PROVIDER_CLIENT_SECRET=your-client-secret

Running Tests

Backend Tests

cd backend
mix test              # All tests
mix test --only unit  # Unit tests only
mix test --cover      # With coverage report

Frontend Tests

pnpm test             # All frontend tests
pnpm test:banking     # Banking app tests
pnpm test:admin       # Admin app tests

Next Steps

• Read the Architecture overview to understand the system design
• Explore the API Reference for endpoint documentation
• Check Deployment for production deployment instructions