🌍 AFRAMP: Africa's Financial Bridge

Don't Trust, Verify

AFRAMP is a blockchain payment platform designed specifically for the African market, enabling seamless conversion between local currencies and digital assets. We specialize in onramp (fiat-to-crypto) and offramp (crypto-to-fiat) transactions using African stablecoins and provide essential services like bill payments.

Built on the Stellar network with multi-chain compatibility, AFRAMP connects traditional African financial systems (like mobile money and local banks) to global blockchain ecosystems. Our platform tackles the high costs and slow speeds of cross-border payments by leveraging blockchain for near-instant, low-fee settlements.

Who It's For

• African Users & Diaspora: Send remittances, pay bills, and manage finances with minimal fees.
• Businesses & Developers: Integrate pan-African payments and treasury solutions.
• Contributors: Help build the future of African fintech with open, verifiable systems.

---

🏗️ Project Structure

The AFRAMP frontend repository is organized for clarity and scalability:

Aframp/
├── public/                 # Static assets
├── app/                    # Next.js App Router
│   ├── (app)/            # Authenticated routes
│   ├── layout.tsx        # Root layout
│   └── page.tsx          # Auth/login page
├── components/             # Reusable UI components
├── lib/                    # Utilities, API client, types
├── .env.example           # Environment variables template
├── package.json
└── README.md

Architecture Decisions

• ADR 001: Keep Backend Requests Behind a Same-Origin Proxy

---

� API Reference

The client-side contract is documented in the repository root OpenAPI file:

• openapi.yaml

This spec covers the backend endpoints used by the frontend in lib/api.ts.

PWA Status

Offline caching and installable PWA support are currently disabled. Web Push payment alerts remain available through a push-only service worker; the app does not cache pages or API data for offline use.

�🚀 Quick Start (5 Minutes)

Get AFRAMP running locally in under 5 minutes with our automated setup script or manual installation.

⚠️ Port constraint — read this first. The backend binds port 3000 and its CORS_ALLOWED_ORIGINS defaults to http://localhost:3001. The frontend must therefore run on 3001, not Next.js's default 3000. If you start the app on 3000, every API request will fail with a silent CORS/network error. Set NEXT_PUBLIC_API_URL to point at the backend and run the frontend on 3001 (see .env.example).

Automated Setup (Easiest) ⚡

Linux/Mac:

git clone https://github.com/your-org/Aframp.git
cd Aframp
chmod +x scripts/setup.sh
./scripts/setup.sh

Windows (PowerShell):

git clone https://github.com/your-org/Aframp.git
cd Aframp
.\scripts\setup.ps1

The script will:

• ✅ Check prerequisites (Node.js, Docker)
• ✅ Create .env.local from template
• ✅ Let you choose Docker or Node.js setup
• ✅ Install dependencies and start the app

Access the app at http://localhost:3001 ✅

Manual Setup

Option 1: Docker (Recommended) 🐳

Prerequisites: Docker & Docker Compose installed

# Clone and start
git clone https://github.com/your-org/Aframp.git
cd Aframp
cp .env.example .env.local
docker-compose -f docker-compose.dev.yml up

Access the app at http://localhost:3001 ✅ (the frontend is mapped to 3001 so it matches the backend's default CORS_ALLOWED_ORIGINS; see docker-compose.dev.yml).

Option 2: Node.js

Prerequisites: Node.js v20+ & npm

# Clone and install
git clone https://github.com/your-org/Aframp.git
cd Aframp
npm install

# Configure and run
cp .env.example .env.local
npm run dev -- -p 3001

Access the app at http://localhost:3001 ✅ (run on 3001 so the backend's default CORS_ALLOWED_ORIGINS=http://localhost:3001 accepts your requests).

---

🔧 Environment Variables

Copy .env.example to .env.local and configure the following. This table is generated from .env.example — run npm run docs:env after editing that file to regenerate it, rather than hand-editing the table below; CI fails if the two ever drift apart.

