FreshFlow Logistics

India-first operations software for priority-aware reverse market routing of perishable agricultural produce.

This repository starts from the invention boundary rather than UI polish. The product core is a decision engine that jointly optimizes:

• perishability-driven lot priority,
• buyer and destination assignment,
• scarce transport capacity allocation,
• dynamic reassignment under delay, degradation, and capacity shocks.

Prototype Scope

This repository now runs as a coherent product prototype:

• real FastAPI CRUD and operator read models,
• deterministic allocation, split-lot, and reassignment engine behavior,
• persisted run history and decision explanations,
• scenario replay through the UI and API,
• an API-backed Next.js operator console with no mock data in product paths,
• India-relevant demo seed data for split, reliability, and reroute stories.

Repository Layout

apps/
  api/      FastAPI API, domain models, scoring engine, simulation harness
  web/      Next.js operations dashboard scaffold
docs/       Architecture, domain, scoring, security, deployment, novelty notes

Core Product Principles

• Joint optimization beats isolated routing or bidding decisions.
• Realizable value matters more than nominal bid value.
• Priority changes market assignment, not just dispatch order.
• Reassignment must be threshold-driven and fully auditable.
• The platform must remain operable on mocked, replayed, or partially missing data.

Quick Start

Docker

1. Run docker compose up --build.
2. Open http://localhost:3000/?pitch=1.
3. Click Prepare pitch demo.
4. Use the flagged story cards instead of browsing tables.

Local

1. Start the API from apps/api with uvicorn main:app --reload --port 8000.
2. Start the web app from apps/web with npm run dev.
3. Open http://localhost:3000/.
4. If the workspace is empty, open Admin and click Seed reference data.

The web console defaults to http://localhost:8000 for API access. You can override that with NEXT_PUBLIC_API_URL.

The API auto-seeds reference data in local dev mode so the UI is usable on first load. The richer operational demo dataset is still an explicit operator action.

Demo Flow

The safest end-to-end story is now guided directly from Pitch Mode on the dashboard:

1. click Prepare pitch demo,
2. open the reliability decision,
3. open the split decision,
4. trigger the demo disruption,
5. open /exceptions,
6. apply reassignment,
7. open the updated decision.

If the workspace drifts, click Recover demo workspace from Pitch Mode.

See docs/demo-guide.md for:

• exact startup steps,
• the safest live route,
• the 2-minute recovery procedure,
• a 3-minute demo script,
• a 7-minute demo script,
• fallback scenario paths,
• screenshot-safe routes.

Documentation Index

• WHY_THIS_IS_NOT_A_GENERIC_LOGISTICS_APP.md
• docs/architecture.md
• docs/demo-guide.md
• docs/frontend-architecture.md
• docs/domain-model.md
• docs/scoring-model.md
• docs/reassignment-policy.md
• docs/api-spec.md
• docs/india-assumptions.md
• docs/security.md
• docs/deployment.md
• docs/operator-workflows.md
• docs/roadmap.md
• docs/patentability/novelty-preservation.md

Explicit Out Of Scope For v1

• consumer-facing farmer applications,
• live payment execution,
• blockchain or tokenized logistics flows,
• multilingual UX beyond schema readiness,
• full national fleet optimization,
• computer vision grading,
• hardware or IoT integrations,
• legal or tax-compliance automation beyond modeled constraints.

Near-Term Execution Order

1. Phase 1: domain framing and score definitions.
2. Phase 2: schema, CRUD, audit, and engine interfaces.
3. Phase 3: deterministic baseline allocation and simulation.
4. Phase 4: reassignment thresholds and explanation persistence.
5. Phase 5: connector-ready India data ingestion.
6. Phase 6: hardening, RBAC, observability, and deployment polish.