raymond6066/paygrid-africa

A resilient cloud-native payment orchestration, ledger and reconciliation platform for African payment systems. # PayGrid Africa PayGrid Africa does not move real money. It simulates a merchant payment platform that assumes upstream providers can time out, fail or return inconsistent records. The system accepts idempotent payment requests, routes them across synthetic providers, records balanced accounting journals, delivers signed webhooks and reconciles internal records against provider statements. ## What this release proves - **API engineering:** versioned REST API, validation, API-key authentication, rate limiting and Swagger documentation. - **Distributed workflows:** PostgreSQL state, Redis-backed BullMQ workers, retries and provider failover. - **Financial controls:** double-entry ledger journals, explicit fees, refunds, audit logs and reconciliation issues. - **Reliability engineering:** health checks, circuit breakers, Prometheus metrics and controllable provider failures. - **Security:** hashed merchant API keys, administrator separation, HMAC-signed webhooks, Helmet and secret-driven configuration. - **DevOps readiness:** Docker images, Docker Compose, Kubernetes manifests, CI, container scanning and k6 load tests. ## Architecture ```mermaid flowchart LR Merchant[Merchant client] -->|X-API-Key + Idempotency-Key| API[NestJS API] Console[Next.js operations console] -->|server-side admin proxy| API API --> PG[(PostgreSQL)] API --> Redis[(Redis / BullMQ)] Redis --> Worker[Payment worker] Worker --> Router[Weighted provider router] Router --> Nile[NILEPAY simulator] Router --> Kora[KORAMONEY simulator] Router --> Sahara[SAHARABANK simulator] Worker --> Ledger[Double-entry ledger] Worker --> ProviderBook[Provider transaction book] Worker --> WebhookQueue[Webhook queue] WebhookQueue --> Sink[Signed webhook receiver] Reconcile[Reconciliation engine] --> PG API --> Metrics[/Prometheus metrics/] ``` More detail: `docs/architecture.md`. ## Quick start with Docker Compose ### 1. Configure the project ```bash cp .env.example .env ``` Change the three demonstration se …