Variable	Type	Required	Default	Example
NEXT_PUBLIC_API_URL	string (URL)	Yes	—	http://127.0.0.1:3000
NEXT_PUBLIC_STELLAR_NETWORK	string (enum: testnet	public)	No	testnet
NEXT_PUBLIC_SENTRY_DSN	string (Sentry DSN URL)	No	(unset — client-side error reporting disabled)	https://examplePublicKey@o0.ingest.sentry.io/0
SENTRY_DSN	string (Sentry DSN URL)	No	(falls back to NEXT_PUBLIC_SENTRY_DSN, then disabled)	https://examplePrivateKey@o0.ingest.sentry.io/1
SENTRY_AUTH_TOKEN	string (Sentry auth token)	No	(unset — source map upload skipped)	sntrys_eyJpYXQiOjE3MDAwMDAwMDAuMCwidXJsIjoiaHR0cHM6Ly9zZW50cnkuaW8ifQ==
SENTRY_ORG	string	No	(unset — source map upload skipped)	aframp
SENTRY_PROJECT	string	No	(unset — source map upload skipped)	aframp-pay
NEXT_PUBLIC_PAYSTACK_PUBLIC_KEY	string (Paystack public key)	No	(unset — Paystack hidden from the onramp provider selector)	pk_test_examplekey1234567890
NEXT_PUBLIC_FLUTTERWAVE_PUBLIC_KEY	string (Flutterwave public key)	No	(unset — Flutterwave hidden from the onramp provider selector)	FLWPUBK_TEST-1234567890abcdef1234567890abcdef-X
NEXT_PUBLIC_CNGN_ISSUER	string (Stellar account address, G...)	No	(unset — cNGN charges disabled, shown as "Coming soon")	GCNGNEXAMPLE234567890234567890234567890234567890234

🐳 Docker Deployment

Development

# Start with hot-reload
docker-compose up

# Rebuild after dependency changes
docker-compose up --build

# Run in background
docker-compose up -d

# View logs
docker-compose logs -f

# Stop containers
docker-compose down

⚠️ The dev compose file maps the frontend to port 3001 because the backend binds 3000 and only allows http://localhost:3001 by default via CORS_ALLOWED_ORIGINS. See docker-compose.dev.yml for the inline explanation.

Production

# Build production image
docker build -t aframp:latest .

# Run production container
docker run -p 3001:3001 --env-file .env.local aframp:latest

# Or use docker-compose
docker-compose -f docker-compose.prod.yml up -d

Docker Environment Variables

Pass environment variables via:

• .env.local file (recommended)
• Docker Compose environment section
• docker run -e flags

---

🚀 Backend Deployment

Vercel (Recommended)

1. Connect Repository

   • Go to vercel.com
   • Import your GitHub repository
   • Select the Aframp project

2. Configure Environment Variables

   • In Vercel dashboard → Settings → Environment Variables
   • Add all variables from .env.example
   • Set NEXT_PUBLIC_DEMO_MODE=false for production

3. Deploy

   • Vercel auto-deploys on push to main
   • Preview deployments for PRs
   • Production URL: https://your-project.vercel.app

Other Platforms

Railway

# Install Railway CLI
npm i -g @railway/cli

# Login and deploy
railway login
railway init
railway up

Render

1. Create new Web Service
2. Connect GitHub repository
3. Build Command: npm run build
4. Start Command: npm start
5. Add environment variables in dashboard

AWS/GCP/Azure

Use the provided Dockerfile for containerized deployment:

# Build and push to container registry
docker build -t aframp:latest .
docker tag aframp:latest your-registry/aframp:latest
docker push your-registry/aframp:latest

# Deploy using your platform's container service
# (ECS, Cloud Run, Container Apps, etc.)

---

🛠️ Troubleshooting

All API calls fail with a network error

If every request to the backend fails (browser console shows CORS errors or net::ERR_FAILED), you are almost certainly running the frontend on the wrong port.

• The backend binds port 3000 and its CORS_ALLOWED_ORIGINS defaults to http://localhost:3001.
• Next.js defaults to port 3000, which collides with the backend and is not in the allowed origins list.

Fix: run the frontend on 3001 and point it at the backend:

# Node.js
npm run dev -- -p 3001

# Docker (already configured in docker-compose.dev.yml)
docker-compose -f docker-compose.dev.yml up

Make sure .env.local sets NEXT_PUBLIC_API_URL to the backend URL (e.g. http://localhost:3000) and that the backend's CORS_ALLOWED_ORIGINS includes your frontend origin (http://localhost:3001 by default). See .env.example for details.

---

📦 Available Scripts

Command	Description

Built for Africa, Verified by Blockchain. Onramp to the future. Offramp to opportunity. 🔗🌍

Handsoff notes