# santhosh-ek2007-zen/kuralagri architecture

> Architecture diagram of the GitHub repository santhosh-ek2007-zen/kuralagri, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/santhosh-ek2007-zen/kuralagri
- Repository: https://github.com/santhosh-ek2007-zen/kuralagri

## Overview

KuralAgri is an agricultural aggregation platform connecting farmers, CSC hubs, and commercial buyers. Its principal workflow is listing produce, grading and pricing it, assigning it to a nearby hub, pooling it for buyer orders, and settling collection through escrow and QR confirmation; reputation records completed transactions. The graph includes the documented product capabilities and sampled API/UI structure. Some feature links come from the README because relevant implementation details were not excerpted.

Main entry points: [`backend/main.py`](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/main.py) (API application), [`backend/app/database.py`](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/database.py) (Relational database), [`frontend/src/api/client.js`](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/frontend/src/api/client.js) (API client), [`frontend/src/App.jsx`](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/frontend/src/App.jsx) (Application shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market["Supply and market"]
  node_listings["Produce listings<br/>[listings.py]"]
  node_grading["AI quality grading<br/>[ai_grading.py]"]
  node_geo["Hub assignment<br/>[geo.py]"]
  node_pricing["Mandi pricing<br/>[pricing.py]"]
  node_aggregation["Aggregation points"]
  node_ivr["IVR listing service<br/>[ivr.py]"]
end

subgraph group_trade["Orders and trust"]
  node_buyer_api["Buyer aggregation<br/>[buyer.py]"]
  node_orders["Orders and escrow<br/>[orders.py]"]
  node_reputation["Trust and disputes<br/>[reputation.py]"]
end

subgraph group_api["Backend services"]
  node_auth["Accounts and access<br/>[auth.py]"]
  node_database[("Relational database<br/>[database.py]")]
  node_models["Domain records<br/>[models.py]"]
  node_api_server["API application<br/>[main.py]"]
end

subgraph group_ui["Frontend experience"]
  node_farmer_ui["Farmer studio<br/>[FarmerPortal.jsx]"]
  node_buyer_ui["Buyer catalog<br/>[BuyerCatalog.jsx]"]
  node_ivr_ui["IVR simulator"]
  node_order_ui["Escrow pickup view"]
  node_reputation_ui["Reputation center<br/>[ReputationView.jsx]"]
  node_app["Application shell<br/>[App.jsx]"]
  node_api_client["API client<br/>[client.js]"]
end

node_farmers(("Farmers / CSC operators"))
node_buyers(("Commercial buyers"))
node_hub(("CSC hub managers"))

node_app -->|"renders"| node_farmer_ui
node_app -->|"renders"| node_buyer_ui
node_app -->|"opens"| node_ivr_ui
node_app -->|"renders"| node_order_ui
node_app -->|"renders"| node_reputation_ui
node_app -->|"checks health"| node_api_client
node_farmer_ui -->|"requests listings"| node_api_client
node_buyer_ui -->|"loads catalog"| node_api_client
node_ivr_ui -->|"submits IVR"| node_api_client
node_order_ui -->|"manages orders"| node_api_client
node_reputation_ui -->|"loads trust"| node_api_client
node_api_client -->|"uploads photos"| node_listings
node_api_client -->|"places orders"| node_orders
node_api_client -->|"simulates calls"| node_ivr
node_farmers -->|"lists produce"| node_farmer_ui
node_farmers -->|"uses voice listing"| node_ivr_ui
node_buyers -->|"browses produce"| node_buyer_ui
node_hub -->|"scans pickup QR"| node_order_ui
node_api_server -->|"registers router"| node_auth
node_api_server -->|"registers router"| node_listings
node_api_server -->|"registers router"| node_aggregation
node_api_server -->|"registers router"| node_buyer_api
node_api_server -->|"registers router"| node_orders
node_api_server -->|"registers router"| node_pricing
node_api_server -->|"registers router"| node_reputation
node_api_server -->|"registers router"| node_ivr
node_api_server -->|"initializes"| node_database
node_api_server -->|"seeds data"| node_database
node_listings -->|"assigns hub"| node_geo
node_listings -->|"analyzes image"| node_grading
node_listings -->|"calculates price"| node_pricing
node_ivr -->|"assigns hub"| node_geo
node_ivr -->|"calculates price"| node_pricing
node_aggregation -->|"uses routing"| node_geo
node_auth -->|"reads and writes"| node_database
node_listings -->|"reads and writes"| node_database
node_buyer_api -->|"reads catalog"| node_database
node_orders -->|"reads and writes"| node_database
node_reputation -->|"reads trust records"| node_database
node_ivr -->|"reads and writes"| node_database
node_aggregation -->|"reads hubs"| node_database
node_database -->|"maps records"| node_models
node_orders -.->|"updates trust"| node_reputation
node_orders -.->|"releases escrow"| node_hub

click node_farmer_ui "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/frontend/src/components/FarmerPortal.jsx"
click node_buyer_ui "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/frontend/src/components/BuyerCatalog.jsx"
click node_ivr_ui "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/frontend/src/components/IvrSimulatorModal.jsx"
click node_order_ui "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/frontend/src/components/OrderEscrowView.jsx"
click node_reputation_ui "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/frontend/src/components/ReputationView.jsx"
click node_app "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/frontend/src/api/client.js"
click node_auth "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/routers/auth.py"
click node_listings "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/routers/listings.py"
click node_grading "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/services/ai_grading.py"
click node_geo "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/services/geo.py"
click node_pricing "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/services/pricing.py"
click node_aggregation "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/routers/aggregation_points.py"
click node_ivr "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/routers/ivr.py"
click node_buyer_api "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/routers/buyer.py"
click node_orders "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/routers/orders.py"
click node_reputation "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/routers/reputation.py"
click node_database "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/database.py"
click node_models "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/models.py"
click node_api_server "https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/main.py"

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_listings,node_grading,node_geo,node_pricing,node_aggregation,node_ivr toneBlue
class node_buyer_api,node_orders,node_reputation toneAmber
class node_auth,node_database,node_models,node_api_server toneMint
class node_farmer_ui,node_buyer_ui,node_ivr_ui,node_order_ui,node_reputation_ui,node_app,node_api_client toneRose
class node_farmers,node_buyers,node_hub toneIndigo
```

## Components

### Supply and market

- [Produce listings](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/routers/listings.py): `backend/app/routers/listings.py`
- [AI quality grading](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/services/ai_grading.py): `backend/app/services/ai_grading.py`
- [Hub assignment](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/services/geo.py): `backend/app/services/geo.py`
- [Mandi pricing](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/services/pricing.py): `backend/app/services/pricing.py`
- [Aggregation points](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/routers/aggregation_points.py): `backend/app/routers/aggregation_points.py`
- [IVR listing service](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/routers/ivr.py): `backend/app/routers/ivr.py`

### Orders and trust

- [Buyer aggregation](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/routers/buyer.py): `backend/app/routers/buyer.py`
- [Orders and escrow](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/routers/orders.py): `backend/app/routers/orders.py`
- [Trust and disputes](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/routers/reputation.py): `backend/app/routers/reputation.py`

### Backend services

- [Accounts and access](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Relational database](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/database.py): `backend/app/database.py`
- [Domain records](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/app/models.py): `backend/app/models.py`
- [API application](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/backend/main.py): `backend/main.py`

### Frontend experience

- [Farmer studio](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/frontend/src/components/FarmerPortal.jsx): `frontend/src/components/FarmerPortal.jsx`
- [Buyer catalog](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/frontend/src/components/BuyerCatalog.jsx): `frontend/src/components/BuyerCatalog.jsx`
- [IVR simulator](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/frontend/src/components/IvrSimulatorModal.jsx): `frontend/src/components/IvrSimulatorModal.jsx`
- [Escrow pickup view](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/frontend/src/components/OrderEscrowView.jsx): `frontend/src/components/OrderEscrowView.jsx`
- [Reputation center](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/frontend/src/components/ReputationView.jsx): `frontend/src/components/ReputationView.jsx`
- [Application shell](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/santhosh-ek2007-zen/kuralagri/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### Other components

- **Farmers / CSC operators**
- **Commercial buyers**
- **CSC hub managers**

## Connections

- Application shell → Farmer studio: renders (evidence: `frontend/src/App.jsx`)
- Application shell → Buyer catalog: renders (evidence: `frontend/src/App.jsx`)
- Application shell → IVR simulator: opens (evidence: `frontend/src/App.jsx`)
- Application shell → Escrow pickup view: renders (evidence: `frontend/src/App.jsx`)
- Application shell → Reputation center: renders (evidence: `frontend/src/App.jsx`)
- Application shell → API client: checks health (evidence: `frontend/src/App.jsx`)
- Farmer studio → API client: requests listings (evidence: `frontend/src/components/FarmerPortal.jsx`)
- Buyer catalog → API client: loads catalog (evidence: `frontend/src/components/BuyerCatalog.jsx`)
- IVR simulator → API client: submits IVR (evidence: `frontend/src/components/IvrSimulatorModal.jsx`)
- Escrow pickup view → API client: manages orders (evidence: `frontend/src/components/OrderEscrowView.jsx`)
- Reputation center → API client: loads trust (evidence: `frontend/src/components/ReputationView.jsx`)
- API client → Produce listings: uploads photos (evidence: `frontend/src/api/client.js`)
- API client → Orders and escrow: places orders (evidence: `frontend/src/api/client.js`)
- API client → IVR listing service: simulates calls (evidence: `frontend/src/api/client.js`)
- Farmers / CSC operators → Farmer studio: lists produce (evidence: `README.md`)
- Farmers / CSC operators → IVR simulator: uses voice listing (evidence: `README.md`)
- Commercial buyers → Buyer catalog: browses produce (evidence: `README.md`)
- CSC hub managers → Escrow pickup view: scans pickup QR (evidence: `README.md`)
- API application → Accounts and access: registers router (evidence: `backend/main.py`)
- API application → Produce listings: registers router (evidence: `backend/main.py`)
- API application → Aggregation points: registers router (evidence: `backend/main.py`)
- API application → Buyer aggregation: registers router (evidence: `backend/main.py`)
- API application → Orders and escrow: registers router (evidence: `backend/main.py`)
- API application → Mandi pricing: registers router (evidence: `backend/main.py`)
- API application → Trust and disputes: registers router (evidence: `backend/main.py`)
- API application → IVR listing service: registers router (evidence: `backend/main.py`)
- API application → Relational database: initializes (evidence: `backend/main.py`)
- API application → Relational database: seeds data (evidence: `backend/main.py`)
- Produce listings → Hub assignment: assigns hub (evidence: `backend/app/routers/listings.py`)
- Produce listings → AI quality grading: analyzes image (evidence: `backend/app/routers/listings.py`)
- Produce listings → Mandi pricing: calculates price (evidence: `backend/app/routers/listings.py`)
- IVR listing service → Hub assignment: assigns hub (evidence: `backend/app/routers/ivr.py`)
- IVR listing service → Mandi pricing: calculates price (evidence: `backend/app/routers/ivr.py`)
- Aggregation points → Hub assignment: uses routing (evidence: `backend/app/routers/aggregation_points.py`)
- Accounts and access → Relational database: reads and writes (evidence: `backend/app/routers/auth.py`)
- Produce listings → Relational database: reads and writes (evidence: `backend/app/routers/listings.py`)
- Buyer aggregation → Relational database: reads catalog (evidence: `backend/app/routers/buyer.py`)
- Orders and escrow → Relational database: reads and writes (evidence: `backend/app/routers/orders.py`)
- Trust and disputes → Relational database: reads trust records (evidence: `backend/app/routers/reputation.py`)
- IVR listing service → Relational database: reads and writes (evidence: `backend/app/routers/ivr.py`)
- Aggregation points → Relational database: reads hubs (evidence: `backend/app/routers/aggregation_points.py`)
- Relational database → Domain records: maps records (evidence: `backend/app/models.py`)
- Orders and escrow → Trust and disputes: updates trust (evidence: `README.md`)
- Orders and escrow → CSC hub managers: releases escrow (evidence: `README.md`)
