mid-night-codes/africa-local

Local-first emulator platform for African digital services — payments, SMS, USSD, banking, identity, and more. # Africa Local **A local-first emulator platform for African digital services.** Run deterministic, production-like emulators for mobile money, SMS, USSD, identity, and banking APIs on your own machine - no real provider sandboxes, no real credentials, no real money. > **Status: early-stage (v0.1).** One category (mobile money) and two providers (both Tanzania) > are implemented. Read Known Limitations before relying on this for > anything beyond local development and CI. ## What Africa Local is - A single local runtime that emulates real-world African provider APIs (starting with mobile money) behind deterministic, scriptable scenarios: success, insufficient funds, timeout, cancellation, delayed success, duplicate callbacks, missing callbacks, provider unavailability. - Plugin-based: a provider is a manifest + JSON Schemas + mapping tables + scenario files, not a block of provider-specific code (see ARCHITECTURE.md). - Spec-first: the source of truth is `specs/` (JSON Schema, state machines, Markdown contracts) and `contracts/` (OpenAPI/AsyncAPI) - not any one programming language. ## What Africa Local is not - Not a real payment switch, aggregator, financial institution, credential broker, settlement engine, or PCI card platform. - Not connected to any real provider, real account, or real money, ever. - Not (yet) a multi-tenant SaaS, a Kubernetes operator, or anything with a database - v0.1 is a single local process with in-memory state, by design (see ROADMAP.md). ## Quick start ```bash git clone cd africa-local make setup make validate make test docker compose up ``` Then: ```bash curl localhost ``` If port 9000 is already taken on your machine (e.g. by MinIO, which defaults to the same port), override it: `AFRICA_LOCAL_PORT=9001 docker compose up`. Without Docker: ```bash npm run setup npm start ``` ## Supported providers | Provider | Country | Category | Status | |---|---|---|---| | M-Pesa (`tz-mpesa`) | TZ | mobile-m …