Skip to content

README.md

Latest commit

 

History

History
282 lines (203 loc) · 9.22 KB

README.md

File metadata and controls

282 lines (203 loc) · 9.22 KB

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

cd backend
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:3000 (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

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

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

  • Swagger UI: http://localhost:3000/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 repo docs: API and Contracts Reference.

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
  • 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

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

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

License

Apache License 2.0