Skip to content

Backend Documentation

Welcome to the CodeForge Suite Platform Backend Documentation. This comprehensive guide covers all major modules and features of the banking system.

Quick Start Navigation

🔐 Security & Compliance

  • 📋 Compliance Status Report - Current vs. Planned compliance frameworks
  • What's implemented ✅ (GDPR, PCI DSS, OWASP, ISO 27001, Banking compliance)
  • What's planned 📋 (HSM, End-to-End encryption, Certifications)
  • Roadmap for compliance implementation

API Documentation Governance

Core Modules

Onboarding Module

  • Mobile Registration - Standalone mobile banking onboarding module (CBS lookup, DIDIT verification, OTP stages, staged approval)

Business & Compliance Modules

Core & Infrastructure Modules

Supporting Modules

System Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                            API Clients                             │
│              Web | Mobile Banking | USSD | Agent | API             │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│                    FastAPI Application Layer                       │
│           Middleware, Security Filters, CORS, Request Context      │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│                        Router Layer (/api/v1/*)                    │
│  Auth & Security Suite: /auth, /2fa/totp                           │
│  Onboarding: /mobile/register                                      │
│  Core Banking: /customer, /wallet, /transaction, /loan             │
│  Ops & Governance: /user, /policy, /support, /reconciliation       │
│  Channels & Integrations: /ussd, /notify, /integration, /agent     │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│                Services and Orchestration Layer                    │
│   Auth/MFA Flow | Mobile Registration Flow | Business Operations    │
│   Staging/Approval Pipeline | Event/Notification Coordination       │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│                     Persistence and State Layer                     │
│      PostgreSQL (SQLAlchemy + Alembic) | Redis (Cache/Sessions)    │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│                  External Integrations and Providers                │
│  CBS | DIDIT | SAML/LDAP IdP | Firebase | Email/SMS Gateways       │
└─────────────────────────────────────────────────────────────────────┘

Tech Stack

Framework:      FastAPI 0.112.2
Server:         Uvicorn 0.23.2 (dev), Gunicorn (prod)
Database:       PostgreSQL with SQLAlchemy 2.0
ORM Migrations: Alembic 1.12.0
Authentication: JWT (PyJWT), SAML (python3-saml), LDAP (ldap3)
Security:       bcrypt, Cryptography (Fernet)
Async Tasks:    Celery with Redis broker
Caching:        Redis (aioredis)
Notifications:  Firebase Admin, SMS/Email APIs
AI/ML:          OpenAI, Pandas, NumPy
Testing:        pytest, httpx
Monitoring:     Prometheus, Flower

Core Concepts

Multi-Authentication (Auth Module)

The system supports multiple authentication strategies: 1. Local: Username/Email + Password (bcrypt hashed) 2. SAML: Enterprise SSO via python3-saml 3. LDAP: Directory services (Active Directory, OpenLDAP) 4. OAuth2: Social login (Google, Azure)

Multi-Factor Authentication Options: - TOTP (Google Authenticator, Authy, Microsoft Authenticator) - SMS/Email OTP (One-Time Password) - Security Questions - Push Notification Verification

Customer Lifecycle (Customer Module)

  1. Registration: Web, Mobile, USSD, or Agent signup
  2. KYC Verification: Tier-based with document upload
  3. Tier Assignment: Basic → Standard → Premium → Business
  4. Feature Access: Based on KYC tier and channel

Mobile Registration Lifecycle (Onboarding Module)

  1. Phone Check: Validate eligibility and issue registration token
  2. Identity Path: CBS lookup (existing customer) or DIDIT verification (non-bank)
  3. Verification Completion: Webhook/redirect handling with polling fallback
  4. Contact Validation: Phone OTP then email OTP
  5. Consent and Credential Setup: Terms acceptance and PIN configuration
  6. Completion and Activation: Auto-approval or manual approval pipeline

Loan Lifecycle (Loan Module)

  1. Product Definition: Configure loan terms
  2. Application: Customer applies for loan
  3. Scoring: Internal + External credit scoring
  4. Underwriting: Fraud detection, risk assessment
  5. Approval: Auto or manual decision
  6. Disbursement: Funds transferred to customer
  7. Repayment: Scheduled installments tracked
  8. Default/Collection: Recovery process

Transaction Flow (Transaction Module)

  1. Initiation: User requests transaction
  2. Validation: Balance, limits, policy checks
  3. Authorization: PIN/OTP verification
  4. Processing: Debit/credit accounts
  5. Settlement: Notify parties, update ledgers
  6. Post-Processing: Send receipts, update analytics

Wallet Ecosystem (Wallet Module)

  1. Product Tiers: Different wallet products
  2. KYC Tiers: Limit based on verification level
  3. Multi-Currency: Support multiple currencies
  4. Payment Methods: P2P, Merchant, Bill payment
  5. Linked Accounts: Bank account integration
  6. QR Codes: Static and dynamic payment QR codes

API Organization

Routing Structure

/api/v1/auth              - Authentication (login, 2FA, SAML, LDAP)
/api/v1/user              - User, role, and policy management (shared router)
/api/v1/core              - Core configuration, entity management, audit
/api/v1/customer          - Customer profiles and KYC
/api/v1/document          - Document storage
/api/v1/transaction       - Financial transactions
/api/v1/wallet            - Digital wallets and e-money
/api/v1/integration       - External service integration (CBS, gateways, email, SMS)
/api/v1/app               - Application configuration
/api/v1/ussd              - USSD gateway (feature phones)
/api/v1/notify            - Notifications (SMS, Email, Push, WebSocket)
/api/v1/agent             - Agent/Operator management, geofencing, stores
/api/v1/ai-agent          - AI conversational interface
/api/v1/report            - Reports and analytics
/api/v1/aml               - Anti-money laundering
/api/v1/campaign          - Marketing campaigns
/api/v1/inventory         - Inventory tracking
/api/v1/loan              - Loan management
/api/v1/support           - Support ticketing and FAQ operations
/api/v1/2fa/totp          - TOTP/2FA management
/api/v1/admin/config      - System configuration
/api/v1/reconciliation    - Account reconciliation
/api/v1/permissions       - Permission administration
/api/v1/mobile/register   - Mobile registration and DIDIT onboarding (standalone onboarding module)
/api/v1/card              - Card management
/api/v1/ws                - WebSocket channels (chat/notifications)

Authentication & Security

JWT Token Flow

1. Login → Validate credentials → Generate JWT tokens
2. Access Token (60 min): Used for API requests
3. Refresh Token (7 days): Used to get new access token
4. Token Denylist (Redis): Immediate revocation capability

Security Headers

CORS Protection:                ✓
HTTPS Enforcement:              ✓ (prod)
Security Headers (CSP, etc):    ✓
Rate Limiting:                  ✓
CSRF Protection:                ✓ (state-changing requests)

Password Security

Hashing:        bcrypt (industry-standard)
Additional:     Fernet encryption (at-rest)
History:        Track previous passwords
Expiry:         Configurable policy
Complexity:     Length, uppercase, numbers, symbols
Reset:          Time-limited email/SMS links

Database Design

Key Principles

  1. Normalization: Follows 3NF to reduce redundancy
  2. Integrity: Foreign keys enforce relationships
  3. Auditability: CreatedAt/UpdatedAt on all entities
  4. Performance: Indexed on frequently queried columns
  5. Scalability: Partition large tables by date range

Core Entities

Users
├─ Credentials (encrypted passwords)
├─ Sessions (active login sessions)
├─ UserRoles (RBAC mapping)
└─ Permissions (fine-grained access control)

Customers
├─ Profiles (personal information)
├─ Phones (contact info)
├─ Emails (contact info)
├─ Addresses (contact info)
└─ KYC Status (verification tier)

Wallets
├─ Wallet Products (e-money product definitions)
├─ Wallet Balances (multi-currency)
├─ Transactions (debit/credit history)
└─ Linked Accounts (bank account links)

Loans
├─ Loan Products (product definitions)
├─ Loan Applications (customer applications)
├─ Loan Records (active loans)
├─ Repayments (payment history)
├─ Scoring Results (underwriting decisions)
└─ Fraud Detection (fraud cases, rules, flags)

Transactions
├─ Transaction Records (all financial movements)
├─ Disputes (customer disputes)
├─ Reconciliation Records (bank reconciliation)
└─ Audit Trail (transaction modifications)

Configuration Management

Environment Variables

# Server
LOCAL_HOST=0.0.0.0
LOCAL_PORT=8000
PRODUCTION=false

# Database
DATABASE_URL=postgresql://user:password@localhost/bank_ussd

# JWT
ACCESS_TOKEN_EXPIRE_MINUTES=60
REFRESH_TOKEN_EXPIRE_MINUTES=10080

# Redis
REDIS_URL=redis://localhost:6379

# Email/SMS
SMTP_SERVER=smtp.gmail.com
TWILIO_ACCOUNT_SID=***
TWILIO_AUTH_TOKEN=***

# SAML/LDAP
SAML_CONFIG_FILE=config/saml_config.json
LDAP_SERVER=ldap.example.com

# Firebase
FIREBASE_PROJECT_ID=***
FIREBASE_CREDENTIALS=***

Seed Data

seed/permissions.json     - Role-based permissions
seed/actions.json         - Available system actions
seed/category.json        - Entity categories
seed/template_seed.json   - Notification templates
seed/campaign_seed.json   - Campaign templates
seed/1_schemas.sql        - Initial database schema
seed/3_initial_data.sql   - Initial data values

Common Workflows

User Registration → Loan Application → Disbursement

1. Register Customer
   └─ /api/v1/auth/register → /api/v1/customer/add

2. Complete KYC
   └─ /api/v1/customer/kyc/initiate → submit documents → verify

3. Apply for Loan
   └─ /api/v1/loan/application/add → submit documents

4. Loan Scoring
   └─ /api/v1/loan/scoring/loan → internal + external scoring

5. Loan Approval
   └─ /api/v1/loan/loan/approve → loan officer approves

6. Disbursement
   └─ /api/v1/loan/loan/disburse → funds to customer wallet

7. Repayment Starts
   └─ Schedule created → /api/v1/loan/repayment/add

Payment Processing Flow

1. Initiate Payment
   └─ /api/v1/wallet/transaction/transfer

2. Validate
   └─ Balance, limits, policy checks

3. Authenticate
   └─ PIN verification + optional OTP

4. Process
   └─ Debit source → Credit destination → Record

5. Notify
   └─ /api/v1/notify/send (SMS, Email, Push)

6. Receipt
   └─ Generate and store transaction receipt

Fraud Detection in Loan Application

1. Application Submitted
   └─ /api/v1/loan/application/add

2. Fraud Check
   └─ /api/v1/loan/fraud/check → evaluate rules

3. Rules Engine
   ├─ Duplicate application check
   ├─ Velocity check (multiple apps in 24h)
   ├─ Phone owner verification
   ├─ Income verification
   └─ Known fraud patterns

4. Flag or Approve
   ├─ If fraud_score > threshold → Flag
   │  └─ /api/v1/loan/fraudflag/escalate → Investigation
   └─ Else → Continue to scoring

Error Handling Strategy

Standard Error Response

{
  "status_code": 400,
  "error_code": "VALIDATION_ERROR",
  "message": "Insufficient balance for transaction",
  "details": {
    "required": 5000,
    "available": 3000,
    "deficit": 2000
  }
}

Common Error Codes

401 - Unauthorized (Invalid credentials, expired token)
403 - Forbidden (Insufficient permissions)
404 - Not Found (Resource doesn't exist)
422 - Validation Error (Invalid request data)
429 - Too Many Requests (Rate limit exceeded)
500 - Internal Server Error (Server-side error)

Performance & Scalability

Optimization Strategies

Caching:            Redis for tokens, user data, balances
Database:           Indexes on frequently queried columns
Async Tasks:        Celery for non-blocking operations
Connection Pool:    Reuse database connections (pool_size=10)
Rate Limiting:      Protect endpoints from abuse
Batch Processing:   Process reports in background
Pagination:         Limit large result sets

Monitoring & Logging

Application:        FastAPI logging + custom logger
Database:           Query logging and slowlog tracking
Performance:        Prometheus metrics (latency, throughput)
Task Queue:         Flower dashboard for Celery tasks
Errors:             Centralized error logging and alerting

Testing Strategy

Test Categories

Unit Tests:         Individual function/method testing
Integration Tests:  Multi-component workflows
API Tests:          HTTP endpoint validation
Database Tests:     ORM and query verification
Security Tests:     Authentication, authorization, encryption
Performance Tests:  Load testing, benchmarking

Running Tests

# All tests
pytest

# Specific test file
pytest tests/test_auth.py

# Specific test function
pytest tests/test_auth.py::test_login

# With coverage
pytest --cov=controller --cov=routers

Development Setup

Prerequisites

Python 3.10+
PostgreSQL 12+
Redis 4.0+

Quick Start

# Install dependencies
pip install -r requirements.txt

# Setup environment
cp .env.example .env
# Edit .env with your configuration

# Initialize database
alembic upgrade head
python seed/initial_data.py

# Start development server
python main.py

# View API docs
open http://localhost:8000/docs

Deployment

Docker

docker build -t bank-ussd-backend .
docker run -p 8000:8000 bank-ussd-backend

Environment-Specific Configs

Development:  PRODUCTION=false
Staging:      PRODUCTION=false (separate DB)
Production:   PRODUCTION=true  (with SSL, monitoring)

Next Steps for Documentation

Documentation Coverage Status

Documentation is under active route-to-code reconciliation. Major module guides exist, and endpoint-level parity is being verified against live routers in app/api/v1/router.py and app/api/v1/endpoints/*.py.

Current baseline includes: - Feature descriptions and capabilities - API endpoint listings (module-level; parity hardening in progress) - Database model descriptions - Workflow examples and diagrams - Configuration examples - Security and compliance details - Error handling and testing approaches - Integration points with other modules

For current audit progress, see API_ROUTE_DOCUMENTATION_TODO.md.

Future Enhancements

  • [ ] API Rate Limiting Details & Examples
  • [ ] Caching Strategy Guide & Best Practices
  • [ ] Load Testing Results & Performance Benchmarks
  • [ ] Disaster Recovery & Backup Plan
  • [ ] Security Incident Response Procedures
  • [ ] Database Performance Tuning Guide
  • [ ] Deployment & Infrastructure Guide
  • [ ] API Client SDK Examples

Support & Contributions

Getting Help

  • Check the specific module documentation for detailed information
  • Review error messages and troubleshooting sections
  • Check test files for usage examples
  • Review controller logic for implementation details

Contributing Documentation

To add documentation for additional modules: 1. Follow the established documentation format 2. Include API endpoints, database models, and workflows 3. Add configuration examples 4. Include common use cases and error handling 5. Link to related modules

Documentation Standards

  • Keep it technical and specific
  • Use code examples and diagrams
  • Include configuration examples
  • Document error scenarios
  • Link to related documentation

File Structure

File Description
README.md Navigation Hub - START HERE
COMPLIANCE_STATUS.md Compliance status: current vs planned
AUTHENTICATION.md Auth, MFA, JWT, session
E2E_ENCRYPTION.md End-to-end encryption model and payload protection
AUTHENTICATION_ENHANCED.md Security compliance, GDPR, PCI DSS, ISO 27001
MULTIAUTH_CONSOLIDATED.md Canonical MFA master document
CUSTOMER_MANAGEMENT.md Profiles, KYC, verification
WALLET_PAYMENT_SERVICES.md Wallets, payments, e-money
TRANSACTION_PROCESSING.md Transactions, disputes
LOAN_MANAGEMENT.md Loans, scoring, collections
AGENT_MANAGEMENT.md Field agents, geofencing, stores
NOTIFICATIONS.md Notifications module
USSD_SERVICES.md USSD subscription and registration services
CAMPAIGN_INVENTORY.md Campaigns, promotions, inventory
USER_ROLE_MANAGEMENT.md Users, roles, RBAC, permissions
POLICY_MANAGEMENT.md Access policies, transaction controls
AI_AGENT.md Conversational AI interface
AML.md Anti-money laundering, risk, compliance
RECONCILIATION.md Account reconciliation, reporting
CORE_INTEGRATION.md Core config, entity management, audit/access/journey
DOCUMENT_SERVICE.md Document lifecycle, requirements, encrypted storage
INTEGRATION_SERVICES.md External integrations: CBS, billers, email/SMS, validation
SUPPORT_OPERATIONS.md Support ticketing, FAQ operations
CARD_MANAGEMENT.md Card APIs and lifecycle
MOBILE_REGISTRATION.md Mobile registration and DIDIT integration
SOCKET_REALTIME.md WebSocket chat and notifications
API_ROUTE_DOCUMENTATION_TODO.md Route coverage checklist and documentation gaps
SUPPORTING_MODULES.md TOTP and supporting utility modules

Quick Reference

Most Used Endpoints

Login:              POST /api/v1/auth/login
Create Customer:    POST /api/v1/customer/customer/add
Create Wallet:      POST /api/v1/wallet/wallet/create
Transfer Funds:     POST /api/v1/wallet/transaction/transfer
Apply for Loan:     POST /api/v1/loan/application/add
Process Payment:    POST /api/v1/transaction/add
Send Notification:  POST /api/v1/notify/notification/send

Database Connection

PostgreSQL: postgresql://user:password@localhost:5432/bank_ussd
Redis:      redis://localhost:6379

Key Controllers

controller/auth.py              - Authentication logic
controller/customer.py          - Customer operations
controller/wallet.py            - Wallet operations
controller/transaction.py       - Transaction logic
controller/loan.py              - Loan management
controller/notify.py            - Notification delivery

Last Updated: 2024-06-28 Version: 1.0
Status: Active Documentation (Expanding)

For module-specific details, navigate using the links in the "Quick Start Navigation" section above.