BorderCash Enterprise Platform Documentation

BorderCash is an enterprise-grade, self-hostable fintech platform designed for cross-border payments, multi-currency virtual accounts, tokenized investments, crypto-fiat swaps, and digital banking services.

🏗 Executive Architecture

graph TD
    Client[Flutter Client Apps: Mobile / Web / Desktop] -->|REST & WebSockets| NGINX[Reverse Proxy / SSL]
    NGINX --> Backend[Django 5 / DRF Node]
    Backend --> Postgres[(PostgreSQL Database)]
    Backend --> Redis[(Redis Queue & Cache)]
    Backend --> Celery[Celery Async Workers & Beat]
    
    Backend -->|Ed25519 & Heartbeat| LicenseEngine[Pluggedspace License Engine]
    Backend -->|Encrypted Outbound API Calls| BankingRails[Banking & Fintech Rails: Plaid / Mono / Modulr / Railsr / Sila]
    Backend -->|Crypto / Liquidity| CryptoRails[Stellar Network / Changelly / Transak]
    Backend -->|Utility & Logistics| UtilityRails[Reloadly / AliExpress / LocationIQ]
    
    Admin[Enterprise Executive Dashboard] -->|Encrypted Config & Module Switches| Backend

📦 Core Modules & Applications

app: Central engine containing User Profiles, Multi-Currency Wallets, Transactional ledger, Encrypted Secrets Vault (app/services/vault/), and Runtime Configuration (models_config.py).
licensing: Pluggedspace License Engine connector featuring offline Ed25519 cryptographic token verification, deployment registration, periodic background heartbeats, and grace-period enforcement.
iban: Virtual Multi-Currency IBAN account issuance and automated routing.
invest: Tokenized asset investment pools and live asset valuation.
kyc: Identity compliance verification, tier management, and document approval.
monica: Customer support, chargeback handling, and dispute resolution.
drac: Reconciliation, audit trail integrity, and ledger balancing.
backup: Database and media snapshot manager with Dropbox & S3 storage drivers.

🔐 Encrypted Secrets Vault Subsystem

All third-party credentials and sensitive keys are managed dynamically via the Executive Admin Dashboard and stored using AES-128-CBC / HMAC-SHA256 (Fernet) cryptography.

Security Guarantees

In-Memory Decryption Only: Keys are decrypted on-the-fly inside the backend process when an external API call is dispatched.
Zero Plaintext in Database: Secrets are encrypted automatically before writing to PostgreSQL.
Zero Secrets in Frontend: Client builds contain zero API secrets. The public configuration endpoint (GET /api/v1/system/config/) exposes only organization branding and boolean feature/rail availability.
Masked Presentation: Admin interfaces mask secret keys (e.g., sk_l••••••••3a8f) and password fields.

Supported Provider Rails

Provider Slug	Category	Capabilities
`plaid`	Open Banking (US / UK / EU)	Account linking, balance check, ACH identity
`mono`	Open Banking (Africa)	Bank account resolution, BVN identity, statement parsing
`modulr`	Payment Rails (UK / EU)	Virtual IBAN accounts, Faster Payments, SEPA
`railsr`	Banking-as-a-Service	Global virtual accounts, card issuing
`sila`	ACH & Dollar Pegged	US ACH debits/credits, wallet infrastructure
`flutterwave`	African BaaS & MoMo	Dedicated Virtual NUBAN accounts, Mobile Money
`paystack`	African Payouts & NUBAN	Virtual accounts, NIBSS bank transfers, card processing
`yellowcard`	Pan-African Liquidity & MoMo	20+ countries crypto-fiat converter, local bank & MoMo rails
`link`	NGN Payout & Converter	Stellar USDC ↔ NGN off-ramp and bank payouts
`changelly_crypto`	Crypto Swaps	Non-custodial cryptocurrency conversion
`changelly_fiat`	On/Off Ramp	Credit card and bank fiat-to-crypto purchases
`stellar`	Custody & Settlement	Stellar USDC / XLM high-speed cross-border settlement
`investment_pool`	Asset Custody	Tokenized asset management and dividend routing
`transak`	Fiat Gateway	Global crypto on-ramp with local payment rails
`reloadly`	Airtime & Utilities	Mobile top-ups, utility bill payments, gift cards
`aliexpress`	E-Commerce / Dropshipping	Product ordering and logistics integration
`locationiq`	Geocoding	Reverse geocoding and address validation
`groq`	AI & Assistance	High-speed LLM processing for automated assistance
`zeptomail`	Transactional Email	Enterprise transactional email delivery
`dropbox`	Media Storage	Encrypted snapshot and document backup storage
`firebase`	Push Notifications	Push notifications for mobile & web clients
`sentry`	APM / Error Tracking	Production exception monitoring

🎛 Executive Admin Dashboard & Runtime Branding

The admin interface (/admin/) has been styled into a modern Executive Operations Dashboard.

Platform Module Switches (`/admin/app/platformmoduleconfig/`)

Administrators can instantly enable or disable any functional area of the platform without deploying code or restarting servers:

