# advaetuc/balram architecture

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

- Interactive diagram: https://gitdiagram.com/advaetuc/balram
- Repository: https://github.com/advaetuc/balram

## Overview

Balram is a local-first Maharashtra farm-planning app: farmers define a field, record plots and soil information, plan crops and water, track check-ins, and produce a shareable or printable report. The graph separates the farmer-facing workflow, planning calculations, browser persistence, and provider-backed context. The README documents several capabilities whose implementation files were not sampled; their links are shown only where documented, and source-level call edges are limited to visible excerpts or indexed references.

Main entry points: [`src/store/useBalramStore.ts`](https://github.com/advaetuc/balram/blob/main/src/store/useBalramStore.ts) (Farm state), [`src/components/report/FarmReport.tsx`](https://github.com/advaetuc/balram/blob/main/src/components/report/FarmReport.tsx) (Farm report), [`src/components/journey/JourneyShell.tsx`](https://github.com/advaetuc/balram/blob/main/src/components/journey/JourneyShell.tsx) (Growing Path), [`src/lib/api/server.ts`](https://github.com/advaetuc/balram/blob/main/src/lib/api/server.ts) (Provider request controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Farm experience"]
  node_app["Farm app<br/>[page.tsx]"]
  node_journey["Growing Path<br/>[JourneyShell.tsx]"]
  node_field["Field mapping<br/>[MapClient.tsx]"]
  node_cropcheckout["Crop checkout"]
  node_soilcard["Soil health card<br/>[SoilCard.tsx]"]
  node_irrigationui["Irrigation tools"]
  node_daily["Daily planning<br/>[DailyHome.tsx]"]
  node_checkins["Farm check-ins<br/>[CheckInCard.tsx]"]
  node_report["Farm report<br/>[FarmReport.tsx]"]
  node_backup["Backup and restore<br/>[BackupControls.tsx]"]
end

subgraph group_planning["Planning domain"]
  node_geometry["Field geometry<br/>[geometry.ts]"]
  node_checkout["Plot allocation<br/>[checkout.ts]"]
  node_cropadvice["Crop advice"]
  node_soilmodel["Soil interpretation<br/>[soilKit.ts]"]
  node_watermodel["Water estimates<br/>[irrigation.ts]"]
  node_fieldvoice["Field Voice<br/>[fieldVoice.ts]"]
  node_roadmap["Prioritized roadmap<br/>[roadmap.ts]"]
end

subgraph group_state["Local farm state"]
  node_store["Farm state<br/>[useBalramStore.ts]"]
  node_indexeddb[("IndexedDB storage<br/>[db.ts]")]
  node_backupformat["Backup format<br/>[backup.ts]"]
end

subgraph group_providers["Provider context"]
  node_api["API client<br/>[client.ts]"]
  node_routes["Provider proxy routes<br/>[route.ts]"]
  node_server["Provider request controls<br/>[server.ts]"]
end

node_farmer(("Farmer"))
node_weatherprovider(("Open-Meteo"))
node_geocodeprovider(("Nominatim"))
node_soilprovider(("SoilGrids"))
node_marketprovider(("Agmarknet"))

node_farmer -->|"uses"| node_app
node_app -.->|"guides setup"| node_journey
node_journey -.->|"defines field"| node_field
node_journey -.->|"records soil"| node_soilcard
node_journey -.->|"plans crops"| node_cropcheckout
node_journey -.->|"presents priorities"| node_roadmap
node_field -->|"calculates geometry"| node_geometry
node_field -->|"saves field"| node_store
node_cropcheckout -->|"commits allocations"| node_checkout
node_cropcheckout -->|"saves allocations"| node_store
node_soilcard -->|"interprets readings"| node_soilmodel
node_soilcard -->|"reads farm state"| node_store
node_irrigationui -->|"calculates estimates"| node_watermodel
node_irrigationui -->|"reads farm state"| node_store
node_daily -.->|"presents advice"| node_fieldvoice
node_daily -.->|"shows priorities"| node_roadmap
node_checkins -.->|"records check-ins"| node_store
node_report -->|"reads farm state"| node_store
node_report -->|"uses estimates"| node_watermodel
node_report -->|"uses interpretation"| node_soilmodel
node_report -->|"includes advisories"| node_fieldvoice
node_report -->|"includes roadmap"| node_roadmap
node_backup -.->|"validates backup"| node_backupformat
node_backup -.->|"restores farm state"| node_store
node_store -->|"persists state"| node_indexeddb
node_app -.->|"requests context"| node_api
node_api -.->|"calls same-origin routes"| node_routes
node_routes -->|"delegates requests"| node_server
node_routes -.->|"fetches forecast"| node_weatherprovider
node_server -.->|"caches provider data"| node_weatherprovider
node_server -->|"routes geocoding"| node_geocodeprovider
node_server -.->|"provider disabled"| node_soilprovider
node_server -.->|"provider disabled"| node_marketprovider

click node_app "https://github.com/advaetuc/balram/blob/main/src/app/(app)/page.tsx"
click node_journey "https://github.com/advaetuc/balram/blob/main/src/components/journey/JourneyShell.tsx"
click node_field "https://github.com/advaetuc/balram/blob/main/src/components/map/MapClient.tsx"
click node_cropcheckout "https://github.com/advaetuc/balram/blob/main/src/components/crops/CropCheckoutSheet.tsx"
click node_soilcard "https://github.com/advaetuc/balram/blob/main/src/components/dashboard/SoilCard.tsx"
click node_irrigationui "https://github.com/advaetuc/balram/blob/main/src/components/irrigation/IrrigationPanel.tsx"
click node_daily "https://github.com/advaetuc/balram/blob/main/src/components/home/DailyHome.tsx"
click node_checkins "https://github.com/advaetuc/balram/blob/main/src/components/home/CheckInCard.tsx"
click node_report "https://github.com/advaetuc/balram/blob/main/src/components/report/FarmReport.tsx"
click node_backup "https://github.com/advaetuc/balram/blob/main/src/components/home/BackupControls.tsx"
click node_geometry "https://github.com/advaetuc/balram/blob/main/src/lib/domain/geometry.ts"
click node_checkout "https://github.com/advaetuc/balram/blob/main/src/lib/domain/checkout.ts"
click node_cropadvice "https://github.com/advaetuc/balram/blob/main/src/lib/domain/cropRecommendations.ts"
click node_soilmodel "https://github.com/advaetuc/balram/blob/main/src/lib/domain/soilKit.ts"
click node_watermodel "https://github.com/advaetuc/balram/blob/main/src/lib/domain/irrigation.ts"
click node_fieldvoice "https://github.com/advaetuc/balram/blob/main/src/lib/domain/fieldVoice.ts"
click node_roadmap "https://github.com/advaetuc/balram/blob/main/src/lib/domain/roadmap.ts"
click node_store "https://github.com/advaetuc/balram/blob/main/src/store/useBalramStore.ts"
click node_indexeddb "https://github.com/advaetuc/balram/blob/main/src/lib/storage/db.ts"
click node_backupformat "https://github.com/advaetuc/balram/blob/main/src/lib/storage/backup.ts"
click node_api "https://github.com/advaetuc/balram/blob/main/src/lib/api/client.ts"
click node_routes "https://github.com/advaetuc/balram/blob/main/src/app/api/weather/route.ts"
click node_server "https://github.com/advaetuc/balram/blob/main/src/lib/api/server.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_app,node_journey,node_field,node_cropcheckout,node_soilcard,node_irrigationui,node_daily,node_checkins,node_report,node_backup toneBlue
class node_geometry,node_checkout,node_cropadvice,node_soilmodel,node_watermodel,node_fieldvoice,node_roadmap toneAmber
class node_store,node_indexeddb,node_backupformat toneMint
class node_api,node_routes,node_server toneRose
class node_farmer,node_weatherprovider,node_geocodeprovider,node_soilprovider,node_marketprovider toneIndigo
```

## Components

### Farm experience

- [Farm app](https://github.com/advaetuc/balram/blob/main/src/app/(app)/page.tsx): `src/app/(app)/page.tsx`
- [Growing Path](https://github.com/advaetuc/balram/blob/main/src/components/journey/JourneyShell.tsx): `src/components/journey/JourneyShell.tsx`
- [Field mapping](https://github.com/advaetuc/balram/blob/main/src/components/map/MapClient.tsx): `src/components/map/MapClient.tsx`
- [Crop checkout](https://github.com/advaetuc/balram/blob/main/src/components/crops/CropCheckoutSheet.tsx): `src/components/crops/CropCheckoutSheet.tsx`
- [Soil health card](https://github.com/advaetuc/balram/blob/main/src/components/dashboard/SoilCard.tsx): `src/components/dashboard/SoilCard.tsx`
- [Irrigation tools](https://github.com/advaetuc/balram/blob/main/src/components/irrigation/IrrigationPanel.tsx): `src/components/irrigation/IrrigationPanel.tsx`
- [Daily planning](https://github.com/advaetuc/balram/blob/main/src/components/home/DailyHome.tsx): `src/components/home/DailyHome.tsx`
- [Farm check-ins](https://github.com/advaetuc/balram/blob/main/src/components/home/CheckInCard.tsx): `src/components/home/CheckInCard.tsx`
- [Farm report](https://github.com/advaetuc/balram/blob/main/src/components/report/FarmReport.tsx): `src/components/report/FarmReport.tsx`
- [Backup and restore](https://github.com/advaetuc/balram/blob/main/src/components/home/BackupControls.tsx): `src/components/home/BackupControls.tsx`

### Planning domain

- [Field geometry](https://github.com/advaetuc/balram/blob/main/src/lib/domain/geometry.ts): `src/lib/domain/geometry.ts`
- [Plot allocation](https://github.com/advaetuc/balram/blob/main/src/lib/domain/checkout.ts): `src/lib/domain/checkout.ts`
- [Crop advice](https://github.com/advaetuc/balram/blob/main/src/lib/domain/cropRecommendations.ts): `src/lib/domain/cropRecommendations.ts`
- [Soil interpretation](https://github.com/advaetuc/balram/blob/main/src/lib/domain/soilKit.ts): `src/lib/domain/soilKit.ts`
- [Water estimates](https://github.com/advaetuc/balram/blob/main/src/lib/domain/irrigation.ts): `src/lib/domain/irrigation.ts`
- [Field Voice](https://github.com/advaetuc/balram/blob/main/src/lib/domain/fieldVoice.ts): `src/lib/domain/fieldVoice.ts`
- [Prioritized roadmap](https://github.com/advaetuc/balram/blob/main/src/lib/domain/roadmap.ts): `src/lib/domain/roadmap.ts`

### Local farm state

- [Farm state](https://github.com/advaetuc/balram/blob/main/src/store/useBalramStore.ts): `src/store/useBalramStore.ts`
- [IndexedDB storage](https://github.com/advaetuc/balram/blob/main/src/lib/storage/db.ts): `src/lib/storage/db.ts`
- [Backup format](https://github.com/advaetuc/balram/blob/main/src/lib/storage/backup.ts): `src/lib/storage/backup.ts`

### Provider context

- [API client](https://github.com/advaetuc/balram/blob/main/src/lib/api/client.ts): `src/lib/api/client.ts`
- [Provider proxy routes](https://github.com/advaetuc/balram/blob/main/src/app/api/weather/route.ts): `src/app/api/weather/route.ts`
- [Provider request controls](https://github.com/advaetuc/balram/blob/main/src/lib/api/server.ts): `src/lib/api/server.ts`

### Other components

- **Farmer**
- **Open-Meteo**
- **Nominatim**
- **SoilGrids**
- **Agmarknet**

## Connections

- Farmer → Farm app: uses
- Farm app → Growing Path: guides setup
- Growing Path → Field mapping: defines field
- Growing Path → Soil health card: records soil
- Growing Path → Crop checkout: plans crops
- Growing Path → Prioritized roadmap: presents priorities
- Field mapping → Field geometry: calculates geometry (evidence: `src/components/map/MapClient.tsx`)
- Field mapping → Farm state: saves field (evidence: `src/components/map/MapClient.tsx`)
- Crop checkout → Plot allocation: commits allocations (evidence: `src/components/crops/CropCheckoutSheet.tsx`)
- Crop checkout → Farm state: saves allocations (evidence: `src/components/crops/CropCheckoutSheet.tsx`)
- Soil health card → Soil interpretation: interprets readings (evidence: `src/components/dashboard/SoilCard.tsx`)
- Soil health card → Farm state: reads farm state (evidence: `src/components/dashboard/SoilCard.tsx`)
- Irrigation tools → Water estimates: calculates estimates (evidence: `src/components/irrigation/IrrigationPanel.tsx`)
- Irrigation tools → Farm state: reads farm state (evidence: `src/components/irrigation/IrrigationPanel.tsx`)
- Daily planning → Field Voice: presents advice
- Daily planning → Prioritized roadmap: shows priorities
- Farm check-ins → Farm state: records check-ins
- Farm report → Farm state: reads farm state (evidence: `src/components/report/FarmReport.tsx`)
- Farm report → Water estimates: uses estimates (evidence: `src/components/report/FarmReport.tsx`)
- Farm report → Soil interpretation: uses interpretation (evidence: `src/components/report/FarmReport.tsx`)
- Farm report → Field Voice: includes advisories (evidence: `src/components/report/FarmReport.tsx`)
- Farm report → Prioritized roadmap: includes roadmap
- Backup and restore → Backup format: validates backup
- Backup and restore → Farm state: restores farm state
- Farm state → IndexedDB storage: persists state (evidence: `src/store/useBalramStore.ts`)
- Farm app → API client: requests context
- API client → Provider proxy routes: calls same-origin routes
- Provider proxy routes → Provider request controls: delegates requests (evidence: `src/app/api/weather/route.ts`)
- Provider proxy routes → Open-Meteo: fetches forecast
- Provider request controls → Open-Meteo: caches provider data
- Provider request controls → Nominatim: routes geocoding
- Provider request controls → SoilGrids: provider disabled
- Provider request controls → Agmarknet: provider disabled
