# dawit-getachew/umurima architecture

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

- Interactive diagram: https://gitdiagram.com/dawit-getachew/umurima
- Repository: https://github.com/dawit-getachew/umurima

## Overview

Umurima AI delivers farming advice by SMS: a farmer messages an Android relay, which calls the backend and sends the returned reply. The backend applies triage, verified answers, cache, retrieval/model, and offline fallback stages, then adds a human referral. The README documents this routing and the gateway’s store-and-forward role, but the Flutter application source is absent from the supplied tree, so its internal queue and dashboard are represented only at the gateway level. Native telephony plugin relationships are shown only where the sampled plugin source supports them.

Main entry points: [`backend/app/advisor.py`](https://github.com/dawit-getachew/umurima/blob/main/backend/app/advisor.py) (Answer orchestrator), [`sms-gateway`](https://github.com/dawit-getachew/umurima/tree/main/sms-gateway) (SMS relay), [`backend/app/main.py`](https://github.com/dawit-getachew/umurima/blob/main/backend/app/main.py) (FastAPI service), [`sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/sms/SmsMethodCallHandler.kt`](https://github.com/dawit-getachew/umurima/blob/main/sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/sms/SmsMethodCallHandler.kt) (Method call handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["SMS gateway"]
  node_gateway_app["SMS relay"]
end

subgraph group_backend["Advice backend"]
  node_backend_api["FastAPI service<br/>[main.py]"]
  node_advisor["Answer orchestrator<br/>[advisor.py]"]
  node_triage["Urgency triage<br/>[triage.py]"]
  node_faq["Verified answers<br/>[faq.py]"]
  node_cache["Answer cache<br/>[cache.py]"]
  node_llm["Model client<br/>[llm.py]"]
  node_offline["Offline fallback<br/>[rag.py]"]
  node_nlp["Language and matching<br/>[nlp.py]"]
  node_reply_rules["Reply formatting<br/>[replies.py]"]
  node_memory[("History storage<br/>[memory.py]")]
end

subgraph group_knowledge["Advice knowledge"]
  node_rag["Note retrieval<br/>[rag.py]"]
  node_knowledge_notes["Agronomy notes"]
end

subgraph group_telephony["Android telephony"]
  node_android_plugin["Telephony plugin<br/>[TelephonyPlugin.kt]"]
  node_method_handler["Method call handler"]
  node_sms_controller["SMS controller<br/>[SmsController.kt]"]
  node_incoming_handler["Incoming SMS handler"]
  node_permissions["Permission controller"]
end

node_farmer(("Farmer"))
node_model_service["OpenRouter"]

node_farmer -->|"texts SMS"| node_gateway_app
node_gateway_app -->|"sends HTTPS"| node_backend_api
node_backend_api -->|"returns reply"| node_gateway_app
node_gateway_app -->|"sends SMS"| node_farmer
node_backend_api -->|"calls"| node_advisor
node_backend_api -->|"initializes"| node_memory
node_advisor -->|"checks urgency"| node_triage
node_advisor -->|"checks answers"| node_faq
node_advisor -->|"checks cache"| node_cache
node_advisor -->|"retrieves notes"| node_rag
node_advisor -->|"requests answer"| node_llm
node_advisor -->|"falls back"| node_offline
node_advisor -->|"formats reply"| node_reply_rules
node_advisor -->|"uses history"| node_memory
node_advisor -->|"normalizes text"| node_nlp
node_rag -->|"loads and ranks"| node_knowledge_notes
node_rag -->|"tokenizes queries"| node_nlp
node_llm -->|"calls API"| node_model_service
node_cache -.->|"persists answers"| node_memory
node_android_plugin -->|"registers handler"| node_method_handler
node_method_handler -->|"dispatches SMS"| node_sms_controller
node_method_handler -->|"configures callbacks"| node_incoming_handler
node_method_handler -->|"checks permissions"| node_permissions
node_gateway_app -.->|"uses native SMS"| node_android_plugin

click node_gateway_app "https://github.com/dawit-getachew/umurima/tree/main/sms-gateway"
click node_backend_api "https://github.com/dawit-getachew/umurima/blob/main/backend/app/main.py"
click node_advisor "https://github.com/dawit-getachew/umurima/blob/main/backend/app/advisor.py"
click node_triage "https://github.com/dawit-getachew/umurima/blob/main/backend/app/triage.py"
click node_faq "https://github.com/dawit-getachew/umurima/blob/main/backend/app/faq.py"
click node_cache "https://github.com/dawit-getachew/umurima/blob/main/backend/app/cache.py"
click node_rag "https://github.com/dawit-getachew/umurima/blob/main/backend/app/rag.py"
click node_knowledge_notes "https://github.com/dawit-getachew/umurima/tree/main/backend/knowledge"
click node_llm "https://github.com/dawit-getachew/umurima/blob/main/backend/app/llm.py"
click node_offline "https://github.com/dawit-getachew/umurima/blob/main/backend/app/rag.py"
click node_nlp "https://github.com/dawit-getachew/umurima/blob/main/backend/app/nlp.py"
click node_reply_rules "https://github.com/dawit-getachew/umurima/blob/main/backend/app/replies.py"
click node_memory "https://github.com/dawit-getachew/umurima/blob/main/backend/app/memory.py"
click node_android_plugin "https://github.com/dawit-getachew/umurima/blob/main/sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/TelephonyPlugin.kt"
click node_method_handler "https://github.com/dawit-getachew/umurima/blob/main/sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/sms/SmsMethodCallHandler.kt"
click node_sms_controller "https://github.com/dawit-getachew/umurima/blob/main/sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/sms/SmsController.kt"
click node_incoming_handler "https://github.com/dawit-getachew/umurima/blob/main/sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/sms/IncomingSmsHandler.kt"
click node_permissions "https://github.com/dawit-getachew/umurima/blob/main/sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/PermissionsController.kt"

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_gateway_app toneBlue
class node_backend_api,node_advisor,node_triage,node_faq,node_cache,node_llm,node_offline,node_nlp,node_reply_rules,node_memory toneAmber
class node_rag,node_knowledge_notes,node_model_service toneMint
class node_android_plugin,node_method_handler,node_sms_controller,node_incoming_handler,node_permissions toneRose
class node_farmer toneIndigo
```

## Components

### SMS gateway

- [SMS relay](https://github.com/dawit-getachew/umurima/tree/main/sms-gateway): `sms-gateway`

### Advice backend

- [FastAPI service](https://github.com/dawit-getachew/umurima/blob/main/backend/app/main.py): `backend/app/main.py`
- [Answer orchestrator](https://github.com/dawit-getachew/umurima/blob/main/backend/app/advisor.py): `backend/app/advisor.py`
- [Urgency triage](https://github.com/dawit-getachew/umurima/blob/main/backend/app/triage.py): `backend/app/triage.py`
- [Verified answers](https://github.com/dawit-getachew/umurima/blob/main/backend/app/faq.py): `backend/app/faq.py`
- [Answer cache](https://github.com/dawit-getachew/umurima/blob/main/backend/app/cache.py): `backend/app/cache.py`
- [Model client](https://github.com/dawit-getachew/umurima/blob/main/backend/app/llm.py): `backend/app/llm.py`
- [Offline fallback](https://github.com/dawit-getachew/umurima/blob/main/backend/app/rag.py): `backend/app/rag.py`
- [Language and matching](https://github.com/dawit-getachew/umurima/blob/main/backend/app/nlp.py): `backend/app/nlp.py`
- [Reply formatting](https://github.com/dawit-getachew/umurima/blob/main/backend/app/replies.py): `backend/app/replies.py`
- [History storage](https://github.com/dawit-getachew/umurima/blob/main/backend/app/memory.py): `backend/app/memory.py`

### Advice knowledge

- [Note retrieval](https://github.com/dawit-getachew/umurima/blob/main/backend/app/rag.py): `backend/app/rag.py`
- [Agronomy notes](https://github.com/dawit-getachew/umurima/tree/main/backend/knowledge): `backend/knowledge`

### Android telephony

- [Telephony plugin](https://github.com/dawit-getachew/umurima/blob/main/sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/TelephonyPlugin.kt): `sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/TelephonyPlugin.kt`
- [Method call handler](https://github.com/dawit-getachew/umurima/blob/main/sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/sms/SmsMethodCallHandler.kt): `sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/sms/SmsMethodCallHandler.kt`
- [SMS controller](https://github.com/dawit-getachew/umurima/blob/main/sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/sms/SmsController.kt): `sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/sms/SmsController.kt`
- [Incoming SMS handler](https://github.com/dawit-getachew/umurima/blob/main/sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/sms/IncomingSmsHandler.kt): `sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/sms/IncomingSmsHandler.kt`
- [Permission controller](https://github.com/dawit-getachew/umurima/blob/main/sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/PermissionsController.kt): `sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/PermissionsController.kt`

### Other components

- **Farmer**
- **OpenRouter**

## Connections

- Farmer → SMS relay: texts SMS
- SMS relay → FastAPI service: sends HTTPS
- FastAPI service → SMS relay: returns reply
- SMS relay → Farmer: sends SMS
- FastAPI service → Answer orchestrator: calls (evidence: `backend/app/main.py`)
- FastAPI service → History storage: initializes (evidence: `backend/app/main.py`)
- Answer orchestrator → Urgency triage: checks urgency (evidence: `backend/app/advisor.py`)
- Answer orchestrator → Verified answers: checks answers (evidence: `backend/app/advisor.py`)
- Answer orchestrator → Answer cache: checks cache (evidence: `backend/app/advisor.py`)
- Answer orchestrator → Note retrieval: retrieves notes (evidence: `backend/app/advisor.py`)
- Answer orchestrator → Model client: requests answer (evidence: `backend/app/advisor.py`)
- Answer orchestrator → Offline fallback: falls back (evidence: `backend/app/advisor.py`)
- Answer orchestrator → Reply formatting: formats reply (evidence: `backend/app/advisor.py`)
- Answer orchestrator → History storage: uses history (evidence: `backend/app/advisor.py`)
- Answer orchestrator → Language and matching: normalizes text (evidence: `backend/app/advisor.py`)
- Note retrieval → Agronomy notes: loads and ranks (evidence: `backend/app/rag.py`)
- Note retrieval → Language and matching: tokenizes queries (evidence: `backend/app/rag.py`)
- Model client → OpenRouter: calls API (evidence: `backend/app/llm.py`)
- Answer cache → History storage: persists answers (evidence: `backend/app/cache.py`)
- Telephony plugin → Method call handler: registers handler (evidence: `sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/TelephonyPlugin.kt`)
- Method call handler → SMS controller: dispatches SMS (evidence: `sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/sms/SmsMethodCallHandler.kt`)
- Method call handler → Incoming SMS handler: configures callbacks (evidence: `sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/sms/SmsMethodCallHandler.kt`)
- Method call handler → Permission controller: checks permissions (evidence: `sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/sms/SmsMethodCallHandler.kt`)
- SMS relay → Telephony plugin: uses native SMS (evidence: `sms-gateway/packages/telephony/android/src/main/kotlin/com/shounakmulay/telephony/TelephonyPlugin.kt`)
