AI-assisted post-harvest logistics platform for Sub-Saharan African agricultural cooperatives, combining ML-based spoilage forecasting, dynamic market/route recommendation, and multi-tenant operational tooling to reduce produce lost in transit between farm and market.
Problem
Smallholder farmers and cooperatives routinely lose a large share of harvested produce before it reaches a buyer — not from poor yields, but from logistical blindness in transit: non-refrigerated transport, unpredictable road delays, and zero real-time visibility into whether cargo is still sellable by the time it arrives. Dispatchers have no way to know a shipment is degrading until it’s already a write-off at the destination market.
What It Does
Fresh Supplies tracks produce from harvest through delivery and uses a trained ML model to predict spoilage risk for a shipment based on transit time, distance, and crop-specific perishability. When risk is high, it recommends alternative wholesale markets ranked by revenue retained (quantity × price × (1 − spoilage%)), so a shipment can be diverted to a nearer, better-margin buyer instead of continuing to a market where it’ll arrive unsellable.
Multi-Tenant Role Model
The platform is organized around agricultural cooperatives as tenants, with role-scoped access enforced server-side:
| Role | Scope |
|---|---|
| Administrator | Platform-wide: provisions cooperatives, users, and access grants |
| Farmer Cooperative (Admin / Member) | Owns produce lots and shipments for their own cooperative |
| Logistics Manager | Manages shipments and driver assignment for cooperatives they’ve been explicitly granted access to |
| Market Analyst | Views analytics/market intelligence for granted cooperatives only |
| Driver | Mobile-only; sees and acts on shipments assigned to them specifically |
Staff roles (Logistics Manager, Market Analyst) get cooperative access via explicit access grants rather than a single fixed assignment, so one person can support multiple cooperatives without being a full admin.
Core Features
- Produce lot tracking — crop type, grade, quantity, harvest date, per cooperative.
- Shipment lifecycle — scheduled → in-transit → delivered, with driver assignment and cooperative-scoped visibility.
- Spoilage prediction — per-shipment risk score from a trained classifier (temperature, transit time, distance, crop frailty).
- Market/route recommendation — ranks candidate destination markets by distance, time, predicted spoilage, and resulting revenue retained.
- Mobile driver app (Flutter) — OTP-based login, offline-capable sync of field records, in-app pickup confirmation that flips a shipment to in-transit.
- Admin dashboard — user provisioning with forced password-change-on-first-login (via emailed OTP), cooperative/tenant management, access-grant management.
- Analytics & reporting — cooperative-scoped dashboards for shipment and spoilage trends, CSV/report export.
Architecture
Web (Next.js) ─┐
Mobile (Flutter)─┼─▶ FastAPI backend ─▶ PostgreSQL
│ (REST + ML inference)
│
Caddy (reverse proxy, path-routed, single origin)
│
Cloudflare Tunnel (named, fixed hostname)
│
Cloudflare edge (TLS termination)
- Web and backend are served from a single origin behind Caddy (
/api/*→ backend, everything else → frontend), eliminating CORS in production. - The only internet-facing component is an outbound-only Cloudflare Tunnel — no ports are opened on the host; TLS terminates at Cloudflare’s edge.
- Docker Compose orchestrates Postgres, backend, frontend, Caddy, Cloudflare Tunnel, and one-shot DB provisioning/migration containers.
Tech Stack
| Layer | Technology |
|---|---|
| Backend | FastAPI, SQLAlchemy 2.0 (async), Alembic, PostgreSQL 16 |
| Frontend | Next.js, React, TypeScript, Tailwind CSS, shadcn/ui, TanStack Query |
| Mobile | Flutter/Dart |
| ML | scikit-learn / XGBoost spoilage classifier, graph-based route scoring |
| Infra | Docker Compose, Caddy, named Cloudflare Tunnel |
| Auth | JWT access/refresh tokens, email OTP for first login and passwordless recovery |
Status
Actively developed capstone project; core multi-tenant auth, provisioning, shipment/produce management, ML spoilage and market recommendation, and the mobile driver app are implemented and deployed.
Where To Find The Resource
- Visit the live project at freshsupplies.umarndungo.com.