# kathirvbk/ai-agriculture-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/kathirvbk/ai-agriculture-assistant
- Repository: https://github.com/kathirvbk/ai-agriculture-assistant

## Overview

AgriSense is an agricultural advisory platform: users authenticate, submit text or voice consultations (optionally with a soil report), and receive structured, context-aware guidance. The backend API delegates consultation processing to a rules-and-crop pipeline, which can use local retrieval, web search, and an LLM; the API also manages sessions and persisted chat history. The graph preserves documented voice capabilities, though the excerpts do not show their full wiring. Some backend relationships are supported by the source index rather than complete call-site excerpts.

Main entry points: [`backend/core/pipeline.py`](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/core/pipeline.py) (Query Pipeline), [`backend/app.py`](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/app.py) (FastAPI Routes), [`backend/rag/query.py`](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/rag/query.py) (Context Retrieval), [`frontend/src/App.js`](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/frontend/src/App.js) (Consultation UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web Client"]
  node_app_ui["Consultation UI<br/>[App.js]"]
  node_auth_ui["Authentication UI<br/>[AuthPage.js]"]
end

subgraph group_api["API and Sessions"]
  node_api_app["FastAPI Routes<br/>[app.py]"]
  node_chat_store[("Chat Persistence<br/>[database.py]")]
end

subgraph group_advisory["Advisory Workflow"]
  node_pipeline["Query Pipeline<br/>[pipeline.py]"]
  node_crop_rules["Crop Filtering<br/>[crop_engine.py]"]
  node_crop_facts["Crop Knowledge<br/>[crop_info.py]"]
  node_validation["Query Validation<br/>[validator.py]"]
  node_guardrails["Agricultural Guardrails<br/>[guardrails.py]"]
  node_context_manifest["Context Manifest"]
end

subgraph group_knowledge["Knowledge and Synthesis"]
  node_rag_query["Context Retrieval<br/>[query.py]"]
  node_rag_pipeline["Semantic Retrieval<br/>[rag_pipeline.py]"]
  node_vector_store[("Vector Store<br/>[vector_store.py]")]
  node_embeddings["Embeddings<br/>[embeddings.py]"]
  node_web_search["Web Search<br/>[web_agent.py]"]
  node_llm["Answer Generation<br/>[llm.py]"]
end

subgraph group_identity["Identity and Voice"]
  node_firebase["Firebase Client<br/>[firebase.js]"]
  node_firebase_auth["Backend Token Verification<br/>[firebase_auth.py]"]
  node_voice["Voice Services"]
end

node_farmer(("Farmer"))

node_farmer -->|"consults through"| node_app_ui
node_app_ui -->|"sends API requests"| node_api_app
node_app_ui -->|"renders"| node_auth_ui
node_auth_ui -->|"signs in with"| node_firebase
node_app_ui -->|"signs out with"| node_firebase
node_api_app -->|"verifies tokens"| node_firebase_auth
node_api_app -->|"persists sessions"| node_chat_store
node_api_app -->|"runs queries"| node_pipeline
node_api_app -->|"validates requests"| node_validation
node_api_app -.->|"serves voice features"| node_voice
node_pipeline -->|"filters crops"| node_crop_rules
node_pipeline -->|"validates and grounds"| node_validation
node_pipeline -->|"applies guardrails"| node_guardrails
node_pipeline -->|"retrieves context"| node_rag_query
node_pipeline -->|"generates guidance"| node_llm
node_pipeline -->|"assembles source context"| node_context_manifest
node_crop_rules -->|"uses crop data"| node_crop_facts
node_rag_query -->|"checks and grounds"| node_validation
node_rag_query -->|"retrieves local context"| node_rag_pipeline
node_rag_query -->|"fetches web context"| node_web_search
node_rag_query -->|"synthesizes response"| node_llm
node_rag_pipeline -->|"searches vectors"| node_vector_store
node_vector_store -->|"uses embeddings"| node_embeddings

click node_app_ui "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/frontend/src/App.js"
click node_auth_ui "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/frontend/src/components/Auth/AuthPage.js"
click node_api_app "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/app.py"
click node_chat_store "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/core/database.py"
click node_pipeline "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/core/pipeline.py"
click node_crop_rules "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/core/crop_engine.py"
click node_crop_facts "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/knowledge/crop_info.py"
click node_validation "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/utils/validator.py"
click node_guardrails "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/utils/guardrails.py"
click node_context_manifest "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/utils/context_classifier.py"
click node_rag_query "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/rag/query.py"
click node_rag_pipeline "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/rag/rag_pipeline.py"
click node_vector_store "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/rag/vector_store.py"
click node_embeddings "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/rag/embeddings.py"
click node_web_search "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/agents/web_agent.py"
click node_llm "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/rag/llm.py"
click node_firebase "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/frontend/src/firebase.js"
click node_firebase_auth "https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/utils/firebase_auth.py"
click node_voice "https://github.com/kathirvbk/ai-agriculture-assistant/tree/main/backend/voice"

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_ui,node_auth_ui toneBlue
class node_api_app,node_chat_store toneAmber
class node_pipeline,node_crop_rules,node_crop_facts,node_validation,node_guardrails,node_context_manifest toneMint
class node_rag_query,node_rag_pipeline,node_vector_store,node_embeddings,node_web_search,node_llm toneRose
class node_firebase,node_firebase_auth,node_voice,node_farmer toneIndigo
```

## Components

### Web Client

- [Consultation UI](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/frontend/src/App.js): `frontend/src/App.js`
- [Authentication UI](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/frontend/src/components/Auth/AuthPage.js): `frontend/src/components/Auth/AuthPage.js`

### API and Sessions

- [FastAPI Routes](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/app.py): `backend/app.py`
- [Chat Persistence](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/core/database.py): `backend/core/database.py`

### Advisory Workflow

- [Query Pipeline](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/core/pipeline.py): `backend/core/pipeline.py`
- [Crop Filtering](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/core/crop_engine.py): `backend/core/crop_engine.py`
- [Crop Knowledge](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/knowledge/crop_info.py): `backend/knowledge/crop_info.py`
- [Query Validation](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/utils/validator.py): `backend/utils/validator.py`
- [Agricultural Guardrails](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/utils/guardrails.py): `backend/utils/guardrails.py`
- [Context Manifest](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/utils/context_classifier.py): `backend/utils/context_classifier.py`

### Knowledge and Synthesis

- [Context Retrieval](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/rag/query.py): `backend/rag/query.py`
- [Semantic Retrieval](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/rag/rag_pipeline.py): `backend/rag/rag_pipeline.py`
- [Vector Store](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/rag/vector_store.py): `backend/rag/vector_store.py`
- [Embeddings](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/rag/embeddings.py): `backend/rag/embeddings.py`
- [Web Search](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/agents/web_agent.py): `backend/agents/web_agent.py`
- [Answer Generation](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/rag/llm.py): `backend/rag/llm.py`

### Identity and Voice

- [Firebase Client](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/frontend/src/firebase.js): `frontend/src/firebase.js`
- [Backend Token Verification](https://github.com/kathirvbk/ai-agriculture-assistant/blob/main/backend/utils/firebase_auth.py): `backend/utils/firebase_auth.py`
- [Voice Services](https://github.com/kathirvbk/ai-agriculture-assistant/tree/main/backend/voice): `backend/voice`

### Other components

- **Farmer**

## Connections

- Farmer → Consultation UI: consults through (evidence: `README.md`)
- Consultation UI → FastAPI Routes: sends API requests (evidence: `README.md`)
- Consultation UI → Authentication UI: renders (evidence: `frontend/src/App.js`)
- Authentication UI → Firebase Client: signs in with (evidence: `frontend/src/components/Auth/AuthPage.js`)
- Consultation UI → Firebase Client: signs out with (evidence: `frontend/src/App.js`)
- FastAPI Routes → Backend Token Verification: verifies tokens (evidence: `backend/app.py`)
- FastAPI Routes → Chat Persistence: persists sessions (evidence: `backend/app.py`)
- FastAPI Routes → Query Pipeline: runs queries (evidence: `backend/app.py`)
- FastAPI Routes → Query Validation: validates requests (evidence: `backend/app.py`)
- FastAPI Routes → Voice Services: serves voice features (evidence: `README.md`)
- Query Pipeline → Crop Filtering: filters crops (evidence: `backend/core/pipeline.py`)
- Query Pipeline → Query Validation: validates and grounds (evidence: `backend/core/pipeline.py`)
- Query Pipeline → Agricultural Guardrails: applies guardrails (evidence: `backend/core/pipeline.py`)
- Query Pipeline → Context Retrieval: retrieves context (evidence: `backend/core/pipeline.py`)
- Query Pipeline → Answer Generation: generates guidance (evidence: `backend/core/pipeline.py`)
- Query Pipeline → Context Manifest: assembles source context (evidence: `backend/core/pipeline.py`)
- Crop Filtering → Crop Knowledge: uses crop data (evidence: `backend/core/crop_engine.py`)
- Context Retrieval → Query Validation: checks and grounds (evidence: `backend/rag/query.py`)
- Context Retrieval → Semantic Retrieval: retrieves local context (evidence: `backend/rag/query.py`)
- Context Retrieval → Web Search: fetches web context (evidence: `backend/rag/query.py`)
- Context Retrieval → Answer Generation: synthesizes response (evidence: `backend/rag/query.py`)
- Semantic Retrieval → Vector Store: searches vectors (evidence: `backend/rag/rag_pipeline.py`)
- Vector Store → Embeddings: uses embeddings (evidence: `backend/rag/vector_store.py`)
