EmmanuelOnyekachi21/trustbridge-escrow

TrustBridge: Secure multi-currency escrow platform for Africa-first marketplaces. Source-settled in NGN/GHS/KES/etc. with 14-day dispute protection, automatic 15% fee deduction on release, Flutterwave integration, and real-time USD-view balances — built with FastAPI, PostgreSQL, and Firebase. # TrustBridge **Secure multi-currency escrow & settlement platform for African digital commerce** ## 📋 Table of Contents - Overview - Core Features - Architecture Overview - Tech Stack - Development Roadmap - Important Warnings & Compliance - Getting Started - Prerequisites - Installation - Configuration - Running the Application - Project Structure - API Documentation - Testing - Deployment - Contributing - License ## Overview TrustBridge enables trusted transactions between buyers and vendors by holding funds in the original currency (source-settled: NGN, GHS, KES, etc.) during escrow, avoiding exchange rate risk. Funds are released only after service confirmation, with an automatic 15% platform fee deducted (net of processor fees). A 14-day inactivity timer moves inactive transactions to a "dispute vault" for admin resolution. Built as a **production-grade backend** with real-user intent in mind: concurrency-safe ledger, idempotent operations, audit trails, and compliance awareness (KYC, AML, licensing considerations). **Current Status**: Phase 1 (Foundation & Project Setup) — Early development / MVP phase. Not yet production-deployed. **Strong compliance & legal warnings** apply (see below). ## Core Features - **Source-Settled Escrow** — Funds held in original currency (no premature FX conversion) - **15% Platform Fee** — Deducted only on successful release (net of Flutterwave fees) - **14-Day Dispute Vault** — Auto-freeze on inactivity; admin-mediated resolution - **Multi-Currency Support** — NGN, GHS, KES + real-time USD-view conversion (on-the-fly, cached rates) - **Payment Methods** — Cards, bank transfers (via Flutterwave Standard/Direct Charge) - **Authentication** — Firebase Auth (email/password, Google, Apple Sign In) - **Payouts** — Vendor withdrawals via Flutterwave Transfer API (NUBAN, M-Pesa, etc.) - **Webhooks** — Secure handling of Flutterwave events (charge.completed, transfers) - **Ledger Integrity** — PostgreSQL with ACID transacti …