ACBU Backend API

Backend API server for the ACBU (African Currency Basket Unit) platform.

Technology Stack

• Runtime: Node.js 20+ with TypeScript
• Framework: Express.js
• Database: Prisma Accelerate (managed PostgreSQL; no local PostgreSQL)
• Cache: MongoDB Atlas (managed; no local MongoDB)
• Message Queue: RabbitMQ
• Testing: Jest
• Logging: Winston
• Development: Nodemon

Prerequisites

• Node.js 20 or higher
• Docker and Docker Compose
• pnpm 10+ (Required package manager)

Setup Instructions

1. Clone and Install

pnpm install

2. Environment Configuration

Copy the example environment file and configure it:

cp .env.example .env

Edit .env and configure:

• Prisma Accelerate URL (PRISMA_ACCELERATE_URL) as the runtime database connection; DATABASE_URL for migrations if your setup uses it
• MongoDB Atlas connection string (MONGODB_URI), e.g. mongodb+srv://...
• RabbitMQ URL (or use a managed queue)
• API keys for fintech partners (Flutterwave, etc.)
• JWT secrets
• Other service configurations

Database URL Matrix

Two separate environment variables serve distinct purposes — using the wrong one for the wrong purpose causes silent failures or boot errors.

Variable	Protocol	Used by	Must NOT be used for
DATABASE_URL	postgresql:// or postgres://	prisma migrate (schema migrations)	Runtime app server; Prisma Accelerate
PRISMA_ACCELERATE_URL	prisma:// or prisma+postgres://	App server at runtime (connection pooling, caching)	Migrations (prisma migrate will fail with this URL)

Rules:

• DATABASE_URL must always be a direct PostgreSQL connection string. The server asserts this at boot and will refuse to start if it detects a prisma:// protocol here.
• PRISMA_ACCELERATE_URL is optional. When set, the app uses it for all runtime queries. When absent, the app falls back to DATABASE_URL directly (suitable for local dev).
• Never run pnpm prisma:migrate pointing at PRISMA_ACCELERATE_URL. Always run migrations against the direct DATABASE_URL.
• The boot log prints which URL type is active: Runtime connection: Prisma Accelerate (pooled) or Runtime connection: direct PostgreSQL.

3. Message queue and optional local services

The app uses Prisma Accelerate and MongoDB Atlas; it does not require local PostgreSQL or MongoDB. You need a RabbitMQ instance (e.g. from Docker or a managed provider).

To run only RabbitMQ via Docker:

docker-compose up -d rabbitmq

