# devbaghel-02/kisan-helpline architecture

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

- Interactive diagram: https://gitdiagram.com/devbaghel-02/kisan-helpline
- Repository: https://github.com/devbaghel-02/kisan-helpline

## Overview

Kisan Helpline takes farmer questions through a web interface or keypad-phone call, identifies crop, mandi, intent and date, then returns a grounded Punjabi or Hindi response as text and speech. Its distinct answer branches cover mandi prices, weather forecasts and government schemes; admins can upload price data and inspect query logs. Phone calls share the answering pipeline, while the simulator adds phone-quality audio processing. The graph follows the README and sampled excerpts; unsampled route details are represented only where documented.

Main entry points: [`app/main.py`](https://github.com/devbaghel-02/kisan-helpline/blob/main/app/main.py) (FastAPI Routes), [`app/pipeline.py`](https://github.com/devbaghel-02/kisan-helpline/blob/main/app/pipeline.py) (Answer Pipeline), [`app/data.py`](https://github.com/devbaghel-02/kisan-helpline/blob/main/app/data.py) (Price Database), [`app/intent.py`](https://github.com/devbaghel-02/kisan-helpline/blob/main/app/intent.py) (Intent and Slots)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Farmer Interfaces"]
  node_web_ui["Farmer Website<br/>[index.html]"]
  node_phone_ui["Phone Simulator UI<br/>[phone.html]"]
  node_admin_ui["Admin Panel<br/>[admin.html]"]
  node_api["FastAPI Routes<br/>[main.py]"]
end

subgraph group_calls["Call Handling"]
  node_phone_flow["Phone Call Flow<br/>[phone.py]"]
  node_line_audio["Phone Audio Filter<br/>[phoneline.py]"]
end

subgraph group_understanding["Question Understanding"]
  node_pipeline["Answer Pipeline<br/>[pipeline.py]"]
  node_speech["Speech ASR and TTS<br/>[speech.py]"]
  node_intent["Intent and Slots<br/>[intent.py]"]
  node_normalise["Fuzzy Normalisation<br/>[normalise.py]"]
  node_synonyms["Crop and Mandi Synonyms<br/>[synonyms.json]"]
end

subgraph group_answers["Grounded Answers"]
  node_answer["Grounded Answer Builder<br/>[answer.py]"]
  node_weather["Weather Forecasts<br/>[weather.py]"]
  node_scheme_data["Scheme Catalogue<br/>[schemes.json]"]
end

subgraph group_data_admin["Data and Admin"]
  node_price_db[("Price Database<br/>[data.py]")]
  node_price_csv["Sample Price Data<br/>[sample_prices.csv]"]
  node_config["Environment Config<br/>[config.py]"]
end

node_farmer(("Farmer"))
node_weather_service["Weather Providers"]
node_speech_service["Speech Providers"]

node_farmer -->|"asks through"| node_web_ui
node_farmer -->|"asks through"| node_phone_ui
node_farmer -->|"manages data"| node_admin_ui
node_web_ui -->|"submits questions"| node_api
node_phone_ui -->|"uses simulator"| node_api
node_admin_ui -->|"uploads CSV"| node_api
node_api -->|"routes questions"| node_pipeline
node_api -->|"mounts routes"| node_phone_flow
node_api -->|"imports and logs"| node_price_db
node_api -->|"refreshes matchers"| node_intent
node_api -->|"loads settings"| node_config
node_phone_flow -->|"answers recordings"| node_pipeline
node_phone_flow -->|"filters simulator audio"| node_line_audio
node_phone_flow -->|"plays generated audio"| node_speech
node_pipeline -->|"transcribes and speaks"| node_speech
node_pipeline -->|"parses alternatives"| node_intent
node_pipeline -->|"builds response"| node_answer
node_pipeline -->|"logs query"| node_price_db
node_intent -->|"matches text"| node_normalise
node_intent -->|"loads market names"| node_price_db
node_intent -->|"uses vocabulary"| node_synonyms
node_answer -->|"reads prices"| node_price_db
node_answer -->|"requests forecast"| node_weather
node_answer -->|"reads scheme facts"| node_scheme_data
node_weather -->|"fetches forecast"| node_weather_service
node_speech -->|"uses ASR and TTS"| node_speech_service
node_admin_ui -->|"reviews logs"| node_price_db
node_price_csv -.->|"provides sample rows"| node_price_db

click node_web_ui "https://github.com/devbaghel-02/kisan-helpline/blob/main/static/index.html"
click node_phone_ui "https://github.com/devbaghel-02/kisan-helpline/blob/main/static/phone.html"
click node_admin_ui "https://github.com/devbaghel-02/kisan-helpline/blob/main/static/admin.html"
click node_api "https://github.com/devbaghel-02/kisan-helpline/blob/main/app/main.py"
click node_phone_flow "https://github.com/devbaghel-02/kisan-helpline/blob/main/app/phone.py"
click node_line_audio "https://github.com/devbaghel-02/kisan-helpline/blob/main/app/phoneline.py"
click node_pipeline "https://github.com/devbaghel-02/kisan-helpline/blob/main/app/pipeline.py"
click node_speech "https://github.com/devbaghel-02/kisan-helpline/blob/main/app/speech.py"
click node_intent "https://github.com/devbaghel-02/kisan-helpline/blob/main/app/intent.py"
click node_normalise "https://github.com/devbaghel-02/kisan-helpline/blob/main/app/normalise.py"
click node_answer "https://github.com/devbaghel-02/kisan-helpline/blob/main/app/answer.py"
click node_weather "https://github.com/devbaghel-02/kisan-helpline/blob/main/app/weather.py"
click node_scheme_data "https://github.com/devbaghel-02/kisan-helpline/blob/main/data/schemes.json"
click node_price_db "https://github.com/devbaghel-02/kisan-helpline/blob/main/app/data.py"
click node_price_csv "https://github.com/devbaghel-02/kisan-helpline/blob/main/data/sample_prices.csv"
click node_synonyms "https://github.com/devbaghel-02/kisan-helpline/blob/main/data/synonyms.json"
click node_config "https://github.com/devbaghel-02/kisan-helpline/blob/main/app/config.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_web_ui,node_phone_ui,node_admin_ui,node_api toneBlue
class node_phone_flow,node_line_audio toneAmber
class node_pipeline,node_speech,node_intent,node_normalise,node_synonyms toneMint
class node_answer,node_weather,node_scheme_data toneRose
class node_price_db,node_price_csv,node_config,node_farmer,node_weather_service,node_speech_service toneIndigo
```

## Components

### Farmer Interfaces

- [Farmer Website](https://github.com/devbaghel-02/kisan-helpline/blob/main/static/index.html): `static/index.html`
- [Phone Simulator UI](https://github.com/devbaghel-02/kisan-helpline/blob/main/static/phone.html): `static/phone.html`
- [Admin Panel](https://github.com/devbaghel-02/kisan-helpline/blob/main/static/admin.html): `static/admin.html`
- [FastAPI Routes](https://github.com/devbaghel-02/kisan-helpline/blob/main/app/main.py): `app/main.py`

### Call Handling

- [Phone Call Flow](https://github.com/devbaghel-02/kisan-helpline/blob/main/app/phone.py): `app/phone.py`
- [Phone Audio Filter](https://github.com/devbaghel-02/kisan-helpline/blob/main/app/phoneline.py): `app/phoneline.py`

### Question Understanding

- [Answer Pipeline](https://github.com/devbaghel-02/kisan-helpline/blob/main/app/pipeline.py): `app/pipeline.py`
- [Speech ASR and TTS](https://github.com/devbaghel-02/kisan-helpline/blob/main/app/speech.py): `app/speech.py`
- [Intent and Slots](https://github.com/devbaghel-02/kisan-helpline/blob/main/app/intent.py): `app/intent.py`
- [Fuzzy Normalisation](https://github.com/devbaghel-02/kisan-helpline/blob/main/app/normalise.py): `app/normalise.py`
- [Crop and Mandi Synonyms](https://github.com/devbaghel-02/kisan-helpline/blob/main/data/synonyms.json): `data/synonyms.json`

### Grounded Answers

- [Grounded Answer Builder](https://github.com/devbaghel-02/kisan-helpline/blob/main/app/answer.py): `app/answer.py`
- [Weather Forecasts](https://github.com/devbaghel-02/kisan-helpline/blob/main/app/weather.py): `app/weather.py`
- [Scheme Catalogue](https://github.com/devbaghel-02/kisan-helpline/blob/main/data/schemes.json): `data/schemes.json`

### Data and Admin

- [Price Database](https://github.com/devbaghel-02/kisan-helpline/blob/main/app/data.py): `app/data.py`
- [Sample Price Data](https://github.com/devbaghel-02/kisan-helpline/blob/main/data/sample_prices.csv): `data/sample_prices.csv`
- [Environment Config](https://github.com/devbaghel-02/kisan-helpline/blob/main/app/config.py): `app/config.py`

### Other components

- **Farmer**
- **Weather Providers**
- **Speech Providers**

## Connections

- Farmer → Farmer Website: asks through (evidence: `README.md`)
- Farmer → Phone Simulator UI: asks through (evidence: `README.md`)
- Farmer → Admin Panel: manages data (evidence: `README.md`)
- Farmer Website → FastAPI Routes: submits questions (evidence: `README.md`)
- Phone Simulator UI → FastAPI Routes: uses simulator (evidence: `README.md`)
- Admin Panel → FastAPI Routes: uploads CSV (evidence: `app/main.py`)
- FastAPI Routes → Answer Pipeline: routes questions (evidence: `app/main.py`)
- FastAPI Routes → Phone Call Flow: mounts routes (evidence: `app/main.py`)
- FastAPI Routes → Price Database: imports and logs (evidence: `app/main.py`)
- FastAPI Routes → Intent and Slots: refreshes matchers (evidence: `app/main.py`)
- FastAPI Routes → Environment Config: loads settings (evidence: `app/main.py`)
- Phone Call Flow → Answer Pipeline: answers recordings (evidence: `app/phone.py`)
- Phone Call Flow → Phone Audio Filter: filters simulator audio (evidence: `app/phone.py`)
- Phone Call Flow → Speech ASR and TTS: plays generated audio (evidence: `app/phone.py`)
- Answer Pipeline → Speech ASR and TTS: transcribes and speaks (evidence: `app/pipeline.py`)
- Answer Pipeline → Intent and Slots: parses alternatives (evidence: `app/pipeline.py`)
- Answer Pipeline → Grounded Answer Builder: builds response (evidence: `app/pipeline.py`)
- Answer Pipeline → Price Database: logs query (evidence: `app/pipeline.py`)
- Intent and Slots → Fuzzy Normalisation: matches text (evidence: `app/intent.py`)
- Intent and Slots → Price Database: loads market names (evidence: `app/intent.py`)
- Intent and Slots → Crop and Mandi Synonyms: uses vocabulary (evidence: `README.md`)
- Grounded Answer Builder → Price Database: reads prices (evidence: `app/answer.py`)
- Grounded Answer Builder → Weather Forecasts: requests forecast (evidence: `app/answer.py`)
- Grounded Answer Builder → Scheme Catalogue: reads scheme facts (evidence: `README.md`)
- Weather Forecasts → Weather Providers: fetches forecast (evidence: `app/weather.py`)
- Speech ASR and TTS → Speech Providers: uses ASR and TTS (evidence: `README.md`)
- Admin Panel → Price Database: reviews logs (evidence: `README.md`)
- Sample Price Data → Price Database: provides sample rows