Shop & Utilities: Enable/disable mobile airtime, utility bill payments, and catalog purchases.
Investments: Enable/disable tokenized stock trading and investment pools.
Virtual IBANs: Enable/disable European/UK multi-currency banking accounts (EUR SEPA, GBP Faster Payments).
African NUBANs: Enable/disable dedicated African virtual bank accounts and local bank transfers.
Mobile Money (MoMo): Enable/disable M-Pesa, MTN MoMo, Airtel Money deposits and disbursements.
KYC Compliance: Enable/disable tiered identity verification requirements.
Dispute Resolution: Enable/disable customer grievance submissions.
Crypto Swaps & Fiat Transfers: Enable/disable individual payment vectors.
Rewards System: Enable/disable referral incentives and loyalty points.
Global Maintenance Mode: Place customer client APIs into maintenance mode with a custom announcement while retaining admin access.

Dynamic Organization Branding (`/admin/app/organizationbrandingconfig/`)

Organization Name & Title: Injected dynamically into client headers and notifications.
Palette (Primary & Accent Hex): Theme colors propagated to web and mobile apps dynamically.
Logo & Favicon URLs: Custom branding asset endpoints.
Support Email & Footer: Injected across emails and support screens.

🔑 Pluggedspace License Engine Integration

BorderCash nodes connect directly to the Pluggedspace License Engine for enterprise compliance and feature authorization.

Offline Cryptographic Verification:
- Verification uses high-security Ed25519 asymmetric digital signatures.
- Nodes can validate license tokens completely offline using embedded public keys.
Periodic Background Heartbeat:
- Celery tasks periodically sync node telemetry, active tier, and allowed seat counts with the Pluggedspace Registry.
Graceful Degradation:
- If the remote registry is unreachable, a 14-day cryptographic grace period ensures uninterrupted operations.
Public Node Info Endpoint:
- GET /api/v1/node/info/ provides the client app with license validity, tier name, and allowed feature sets.

📱 Decoupled Flutter Client & CI/CD Pipeline

The BorderCash Flutter client is maintained as a decoupled frontend artifact that communicates with the backend via REST and WebSockets.

Default Localhost Configuration

All client endpoints default strictly to http://localhost:8000 (backend) and http://localhost:3000 (web), with zero hardcoded external domains.

Custom Self-Hosted Node Pairing

Users and operators can dynamically point the Flutter app to any custom self-hosted node via the Node Connection Screen (/node-connection). The app saves this endpoint in encrypted device storage (FlutterSecureStorage) and fetches the server's runtime branding and active modules automatically.

Automated GitHub Actions Whitelabel Matrix

The repository includes a production CI/CD workflow (.github/workflows/whitelabel-build.yml) that builds whitelabeled APKs, Web bundles, and iOS binaries using GitHub Actions.

# Example local whitelabel asset branding overlay
python scripts/whitelabel_overlay.py \
  --app-name "FinTech Plus" \
  --org-name "FinTech Plus Global" \
  --primary-color "#0A2540" \
  --accent-color "#635BFF" \
  --base-url "https://api.fintechplus.io" \
  --support-email "support@fintechplus.io"

🛠 Lifecycle Management Scripts

Production server operations are automated via scripts in scripts/:

scripts/install.sh: Automated node installer with interactive prompt, dependency installation (Docker, Compose), PostgreSQL setup, and systemd service generation.
scripts/upgrade.sh: Zero-downtime database migration and container image updating.
scripts/backup.sh: Automated PostgreSQL database dump and uploaded media archive creation.
scripts/restore.sh: Point-in-time disaster recovery restore from backup tarballs.
scripts/uninstall.sh: Clean node uninstallation with interactive data preservation prompt.
scripts/cli_wizard.py: CLI assistant for managing admin credentials, testing license status, and validating provider health.

🩺 Health Probes & Monitoring

Kubernetes and Docker healthcheck endpoints are exposed out-of-the-box:

GET /healthz: Comprehensive node status including Database connectivity, Redis queue, License status, and active modules.
GET /livez: Liveness probe (HTTP 200 if process is running).
GET /readyz: Readiness probe (HTTP 200 if PostgreSQL connection pool is healthy).
Structured JSON Logging: Centralized request-id correlation via RequestIDMiddleware with JSON output formatted for Datadog, Grafana Loki, and CloudWatch.

🏗 Executive Architecture​

📦 Core Modules & Applications​

🔐 Encrypted Secrets Vault Subsystem​

Security Guarantees​

Supported Provider Rails​

🎛 Executive Admin Dashboard & Runtime Branding​

Platform Module Switches (/admin/app/platformmoduleconfig/)​

Dynamic Organization Branding (/admin/app/organizationbrandingconfig/)​

🔑 Pluggedspace License Engine Integration​

📱 Decoupled Flutter Client & CI/CD Pipeline​

Default Localhost Configuration​

Custom Self-Hosted Node Pairing​

Automated GitHub Actions Whitelabel Matrix​

🛠 Lifecycle Management Scripts​

🩺 Health Probes & Monitoring​