# keiloktql/farmora architecture

> Architecture diagram of the GitHub repository keiloktql/farmora, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/keiloktql/farmora
- Repository: https://github.com/keiloktql/farmora

## Overview

Farmora is an FPO workspace for turning exporter demand into farmer-backed produce deals and tracking them through delivery. The principal workflow runs from buyer discovery or an order book, through contract creation and climate-risk farmer matching, to allocation and season progress. Separate capabilities include the farmer directory, recommendation chat, portfolio overview, and WhatsApp product reels. The README documents the page/runtime structure; source-index references and excerpts support the service links shown. Several page and API implementations were not sampled, so their internal wiring is omitted.

Main entry points: [`src/lib/contracts/store.ts`](https://github.com/keiloktql/farmora/blob/main/src/lib/contracts/store.ts) (Contract Store), [`src/app/api/recommend/route.ts`](https://github.com/keiloktql/farmora/blob/main/src/app/api/recommend/route.ts) (Recommendation API), [`src/lib/recommender/data.ts`](https://github.com/keiloktql/farmora/blob/main/src/lib/recommender/data.ts) (Climate & Farmer Data), [`src/components/pages/farmer-database.tsx`](https://github.com/keiloktql/farmora/blob/main/src/components/pages/farmer-database.tsx) (Farmer Directory UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["FPO Workspace"]
  node_buyerui["Buyer Network<br/>[buyers.tsx]"]
  node_overview["Overview<br/>[overview.tsx]"]
  node_farmerdb["Farmer Directory UI"]
  node_whatsapp["WhatsApp Reels<br/>[whatsapp.tsx]"]
  node_portfolioapi["Portfolio API<br/>[route.ts]"]
  node_portfolio["Portfolio Service<br/>[portfolio.ts]"]
  node_dc["Page Runtime<br/>[dc.tsx]"]
  node_voxel["3D Farm Scenes<br/>[voxel.ts]"]
end

subgraph group_dealflow["Deal Flow"]
  node_newproject["Order Book Review<br/>[new-project.tsx]"]
  node_contractsui["Contracts UI<br/>[contracts.tsx]"]
  node_farmercontracts["Contract Farmers"]
  node_buyersapi["Buyer API"]
  node_orderparse["Order Book Parser<br/>[route.ts]"]
  node_contractsapi["Contracts API"]
  node_buyerstore["Exporter Network<br/>[store.ts]"]
  node_contractstore[("Contract Store<br/>[store.ts]")]
  node_standards["Export Standards<br/>[standards.ts]"]
end

subgraph group_matching["Farmer Matching"]
  node_recommendui["Farmer Picking UI"]
  node_recommendapi["Recommendation API<br/>[route.ts]"]
  node_interpretapi["Preference Chat API<br/>[route.ts]"]
  node_recdata[("Climate &amp; Farmer Data<br/>[data.ts]")]
  node_preferences["Preference Rules<br/>[preferences.ts]"]
  node_recmodel["Risk Recommender<br/>[model.ts]"]
  node_directoryapi["Farmer Directory API"]
  node_directory["Farmer Directory Service<br/>[directory.ts]"]
end

subgraph group_delivery["Delivery Tracking"]
  node_progressui["Project Progress UI<br/>[progress.tsx]"]
  node_progressapi["Progress Reports API"]
  node_progressstore[("Progress Store<br/>[store.ts]")]
  node_stages["Crop Season Stages<br/>[stages.ts]"]
end

node_manager(("FPO Manager"))

node_manager -->|"find exporters"| node_buyerui
node_manager -->|"review order"| node_newproject
node_manager -->|"pick farmers"| node_recommendui
node_manager -->|"browse farmers"| node_farmerdb
node_manager -->|"monitor deals"| node_overview
node_manager -->|"view reels"| node_whatsapp
node_manager -->|"track projects"| node_progressui
node_buyerui -.->|"loads network"| node_buyersapi
node_newproject -.->|"submits order book"| node_orderparse
node_contractsui -.->|"manages deals"| node_contractsapi
node_orderparse -->|"uses standards"| node_standards
node_orderparse -->|"loads crop data"| node_recdata
node_orderparse -.->|"creates contracts"| node_contractstore
node_contractsapi -->|"reads and writes"| node_contractstore
node_buyersapi -->|"serves exporter data"| node_buyerstore
node_buyerstore -->|"creates deals"| node_contractstore
node_buyerstore -->|"loads capacity data"| node_recdata
node_buyerstore -->|"scores capacity"| node_recmodel
node_recommendui -.->|"requests shortlist"| node_recommendapi
node_recommendui -.->|"sends chat"| node_interpretapi
node_recommendapi -->|"checks reserved land"| node_contractstore
node_recommendapi -->|"loads data"| node_recdata
node_recommendapi -->|"sanitizes filters"| node_preferences
node_recommendapi -->|"scores farmers"| node_recmodel
node_interpretapi -->|"loads context"| node_recdata
node_interpretapi -->|"interprets chat"| node_preferences
node_directoryapi -->|"queries farmers"| node_directory
node_farmerdb -->|"loads directory"| node_directoryapi
node_directory -->|"reads commitments"| node_contractstore
node_directory -->|"reads farmer data"| node_recdata
node_directory -->|"computes climate risk"| node_recmodel
node_portfolioapi -->|"requests summary"| node_portfolio
node_portfolio -->|"reads contracts"| node_contractstore
node_progressapi -->|"reads and records"| node_progressstore
node_progressstore -->|"loads allocations"| node_contractstore
node_progressstore -->|"uses season stages"| node_stages
node_progressui -.->|"loads progress"| node_progressapi
node_overview -->|"runs in"| node_dc
node_farmerdb -->|"runs in"| node_dc
node_recommendui -->|"runs in"| node_dc
node_farmerdb -->|"renders scene"| node_voxel

click node_buyerui "https://github.com/keiloktql/farmora/blob/main/src/components/pages/buyers.tsx"
click node_overview "https://github.com/keiloktql/farmora/blob/main/src/components/pages/overview.tsx"
click node_farmerdb "https://github.com/keiloktql/farmora/blob/main/src/components/pages/farmer-database.tsx"
click node_whatsapp "https://github.com/keiloktql/farmora/blob/main/src/components/pages/whatsapp.tsx"
click node_newproject "https://github.com/keiloktql/farmora/blob/main/src/components/pages/new-project.tsx"
click node_contractsui "https://github.com/keiloktql/farmora/blob/main/src/components/pages/contracts.tsx"
click node_farmercontracts "https://github.com/keiloktql/farmora/blob/main/src/components/pages/contracts-farmers.tsx"
click node_buyersapi "https://github.com/keiloktql/farmora/tree/main/src/app/api/buyers"
click node_orderparse "https://github.com/keiloktql/farmora/blob/main/src/app/api/orderbook/parse/route.ts"
click node_contractsapi "https://github.com/keiloktql/farmora/tree/main/src/app/api/contracts"
click node_buyerstore "https://github.com/keiloktql/farmora/blob/main/src/lib/buyers/store.ts"
click node_contractstore "https://github.com/keiloktql/farmora/blob/main/src/lib/contracts/store.ts"
click node_standards "https://github.com/keiloktql/farmora/blob/main/src/lib/contracts/standards.ts"
click node_recommendui "https://github.com/keiloktql/farmora/blob/main/src/components/pages/recommendations.tsx"
click node_recommendapi "https://github.com/keiloktql/farmora/blob/main/src/app/api/recommend/route.ts"
click node_interpretapi "https://github.com/keiloktql/farmora/blob/main/src/app/api/recommend/interpret/route.ts"
click node_recdata "https://github.com/keiloktql/farmora/blob/main/src/lib/recommender/data.ts"
click node_preferences "https://github.com/keiloktql/farmora/blob/main/src/lib/recommender/preferences.ts"
click node_recmodel "https://github.com/keiloktql/farmora/blob/main/src/lib/recommender/model.ts"
click node_directoryapi "https://github.com/keiloktql/farmora/tree/main/src/app/api/farmers"
click node_directory "https://github.com/keiloktql/farmora/blob/main/src/lib/farmers/directory.ts"
click node_portfolioapi "https://github.com/keiloktql/farmora/blob/main/src/app/api/portfolio/route.ts"
click node_portfolio "https://github.com/keiloktql/farmora/blob/main/src/lib/portfolio.ts"
click node_progressui "https://github.com/keiloktql/farmora/blob/main/src/components/pages/progress.tsx"
click node_progressapi "https://github.com/keiloktql/farmora/tree/main/src/app/api/progress"
click node_progressstore "https://github.com/keiloktql/farmora/blob/main/src/lib/progress/store.ts"
click node_stages "https://github.com/keiloktql/farmora/blob/main/src/lib/progress/stages.ts"
click node_dc "https://github.com/keiloktql/farmora/blob/main/src/lib/dc.tsx"
click node_voxel "https://github.com/keiloktql/farmora/blob/main/src/lib/voxel.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_buyerui,node_overview,node_farmerdb,node_whatsapp,node_portfolioapi,node_portfolio,node_dc,node_voxel toneBlue
class node_newproject,node_contractsui,node_farmercontracts,node_buyersapi,node_orderparse,node_contractsapi,node_buyerstore,node_contractstore,node_standards toneAmber
class node_recommendui,node_recommendapi,node_interpretapi,node_recdata,node_preferences,node_recmodel,node_directoryapi,node_directory toneMint
class node_progressui,node_progressapi,node_progressstore,node_stages toneRose
class node_manager toneIndigo
```

## Components

### FPO Workspace

- [Buyer Network](https://github.com/keiloktql/farmora/blob/main/src/components/pages/buyers.tsx): `src/components/pages/buyers.tsx`
- [Overview](https://github.com/keiloktql/farmora/blob/main/src/components/pages/overview.tsx): `src/components/pages/overview.tsx`
- [Farmer Directory UI](https://github.com/keiloktql/farmora/blob/main/src/components/pages/farmer-database.tsx): `src/components/pages/farmer-database.tsx`
- [WhatsApp Reels](https://github.com/keiloktql/farmora/blob/main/src/components/pages/whatsapp.tsx): `src/components/pages/whatsapp.tsx`
- [Portfolio API](https://github.com/keiloktql/farmora/blob/main/src/app/api/portfolio/route.ts): `src/app/api/portfolio/route.ts`
- [Portfolio Service](https://github.com/keiloktql/farmora/blob/main/src/lib/portfolio.ts): `src/lib/portfolio.ts`
- [Page Runtime](https://github.com/keiloktql/farmora/blob/main/src/lib/dc.tsx): `src/lib/dc.tsx`
- [3D Farm Scenes](https://github.com/keiloktql/farmora/blob/main/src/lib/voxel.ts): `src/lib/voxel.ts`

### Deal Flow

- [Order Book Review](https://github.com/keiloktql/farmora/blob/main/src/components/pages/new-project.tsx): `src/components/pages/new-project.tsx`
- [Contracts UI](https://github.com/keiloktql/farmora/blob/main/src/components/pages/contracts.tsx): `src/components/pages/contracts.tsx`
- [Contract Farmers](https://github.com/keiloktql/farmora/blob/main/src/components/pages/contracts-farmers.tsx): `src/components/pages/contracts-farmers.tsx`
- [Buyer API](https://github.com/keiloktql/farmora/tree/main/src/app/api/buyers): `src/app/api/buyers`
- [Order Book Parser](https://github.com/keiloktql/farmora/blob/main/src/app/api/orderbook/parse/route.ts): `src/app/api/orderbook/parse/route.ts`
- [Contracts API](https://github.com/keiloktql/farmora/tree/main/src/app/api/contracts): `src/app/api/contracts`
- [Exporter Network](https://github.com/keiloktql/farmora/blob/main/src/lib/buyers/store.ts): `src/lib/buyers/store.ts`
- [Contract Store](https://github.com/keiloktql/farmora/blob/main/src/lib/contracts/store.ts): `src/lib/contracts/store.ts`
- [Export Standards](https://github.com/keiloktql/farmora/blob/main/src/lib/contracts/standards.ts): `src/lib/contracts/standards.ts`

### Farmer Matching

- [Farmer Picking UI](https://github.com/keiloktql/farmora/blob/main/src/components/pages/recommendations.tsx): `src/components/pages/recommendations.tsx`
- [Recommendation API](https://github.com/keiloktql/farmora/blob/main/src/app/api/recommend/route.ts): `src/app/api/recommend/route.ts`
- [Preference Chat API](https://github.com/keiloktql/farmora/blob/main/src/app/api/recommend/interpret/route.ts): `src/app/api/recommend/interpret/route.ts`
- [Climate & Farmer Data](https://github.com/keiloktql/farmora/blob/main/src/lib/recommender/data.ts): `src/lib/recommender/data.ts`
- [Preference Rules](https://github.com/keiloktql/farmora/blob/main/src/lib/recommender/preferences.ts): `src/lib/recommender/preferences.ts`
- [Risk Recommender](https://github.com/keiloktql/farmora/blob/main/src/lib/recommender/model.ts): `src/lib/recommender/model.ts`
- [Farmer Directory API](https://github.com/keiloktql/farmora/tree/main/src/app/api/farmers): `src/app/api/farmers`
- [Farmer Directory Service](https://github.com/keiloktql/farmora/blob/main/src/lib/farmers/directory.ts): `src/lib/farmers/directory.ts`

### Delivery Tracking

- [Project Progress UI](https://github.com/keiloktql/farmora/blob/main/src/components/pages/progress.tsx): `src/components/pages/progress.tsx`
- [Progress Reports API](https://github.com/keiloktql/farmora/tree/main/src/app/api/progress): `src/app/api/progress`
- [Progress Store](https://github.com/keiloktql/farmora/blob/main/src/lib/progress/store.ts): `src/lib/progress/store.ts`
- [Crop Season Stages](https://github.com/keiloktql/farmora/blob/main/src/lib/progress/stages.ts): `src/lib/progress/stages.ts`

### Other components

- **FPO Manager**

## Connections

- FPO Manager → Buyer Network: find exporters (evidence: `README.md`)
- FPO Manager → Order Book Review: review order (evidence: `README.md`)
- FPO Manager → Farmer Picking UI: pick farmers (evidence: `README.md`)
- FPO Manager → Farmer Directory UI: browse farmers (evidence: `README.md`)
- FPO Manager → Overview: monitor deals (evidence: `README.md`)
- FPO Manager → WhatsApp Reels: view reels (evidence: `README.md`)
- FPO Manager → Project Progress UI: track projects (evidence: `README.md`)
- Buyer Network → Buyer API: loads network
- Order Book Review → Order Book Parser: submits order book
- Contracts UI → Contracts API: manages deals
- Order Book Parser → Export Standards: uses standards (evidence: `src/app/api/orderbook/parse/route.ts`)
- Order Book Parser → Climate & Farmer Data: loads crop data (evidence: `src/app/api/orderbook/parse/route.ts`)
- Order Book Parser → Contract Store: creates contracts
- Contracts API → Contract Store: reads and writes (evidence: `src/app/api/contracts/route.ts`)
- Buyer API → Exporter Network: serves exporter data (evidence: `src/app/api/buyers/route.ts`)
- Exporter Network → Contract Store: creates deals (evidence: `src/lib/buyers/store.ts`)
- Exporter Network → Climate & Farmer Data: loads capacity data (evidence: `src/lib/buyers/store.ts`)
- Exporter Network → Risk Recommender: scores capacity (evidence: `src/lib/buyers/store.ts`)
- Farmer Picking UI → Recommendation API: requests shortlist
- Farmer Picking UI → Preference Chat API: sends chat
- Recommendation API → Contract Store: checks reserved land (evidence: `src/app/api/recommend/route.ts`)
- Recommendation API → Climate & Farmer Data: loads data (evidence: `src/app/api/recommend/route.ts`)
- Recommendation API → Preference Rules: sanitizes filters (evidence: `src/app/api/recommend/route.ts`)
- Recommendation API → Risk Recommender: scores farmers (evidence: `src/app/api/recommend/route.ts`)
- Preference Chat API → Climate & Farmer Data: loads context (evidence: `src/app/api/recommend/interpret/route.ts`)
- Preference Chat API → Preference Rules: interprets chat (evidence: `src/app/api/recommend/interpret/route.ts`)
- Farmer Directory API → Farmer Directory Service: queries farmers (evidence: `src/app/api/farmers/route.ts`)
- Farmer Directory UI → Farmer Directory API: loads directory (evidence: `src/components/pages/farmer-database.tsx`)
- Farmer Directory Service → Contract Store: reads commitments (evidence: `src/lib/farmers/directory.ts`)
- Farmer Directory Service → Climate & Farmer Data: reads farmer data (evidence: `src/lib/farmers/directory.ts`)
- Farmer Directory Service → Risk Recommender: computes climate risk (evidence: `src/lib/farmers/directory.ts`)
- Portfolio API → Portfolio Service: requests summary (evidence: `src/app/api/portfolio/route.ts`)
- Portfolio Service → Contract Store: reads contracts (evidence: `src/lib/portfolio.ts`)
- Progress Reports API → Progress Store: reads and records (evidence: `src/app/api/progress/reports/route.ts`)
- Progress Store → Contract Store: loads allocations (evidence: `src/lib/progress/store.ts`)
- Progress Store → Crop Season Stages: uses season stages (evidence: `src/lib/progress/store.ts`)
- Project Progress UI → Progress Reports API: loads progress
- Overview → Page Runtime: runs in (evidence: `src/components/pages/overview.tsx`)
- Farmer Directory UI → Page Runtime: runs in (evidence: `src/components/pages/farmer-database.tsx`)
- Farmer Picking UI → Page Runtime: runs in (evidence: `src/components/pages/recommendations.tsx`)
- Farmer Directory UI → 3D Farm Scenes: renders scene (evidence: `src/components/pages/farmer-database.tsx`)
