# iamgojoof6eyes/farmersfeedback architecture

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

- Interactive diagram: https://gitdiagram.com/iamgojoof6eyes/farmersfeedback
- Repository: https://github.com/iamgojoof6eyes/farmersfeedback

## Overview

AjraSakha is a farmer-feedback and answer-quality system for the AjraSakha agricultural advisory bot. Farmers submit WhatsApp text, quick replies, or voice feedback; the backend associates feedback with knowledge-base answers, tracks sessions and metrics, and flags poor-performing answers for agronomist review. The dashboard exposes analytics, resolution, catalog, digest, and weather views. Evidence includes README capabilities and indexed imports, but several feature modules were not sampled, so their internal call paths are not asserted.

Main entry points: [`backend/app/main.py`](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/main.py) (FastAPI application), [`frontend/src/App.tsx`](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/App.tsx) (Dashboard routes), [`backend/app/database.py`](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/database.py) (MongoDB collections), [`helpers/flagging_pipeline.py`](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/flagging_pipeline.py) (Statistical flagging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Review dashboard"]
  node_web_app["Dashboard routes<br/>[App.tsx]"]
  node_dashboard_state["Dashboard state<br/>[feedbackSlice.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_analytics_ui["Analytics view<br/>[AnalyticsView.tsx]"]
  node_flagged_ui["Flagged queue"]
  node_whatsapp_ui["WhatsApp simulator"]
  node_gdb_ui["GDB catalog<br/>[GdbCatalogView.tsx]"]
  node_digest_ui["Weekly bulletin"]
  node_weather_ui["Weather advisories"]
end

subgraph group_backend["Backend API"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_config["Runtime settings<br/>[config.py]"]
  node_database[("MongoDB collections<br/>[database.py]")]
  node_scheduler["Scheduled jobs<br/>[scheduler.py]"]
end

subgraph group_quality["Feedback quality"]
  node_flagged_router["Flagged review endpoints<br/>[flagged.py]"]
  node_flagging["Statistical flagging"]
  node_nvidia["Answer generation<br/>[nvidia_service.py]"]
  node_gdb_router["Knowledge catalog endpoints<br/>[gdb.py]"]
end

subgraph group_farmer["Farmer messaging"]
  node_whatsapp_router["WhatsApp endpoints<br/>[whatsapp.py]"]
  node_whatsapp_service["Interaction processing"]
  node_twilio["Twilio messaging<br/>[twilio_service.py]"]
  node_session_pipeline["Session and feedback"]
  node_voice_nlp["Voice feedback NLP"]
end

subgraph group_insights["Insights and advisories"]
  node_analytics_router["Analytics endpoints<br/>[analytics.py]"]
  node_digest_router["Digest endpoints<br/>[digest.py]"]
  node_digest_service["Digest generation<br/>[digest_service.py]"]
  node_weather_router["Weather endpoints<br/>[weather.py]"]
  node_weather_service["Weather risk service<br/>[weather_service.py]"]
end

node_farmer_actor(("Farmer"))
node_agronomist(("Agronomist"))

node_web_app -->|"dispatches"| node_dashboard_state
node_dashboard_state -->|"requests data"| node_api_client
node_web_app -->|"routes to"| node_analytics_ui
node_web_app -->|"routes to"| node_flagged_ui
node_web_app -->|"routes to"| node_whatsapp_ui
node_web_app -->|"routes to"| node_gdb_ui
node_web_app -->|"routes to"| node_digest_ui
node_web_app -->|"routes to"| node_weather_ui
node_api_app -->|"registers"| node_whatsapp_router
node_api_app -->|"registers"| node_gdb_router
node_api_app -->|"registers"| node_analytics_router
node_api_app -->|"registers"| node_flagged_router
node_api_app -->|"registers"| node_digest_router
node_api_app -->|"registers"| node_weather_router
node_api_app -->|"initializes"| node_database
node_api_app -->|"starts"| node_scheduler
node_whatsapp_router -->|"processes interaction"| node_whatsapp_service
node_whatsapp_router -->|"creates sessions"| node_session_pipeline
node_whatsapp_router -->|"sends messages"| node_twilio
node_whatsapp_service -->|"reads and writes"| node_database
node_whatsapp_service -->|"evaluates answers"| node_flagging
node_whatsapp_service -->|"analyzes voice"| node_voice_nlp
node_session_pipeline -->|"updates records"| node_database
node_session_pipeline -->|"evaluates answers"| node_flagging
node_session_pipeline -->|"notifies farmer"| node_twilio
node_flagged_router -->|"runs review pipeline"| node_flagging
node_flagged_router -->|"reads and writes"| node_database
node_flagging -->|"scores entries"| node_database
node_flagging -->|"generates replacements"| node_nvidia
node_gdb_router -->|"reads catalog"| node_database
node_analytics_router -.->|"serves metrics"| node_database
node_digest_router -->|"requests digest"| node_digest_service
node_weather_router -->|"requests advisories"| node_weather_service
node_scheduler -->|"schedules scans"| node_flagging
node_scheduler -->|"schedules nudges"| node_session_pipeline
node_farmer_actor -->|"sends feedback"| node_whatsapp_router
node_agronomist -->|"reviews answers"| node_flagged_ui
node_whatsapp_ui -.->|"simulates interaction"| node_api_app
node_analytics_ui -.->|"loads metrics"| node_api_app
node_flagged_ui -.->|"submits revisions"| node_api_app
node_gdb_ui -.->|"loads catalog"| node_api_app
node_digest_ui -.->|"loads bulletin"| node_api_app
node_weather_ui -.->|"loads advisories"| node_api_app

click node_web_app "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/App.tsx"
click node_dashboard_state "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/store/slices/feedbackSlice.ts"
click node_api_client "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/services/api.ts"
click node_analytics_ui "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/components/AnalyticsView.tsx"
click node_flagged_ui "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/components/FlaggedQueueView.tsx"
click node_whatsapp_ui "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/components/TwilioWhatsAppView.tsx"
click node_gdb_ui "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/components/GdbCatalogView.tsx"
click node_digest_ui "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/components/WeeklyDigestView.tsx"
click node_weather_ui "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/components/WeatherAdvisoryView.tsx"
click node_api_app "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/main.py"
click node_config "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/config.py"
click node_database "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/database.py"
click node_whatsapp_router "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/routers/whatsapp.py"
click node_whatsapp_service "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/whatsapp_service.py"
click node_twilio "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/twilio_service.py"
click node_session_pipeline "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/session_pipeline.py"
click node_voice_nlp "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/voice_nlp_service.py"
click node_flagged_router "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/routers/flagged.py"
click node_flagging "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/flagging_pipeline.py"
click node_nvidia "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/nvidia_service.py"
click node_gdb_router "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/routers/gdb.py"
click node_analytics_router "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/routers/analytics.py"
click node_digest_router "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/routers/digest.py"
click node_digest_service "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/digest_service.py"
click node_weather_router "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/routers/weather.py"
click node_weather_service "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/weather_service.py"
click node_scheduler "https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/scheduler.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_app,node_dashboard_state,node_api_client,node_analytics_ui,node_flagged_ui,node_whatsapp_ui,node_gdb_ui,node_digest_ui,node_weather_ui toneBlue
class node_api_app,node_config,node_database,node_scheduler toneAmber
class node_flagged_router,node_flagging,node_nvidia,node_gdb_router toneMint
class node_whatsapp_router,node_whatsapp_service,node_twilio,node_session_pipeline,node_voice_nlp toneRose
class node_analytics_router,node_digest_router,node_digest_service,node_weather_router,node_weather_service,node_farmer_actor,node_agronomist toneIndigo
```

## Components

### Review dashboard

- [Dashboard routes](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Dashboard state](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/store/slices/feedbackSlice.ts): `frontend/src/store/slices/feedbackSlice.ts`
- [API client](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Analytics view](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/components/AnalyticsView.tsx): `frontend/src/components/AnalyticsView.tsx`
- [Flagged queue](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/components/FlaggedQueueView.tsx): `frontend/src/components/FlaggedQueueView.tsx`
- [WhatsApp simulator](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/components/TwilioWhatsAppView.tsx): `frontend/src/components/TwilioWhatsAppView.tsx`
- [GDB catalog](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/components/GdbCatalogView.tsx): `frontend/src/components/GdbCatalogView.tsx`
- [Weekly bulletin](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/components/WeeklyDigestView.tsx): `frontend/src/components/WeeklyDigestView.tsx`
- [Weather advisories](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/frontend/src/components/WeatherAdvisoryView.tsx): `frontend/src/components/WeatherAdvisoryView.tsx`

### Backend API

- [FastAPI application](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/main.py): `backend/app/main.py`
- [Runtime settings](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/config.py): `backend/app/config.py`
- [MongoDB collections](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/database.py): `backend/app/database.py`
- [Scheduled jobs](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/scheduler.py): `helpers/scheduler.py`

### Feedback quality

- [Flagged review endpoints](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/routers/flagged.py): `backend/app/routers/flagged.py`
- [Statistical flagging](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/flagging_pipeline.py): `helpers/flagging_pipeline.py`
- [Answer generation](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/nvidia_service.py): `helpers/nvidia_service.py`
- [Knowledge catalog endpoints](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/routers/gdb.py): `backend/app/routers/gdb.py`

### Farmer messaging

- [WhatsApp endpoints](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/routers/whatsapp.py): `backend/app/routers/whatsapp.py`
- [Interaction processing](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/whatsapp_service.py): `helpers/whatsapp_service.py`
- [Twilio messaging](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/twilio_service.py): `helpers/twilio_service.py`
- [Session and feedback](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/session_pipeline.py): `helpers/session_pipeline.py`
- [Voice feedback NLP](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/voice_nlp_service.py): `helpers/voice_nlp_service.py`

### Insights and advisories

- [Analytics endpoints](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/routers/analytics.py): `backend/app/routers/analytics.py`
- [Digest endpoints](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/routers/digest.py): `backend/app/routers/digest.py`
- [Digest generation](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/digest_service.py): `helpers/digest_service.py`
- [Weather endpoints](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/backend/app/routers/weather.py): `backend/app/routers/weather.py`
- [Weather risk service](https://github.com/iamgojoof6eyes/farmersfeedback/blob/main/helpers/weather_service.py): `helpers/weather_service.py`

### Other components

- **Farmer**
- **Agronomist**

## Connections

- Dashboard routes → Dashboard state: dispatches (evidence: `frontend/src/App.tsx`)
- Dashboard state → API client: requests data (evidence: `frontend/src/store/slices/feedbackSlice.ts`)
- Dashboard routes → Analytics view: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard routes → Flagged queue: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard routes → WhatsApp simulator: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard routes → GDB catalog: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard routes → Weekly bulletin: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard routes → Weather advisories: routes to (evidence: `frontend/src/App.tsx`)
- FastAPI application → WhatsApp endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI application → Knowledge catalog endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI application → Analytics endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI application → Flagged review endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI application → Digest endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI application → Weather endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI application → MongoDB collections: initializes (evidence: `backend/app/main.py`)
- FastAPI application → Scheduled jobs: starts (evidence: `backend/app/main.py`)
- WhatsApp endpoints → Interaction processing: processes interaction (evidence: `backend/app/routers/whatsapp.py`)
- WhatsApp endpoints → Session and feedback: creates sessions (evidence: `backend/app/routers/whatsapp.py`)
- WhatsApp endpoints → Twilio messaging: sends messages (evidence: `backend/app/routers/whatsapp.py`)
- Interaction processing → MongoDB collections: reads and writes (evidence: `helpers/whatsapp_service.py`)
- Interaction processing → Statistical flagging: evaluates answers (evidence: `helpers/whatsapp_service.py`)
- Interaction processing → Voice feedback NLP: analyzes voice (evidence: `helpers/whatsapp_service.py`)
- Session and feedback → MongoDB collections: updates records (evidence: `helpers/session_pipeline.py`)
- Session and feedback → Statistical flagging: evaluates answers (evidence: `helpers/session_pipeline.py`)
- Session and feedback → Twilio messaging: notifies farmer (evidence: `helpers/session_pipeline.py`)
- Flagged review endpoints → Statistical flagging: runs review pipeline (evidence: `backend/app/routers/flagged.py`)
- Flagged review endpoints → MongoDB collections: reads and writes (evidence: `backend/app/routers/flagged.py`)
- Statistical flagging → MongoDB collections: scores entries (evidence: `helpers/flagging_pipeline.py`)
- Statistical flagging → Answer generation: generates replacements (evidence: `helpers/flagging_pipeline.py`)
- Knowledge catalog endpoints → MongoDB collections: reads catalog (evidence: `backend/app/routers/gdb.py`)
- Analytics endpoints → MongoDB collections: serves metrics
- Digest endpoints → Digest generation: requests digest (evidence: `backend/app/routers/digest.py`)
- Weather endpoints → Weather risk service: requests advisories (evidence: `backend/app/routers/weather.py`)
- Scheduled jobs → Statistical flagging: schedules scans (evidence: `helpers/scheduler.py`)
- Scheduled jobs → Session and feedback: schedules nudges (evidence: `helpers/scheduler.py`)
- Farmer → WhatsApp endpoints: sends feedback (evidence: `README.md`)
- Agronomist → Flagged queue: reviews answers (evidence: `README.md`)
- WhatsApp simulator → FastAPI application: simulates interaction
- Analytics view → FastAPI application: loads metrics
- Flagged queue → FastAPI application: submits revisions
- GDB catalog → FastAPI application: loads catalog
- Weekly bulletin → FastAPI application: loads bulletin
- Weather advisories → FastAPI application: loads advisories