elonmasai7/MavunoRoute

MavunoRoute AI is a Kenya-first agri-logistics platform that helps farmers move perishable produce faster by matching harvests to buyers, optimizing shared transport routes, tracking cold-chain conditions, verifying delivery, and enabling secure M-Pesa-based payments. # MavunoRoute AI MavunoRoute AI is a Kenya-first, multi-role agri-logistics operating platform for coordinating perishable produce from farms to buyers through routing, transport execution, cold-chain visibility, and payments. The system is built as a production-oriented modular monolith with strict role-based access control, API-first domain services, and server-rendered multi-page workflows. ## Platform Status | Area | Status | |---|---| | Backend API | Production-structured (FastAPI, service/repository layers) | | Web Platform | Multi-page role-based UI (82 web routes) | | Security | JWT auth, RBAC, rate limiting, audit logging | | Data Layer | PostgreSQL + PostGIS-ready models, Alembic migrations | | Async Jobs | Celery scaffolding (routes, notifications, risk, reports) | | Test Suite | 23 passing tests (API + route/permission matrix) | ## Core Capabilities - Multi-role workflows: Farmer, Buyer, Transporter, Cold Hub Operator, Cooperative Admin, Ops/Admin. - Harvest-to-demand logistics lifecycle with route and job orchestration. - Cold-chain observability through temperature/breach tracking. - Payments and M-Pesa integration abstraction. - Centralized response envelope, pagination, and access enforcement. - Professional multi-page web UX with role dashboards and isolated modules. ## Architecture Overview ```text Browser (Jinja2 + Vanilla JS) | v FastAPI App - API routes (/api/v1/*) - Web routes (role-based pages) - RBAC + auth dependencies | v PostgreSQL / PostGIS Redis | v Celery Workers (background processing) ``` ## Technology Stack - Backend: Python 3.12, FastAPI, SQLAlchemy 2.x, Alembic, Pydantic v2 - Frontend: Jinja2 templates, modular CSS, minimal vanilla JavaScript - Data: PostgreSQL 16, PostGIS-ready schema, Redis 7 - Async: Celery - Infra: Docker Compose, Nginx (local), Render-ready Docker setup ## Repository Structure ```text backend/ app/ api/v1/ # REST endpoints web/ # Server-rendered page routes models/ …