RabbitMQ will be on port 5672 (Management UI: http://localhost:15672).

The same docker-compose.yml can start local PostgreSQL and MongoDB for migrations or local dev; use those services only if you need them.

4. Database Setup

Initialize Prisma and run migrations:

# Generate Prisma Client
pnpm prisma:generate

# Run database migrations
pnpm prisma:migrate

# (Optional) Seed database
pnpm prisma:seed

5. Start Development Server

pnpm dev

The server will start on http://localhost:5000 (or the port specified in .env).

Nodemon will automatically restart the server when you make changes to the code.

Available Scripts

• pnpm dev - Start development server with hot reloading
• pnpm build - Build TypeScript to JavaScript
• pnpm start - Start production server
• pnpm test - Run tests
• pnpm lint - Run ESLint
• pnpm lint:fix - Fix ESLint errors
• pnpm format - Format code with Prettier
• pnpm format:check - Check code formatting
• pnpm prisma:generate - Generate Prisma Client
• pnpm prisma:migrate - Run database migrations
• pnpm prisma:studio - Open Prisma Studio
• pnpm prisma:seed - Seed database with initial data
• pnpm changelog - Regenerate the full CHANGELOG.md from all git history
• pnpm changelog:update - Append the latest unreleased changes to CHANGELOG.md (after tagging a release)

Release & Versioning Strategy

The backend follows semantic versioning and expects all release artifacts to be tagged consistently.

• Versioning format: vMAJOR.MINOR.PATCH and optional pre-release suffixes such as v1.2.0-rc.1
• MAJOR: breaking API or protocol changes
• MINOR: backward-compatible features or new endpoints
• PATCH: bug fixes, hardening, and compatibility patches
• Release changes should be documented in CHANGELOG.md and reflected in the Git tag workflow used by the release pipeline

For the maintainers' checklist and the recommended release flow, see RELEASE.md and docs/RELEASING.md.

Project Structure

backend/
├── src/
│   ├── config/          # Configuration files
│   ├── controllers/     # Route controllers
│   ├── services/        # Business logic services
│   ├── models/          # Data models
│   ├── routes/          # API routes
│   ├── middleware/      # Express middleware
│   ├── utils/           # Utility functions
│   └── types/           # TypeScript type definitions
├── tests/               # Test files
├── prisma/              # Prisma schema and migrations
├── scripts/             # Utility scripts
├── docker-compose.yml   # Docker services configuration
└── package.json

API Documentation

For the proposed alignment of partner reconciliation, attestation, and audit requirements (W10-DOC-016), see Partner audit cadence proposal. The proposal includes source-document integration steps pending maintainer review.

Once the server is running, API documentation is available at:

• Swagger UI: http://localhost:5000/api-docs (development only, disabled in production for security)

Segment routes (require API key with segment scope): /v1/p2p, /v1/sme, /v1/international, /v1/salary, /v1/enterprise, /v1/savings, /v1/lending, /v1/gateway, /v1/bills. For a full list of routes and smart contracts, see the repository docs in the docs/ folder.

Signature Encoding Conventions

This API uses different signature encodings depending on the protocol and transport layer. The encoding should be treated as part of the contract and documented consistently to avoid verification failures.

• Webhook HMAC signatures: hex strings, typically generated as crypto.createHmac(...).digest("hex") and verified by comparing Buffer.from(signature, "hex")
• JWT and URL-safe token payloads: base64url encoding, such as the standard JSON Web Token header/payload format
• Ed25519/Stellar keys: base32/checksum encoded public keys or raw secret-key formats, not plain hex unless the specific library or API explicitly requires it

When a verifier expects hex, the sender must send a lowercase or uppercase hex digest exactly as specified; when a verifier expects base64url, the value must be base64url-encoded and not hex. The same API should not mix encodings for the same signing scheme without explicit documentation.

Database Management

Prisma Studio

View and edit database data using Prisma Studio:

pnpm prisma:studio

Migrations

Create a new migration:

pnpm prisma:migrate

Testing

Run all tests:

pnpm test

Run tests with coverage:

pnpm test:coverage

Environment Variables

Full list: See ENV_VARS.md. No mock data; all values must be real or explicitly empty.

Required: DATABASE_URL (migrations / fallback), MONGODB_URI (MongoDB Atlas), RABBITMQ_URL, JWT_SECRET. Runtime DB: Prisma Accelerate via PRISMA_ACCELERATE_URL (see ENV_VARS.md).

Fintech: Flutterwave (FLUTTERWAVE_SECRET_KEY, etc.), Paystack (PAYSTACK_SECRET_KEY), MTN MoMo (MTN_MOMO_SUBSCRIPTION_KEY, MTN_MOMO_API_USER_ID, MTN_MOMO_API_KEY). Optional: FINTECH_CURRENCY_PROVIDERS.

Stellar: STELLAR_NETWORK, STELLAR_SECRET_KEY, and after deploy: CONTRACT_ORACLE, CONTRACT_RESERVE_TRACKER, CONTRACT_MINTING, CONTRACT_BURNING. Optional for segment features: CONTRACT_SAVINGS_VAULT, CONTRACT_LENDING_POOL, CONTRACT_ESCROW.

Stellar Fee Configuration: Control transaction fees under varying network congestion:

• STELLAR_USE_DYNAMIC_FEES=true - Fetch live base fee from Horizon before each transaction (recommended for production)
• STELLAR_BASE_FEE_STROOPS=100 - Fallback base fee when dynamic fetch unavailable (default: 100)
• STELLAR_SOROBAN_MIN_FEE_STROOPS=5000 - Minimum total fee for Soroban transactions to prevent underpricing (default: 5000)
• STELLAR_SOROBAN_MAX_FEE_STROOPS=10000000 - Maximum total fee for Soroban transactions to prevent overpaying (~50 XLM at base=100; default: 10M stroops)

Docker Services

With Prisma Accelerate and MongoDB Atlas, the app does not use local PostgreSQL or MongoDB. Only RabbitMQ is required from Docker (or use a managed RabbitMQ). The compose file also defines optional postgres and mongodb services for migrations or local development.

Accessing Services

• RabbitMQ Management UI: http://localhost:15672 (username: acbu, password: acbu_password)
• Optional local Postgres: localhost:5432 (if running docker-compose up -d postgres)
• Optional local MongoDB: localhost:27017 (if running docker-compose up -d mongodb)

Stopping Services

docker-compose down

Viewing Logs

docker-compose logs -f

Health Check Endpoints

The API provides three health check endpoints with different purposes:

/health - Shallow Liveness Check

• Path: GET /api/v1/health
• Status: Always returns 200 OK
• Purpose: For load balancers to verify the process is alive
• Response: { status: "ok", timestamp, uptime, version }
• Note: Does not probe dependencies; fast and reliable

/health/ready - Kubernetes Readiness Probe

• Path: GET /api/v1/health/ready
• Status: Returns 200 if all dependencies up, 503 if any down
• Purpose: For Kubernetes readinessProbe configurations
• Probes: PostgreSQL, MongoDB, RabbitMQ
• Startup Guard: Returns 503 during application startup until all infrastructure connections and background jobs are fully initialized, preventing load balancers from routing traffic to partially-initialized instances
• Recommendation: Use this endpoint in K8s deployment readinessProbe

/health/deep - Deep Health Check

• Path: GET /api/v1/health/deep
• Status: Returns 200 if all dependencies up, 503 if any down
• Purpose: Detailed dependency status for monitoring dashboards
• Response: Full report with status of each dependency
• Startup Guard: Returns 503 during application startup until all infrastructure connections and background jobs are fully initialized

Kubernetes Configuration Example

readinessProbe:
  httpGet:
    path: /api/v1/health/ready
    port: 5000
  initialDelaySeconds: 5
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

livenessProbe:
  httpGet:
    path: /api/v1/health
    port: 5000
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

CI/CD

GitHub Actions CI pipeline runs on:

• Push to main, dev, or develop branches
• Pull requests to main, dev, or develop

The CI pipeline:

• Runs linter and formatter checks
• Runs all tests
• Builds the project
• Validates database migrations
• Blocks destructive Prisma migrations unless the pull request carries the allow-destructive-migration label

Recent Changes

Features

• Transfer service (b6b7036): Implemented createTransfer in transferService.ts with input validation, KYC checks, and blockchain transaction handling, along with full unit test coverage in tests/transfer.test.ts
• Float-interest revenue & segregated partner reserves (W10-S-012, #1141): Resolved revenue model contradiction where float interest was assumed on partner-held segregated reserves. Established conservative baseline zeroing uncontracted partner float ($0.00), defined the Partner Reserve & Interest Agreement (PRIA) framework for conditional entitlement, re-ran breakeven projections to $442M volume, and implemented programmatic governance in FloatRevenueService.

Roadmap

For the ACBU platform development roadmap with committed timelines, owners, dependencies, and acceptance criteria, see docs/ROADMAP.md.

Contributing

1. Create a feature branch
2. Make your changes
3. Run tests and linter: pnpm test && pnpm lint
4. Commit and push
5. Create a pull request (prefer relative references like #123 instead of hardcoded github.com/<owner>/... links)

License

Apache License 2.0