Infrastructure
Complete server architecture showing how every component in the Keshless platform communicates — clients, backend services, databases, storage, external integrations, and scheduled jobs.
System Overview
Network & DNS Routing
All traffic flows through HTTPS. Mobile apps and the dashboard never talk to the database directly — everything goes through the API.
| Domain | Points To | Purpose |
|---|---|---|
api.keshless.com | Cloud Run — keshless-api | Production API |
dev-api.keshless.com | Cloud Run — keshless-api-dev | Development API |
ussd.keshless.com | Cloud Run — keshless-ussd | USSD callbacks + Swazi Mobile proxy |
dashboard.keshless.com | Cloudflare Pages | Admin dashboard (React) |
keshless.com | Cloudflare Pages | Public website |
Request Flow
Authentication Flows
Three distinct auth mechanisms for different client types, plus API key auth for partners.
User Authentication (Phone + OTP)
Vendor Authentication (Email + Password + Device)
Admin Authentication
Partner API Authentication
Data Flow: Payment Transaction
Every payment creates balanced double-entry accounting records. Here's a user-to-vendor payment:
KYC Verification Flow
Documents are stored in GCS with signed URLs — never public. Verification uses AWS for face matching and OCR.
Scheduled Jobs
Cloud Scheduler triggers jobs via authenticated HTTP calls to the API. Each job endpoint validates the X-Job-Secret header.
| Job | Schedule | Endpoint | What It Does |
|---|---|---|---|
| PostgreSQL Backup | Daily 2 AM | /backup-jobs/backup | Full database dump to GCS |
| Secrets Backup | Daily 3 AM | /backup-jobs/secrets | Export GCP secrets (AES-256-GCM encrypted) to GCS |
| Sanctions Sync | Daily 3 AM | /sanctions-jobs/sync | Download UN sanctions list, fuzzy-match against users (80% threshold) |
| Report Generation | Daily 6 AM | /report-jobs/generate | Financial, operational, and compliance reports |
| Backup Cleanup | Daily 7 AM | /backup-jobs/cleanup | Delete backups older than 30 days |
| Alert Escalation | Every 4 hours | /jobs/alert-escalation | Escalate unresolved AML alerts |
| Approval Expiry | Every 30 minutes | /jobs/approval-expiry | Expire pending card/withdrawal approvals |
GCP Project Layout
All infrastructure lives in a single GCP project with resources in europe-west1.
| Resource | Service | Name / ID | Purpose |
|---|---|---|---|
| Cloud Run | Compute | keshless-api | Production API |
| Cloud Run | Compute | keshless-api-dev | Development API |
| Cloud Run | Compute | keshless-ussd | USSD server |
| Cloud SQL | Database | keshless-postgres | PostgreSQL instance (dev + prod DBs) |
| Cloud Storage | Storage | keshless-documents | KYC photos, ID scans, selfies, vendor media |
| Cloud Storage | Storage | keshless-backups | Database backups, secrets backups |
| Secret Manager | Security | KESHLESS_* prefixed | JWT secrets, DB URLs, API keys, encryption keys |
| Cloud Build | CI/CD | Triggers on dev and prod branches | Docker build → Artifact Registry → Cloud Run |
| Artifact Registry | CI/CD | Docker images | Container images for API and USSD |
| Cloud Scheduler | Jobs | 7 scheduled jobs | Backups, sanctions sync, reports, escalation |
| Cloud Logging | Observability | Structured JSON logs | Request logs, security events, audit trail |
Deployment Pipeline
API (Cloud Run via Cloud Build)
Cloud Run Configuration:
- CPU: 1 vCPU
- Memory: 512 MB
- Min instances: 1 (always warm)
- Max instances: 20
- Timeout: 300 seconds
- Concurrency: 1000 requests per instance
Dashboard (Cloudflare Pages)
Mobile Apps (Manual Build)
USSD & Telecom Integration
The USSD server is a separate Cloud Run service that handles telco callbacks and proxies airtime requests.
The USSD server acts as a bridge — it receives USSD menu inputs from MTN, manages session state, and proxies requests to the main API for wallet operations and to Swazi Mobile for airtime top-ups (the Swazi Mobile ERS360 API sits on a private IP, so the USSD server on Cloud Run acts as the public-facing proxy).
Storage Architecture
Key rules:
- All KYC documents accessed via signed URLs only (never public)
- Max upload size: 10 MB per file
- Backups encrypted with AES-256-GCM before storage
- Backup retention: 2 years (PostgreSQL and secrets)
- Cleanup job deletes backups older than 30 days (daily), keeps monthly/yearly snapshots
External Service Dependencies
| Service | Provider | Purpose | Protocol | Auth |
|---|---|---|---|---|
| Notification Service | Eneza (shared) | OTP delivery, transaction alerts | HTTPS REST | X-API-KEY header |
| Face Matching | AWS Rekognition | Selfie vs ID photo comparison | AWS SDK | IAM access keys |
| ID OCR | AWS Textract | Extract text from ID documents | AWS SDK | IAM access keys |
| OCR Fallback | Google Gemini | Backup OCR processor | HTTPS REST | API key |
| Sanctions List | UN (Azure Blob) | PEP/sanctions screening | HTTPS | Public |
| SMS Fallback | YeboLink | SMS when WhatsApp unavailable | HTTPS REST | API key |
| MTN Airtime | MTN ERS360 | Airtime top-up via USSD | SOAP/XML | Credentials |
| Swazi Airtime | Swazi Mobile ERS360 | Airtime top-up (private IP) | SOAP/XML | Credentials |