JohnApollos/VoltReturn

VoltReturn is an enterprise-grade decision-support platform designed for electric motorcycle (boda boda) operators, pay-as-you-go (PAYG) asset financiers, and climate finance investors in East Africa. # VoltReturn ### An AI-Powered Decision Intelligence Platform for African Electric Mobility & Finance VoltReturn is an enterprise-grade investment decision and analytics platform designed for electric motorcycle (boda boda) operators, pay-as-you-go (PAYG) asset financiers, and climate finance investors in East Africa. --- ## 1. The Strategic Business Challenge In the East African electric mobility sector, scaling infrastructure (Battery Swap Stations — BSS) presents a classic chicken-and-egg coordination problem. Operators cannot justify the CapEx of deploying swap cabinets without an active rider base, while riders cannot transition to EVs without station density to eliminate range anxiety. At the same time, financing companies (Mogo, Watu, M-KOPA) deploy billions of shillings in PAYG loans without understanding how physical infrastructure proximity directly impacts borrower credit risk. **Distance to the nearest BSS is the single strongest predictor of payment default.** A rider operating far from a BSS spends critical operating hours traveling to swaps, losing daily revenue. VoltReturn bridges this gap. It turns raw spatial, financial, and battery telemetry data into actionable deployment decisions, credit risk audits, and investment evaluations. --- ## 2. Platform Architecture VoltReturn features a decoupled Monorepo structure, combining a FastAPI analytical backend with a modern, high-performance Next.js single-page application (SPA). ```mermaid graph TD User[Client Browser / Next.js SPA] -->|HTTP REST| API[FastAPI Backend] API -->|Metadata & Logs| SQL[SQLite relational database] API -->|High-speed Parquet scans| Duck[DuckDB analytical engine] API -->|Google GenAI SDK| Gemini[Google Gemini 2.5 Flash] subgraph S1 ["Data Layer"] SQL -->|Governance Registry| G[Model Governance] SQL -->|Recommendation Ledger| R[Recommendations] Duck -->|Time-series pack logs| P[battery_telemetry.parquet] end subgraph S2 ["Frontend Workspace (Zustand LocalStorage)"] User …