# decillium/ermozhi architecture

> Architecture diagram of the GitHub repository decillium/ermozhi, 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/decillium/ermozhi
- Repository: https://github.com/decillium/ermozhi

## Overview

Ermozhi is a WhatsApp assistant that turns a farmer’s Tamil voice or text offer into a market-backed price recommendation, then returns localized text or audio. The documented workflow is webhook intake, durable queuing, worker processing, market lookup, decision, response rendering, and WhatsApp delivery. The source index supports the key worker dependencies and storage uses; sampled excerpts do not show every internal stage or all external API wiring, so uncertain connections are omitted.

Main entry points: [`src/data/storage/blob_repo.py`](https://github.com/decillium/ermozhi/blob/main/src/data/storage/blob_repo.py) (Blob repository), [`src/worker/pipeline.py`](https://github.com/decillium/ermozhi/blob/main/src/worker/pipeline.py) (Message pipeline), [`src/data/ingestion/runner.py`](https://github.com/decillium/ermozhi/blob/main/src/data/ingestion/runner.py) (Market ingestion), [`src/gateway/routes/meta.py`](https://github.com/decillium/ermozhi/blob/main/src/gateway/routes/meta.py) (Webhook intake)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["WhatsApp ingress"]
  node_webhook["Webhook intake<br/>[meta.py]"]
  node_security["Webhook security<br/>[signature.py]"]
  node_rate_limit["Sender rate limiting<br/>[rate_limit.py]"]
  node_event_store[("Inbound event store<br/>[event_store.py]")]
end

subgraph group_processing["Offer processing"]
  node_lease["Work leasing<br/>[lease_manager.py]"]
  node_pipeline["Message pipeline<br/>[pipeline.py]"]
  node_intelligence["Offer extraction<br/>[adapter.py]"]
  node_validator["Extraction validation<br/>[validator.py]"]
  node_decision["Price decision<br/>[engine.py]"]
  node_contracts["Typed contracts<br/>[decision.py]"]
end

subgraph group_market["Market data"]
  node_reader["Snapshot reader<br/>[reader.py]"]
  node_ingestion["Market ingestion<br/>[runner.py]"]
  node_adapters["Market source adapters<br/>[adapters.py]"]
  node_normalizer["Market normalization<br/>[normalizer.py]"]
  node_publisher["Snapshot publishing<br/>[publisher.py]"]
end

subgraph group_delivery["Response delivery"]
  node_language["Localized response<br/>[engine.py]"]
  node_templates["Tamil response templates<br/>[templates.py]"]
  node_tts["Voice synthesis<br/>[tts.py]"]
  node_meta_client["WhatsApp dispatch<br/>[client.py]"]
end

subgraph group_platform["Storage and operations"]
  node_blob[("Blob repository<br/>[blob_repo.py]")]
  node_telemetry["PII masking<br/>[masking.py]"]
  node_cleanup["Storage cleanup<br/>[cleanup.py]"]
  node_reconciliation["Job reconciliation<br/>[reconciliation.py]"]
end

node_farmer(("Farmer"))
node_whatsapp["WhatsApp Cloud"]
node_market_data["AGMARKNET / data.gov.in"]

node_farmer -->|"sends offer"| node_whatsapp
node_whatsapp -->|"posts webhook"| node_webhook
node_webhook -->|"verifies signature"| node_security
node_webhook -->|"checks sender"| node_rate_limit
node_webhook -->|"persists inbound"| node_event_store
node_event_store -->|"stores events"| node_blob
node_lease -->|"leases inbox"| node_blob
node_pipeline -->|"extracts offer"| node_intelligence
node_pipeline -->|"evaluates offer"| node_decision
node_pipeline -->|"loads snapshot"| node_reader
node_pipeline -->|"renders response"| node_language
node_pipeline -->|"dispatches response"| node_meta_client
node_pipeline -->|"uses repository"| node_blob
node_intelligence -->|"validates extraction"| node_validator
node_intelligence -->|"stores inbound media"| node_blob
node_validator -->|"normalizes variety"| node_normalizer
node_reader -->|"reads snapshot"| node_blob
node_ingestion -->|"fetches source data"| node_adapters
node_ingestion -->|"normalizes records"| node_normalizer
node_ingestion -->|"publishes snapshots"| node_publisher
node_ingestion -->|"stores market data"| node_blob
node_publisher -->|"writes snapshots"| node_blob
node_market_data -.->|"supplies prices"| node_adapters
node_language -->|"renders text"| node_templates
node_language -->|"synthesizes voice"| node_tts
node_tts -->|"stores audio"| node_blob
node_meta_client -->|"sends messages"| node_whatsapp
node_cleanup -->|"cleans storage"| node_blob
node_reconciliation -->|"checks storage"| node_blob
node_reconciliation -->|"reconciles leases"| node_lease

click node_webhook "https://github.com/decillium/ermozhi/blob/main/src/gateway/routes/meta.py"
click node_security "https://github.com/decillium/ermozhi/blob/main/src/gateway/security/signature.py"
click node_rate_limit "https://github.com/decillium/ermozhi/blob/main/src/gateway/middleware/rate_limit.py"
click node_event_store "https://github.com/decillium/ermozhi/blob/main/src/platform/storage/event_store.py"
click node_lease "https://github.com/decillium/ermozhi/blob/main/src/worker/lease_manager.py"
click node_pipeline "https://github.com/decillium/ermozhi/blob/main/src/worker/pipeline.py"
click node_intelligence "https://github.com/decillium/ermozhi/blob/main/src/intelligence/adapter.py"
click node_validator "https://github.com/decillium/ermozhi/blob/main/src/intelligence/validator.py"
click node_decision "https://github.com/decillium/ermozhi/blob/main/src/decision_engine/engine.py"
click node_contracts "https://github.com/decillium/ermozhi/blob/main/src/contracts/v1/decision.py"
click node_reader "https://github.com/decillium/ermozhi/blob/main/src/data/reader.py"
click node_ingestion "https://github.com/decillium/ermozhi/blob/main/src/data/ingestion/runner.py"
click node_adapters "https://github.com/decillium/ermozhi/blob/main/src/data/ingestion/adapters.py"
click node_normalizer "https://github.com/decillium/ermozhi/blob/main/src/data/ingestion/normalizer.py"
click node_publisher "https://github.com/decillium/ermozhi/blob/main/src/data/snapshots/publisher.py"
click node_language "https://github.com/decillium/ermozhi/blob/main/src/language/engine.py"
click node_templates "https://github.com/decillium/ermozhi/blob/main/src/language/templates.py"
click node_tts "https://github.com/decillium/ermozhi/blob/main/src/language/tts.py"
click node_meta_client "https://github.com/decillium/ermozhi/blob/main/src/channels/meta/client.py"
click node_blob "https://github.com/decillium/ermozhi/blob/main/src/data/storage/blob_repo.py"
click node_telemetry "https://github.com/decillium/ermozhi/blob/main/src/platform/telemetry/masking.py"
click node_cleanup "https://github.com/decillium/ermozhi/blob/main/src/worker/jobs/cleanup.py"
click node_reconciliation "https://github.com/decillium/ermozhi/blob/main/src/worker/jobs/reconciliation.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_webhook,node_security,node_rate_limit,node_event_store toneBlue
class node_lease,node_pipeline,node_intelligence,node_validator,node_decision,node_contracts toneAmber
class node_reader,node_ingestion,node_adapters,node_normalizer,node_publisher toneMint
class node_language,node_templates,node_tts,node_meta_client toneRose
class node_blob,node_telemetry,node_cleanup,node_reconciliation,node_farmer,node_whatsapp,node_market_data toneIndigo
```

## Components

### WhatsApp ingress

- [Webhook intake](https://github.com/decillium/ermozhi/blob/main/src/gateway/routes/meta.py): `src/gateway/routes/meta.py`
- [Webhook security](https://github.com/decillium/ermozhi/blob/main/src/gateway/security/signature.py): `src/gateway/security/signature.py`
- [Sender rate limiting](https://github.com/decillium/ermozhi/blob/main/src/gateway/middleware/rate_limit.py): `src/gateway/middleware/rate_limit.py`
- [Inbound event store](https://github.com/decillium/ermozhi/blob/main/src/platform/storage/event_store.py): `src/platform/storage/event_store.py`

### Offer processing

- [Work leasing](https://github.com/decillium/ermozhi/blob/main/src/worker/lease_manager.py): `src/worker/lease_manager.py`
- [Message pipeline](https://github.com/decillium/ermozhi/blob/main/src/worker/pipeline.py): `src/worker/pipeline.py`
- [Offer extraction](https://github.com/decillium/ermozhi/blob/main/src/intelligence/adapter.py): `src/intelligence/adapter.py`
- [Extraction validation](https://github.com/decillium/ermozhi/blob/main/src/intelligence/validator.py): `src/intelligence/validator.py`
- [Price decision](https://github.com/decillium/ermozhi/blob/main/src/decision_engine/engine.py): `src/decision_engine/engine.py`
- [Typed contracts](https://github.com/decillium/ermozhi/blob/main/src/contracts/v1/decision.py): `src/contracts/v1/decision.py`

### Market data

- [Snapshot reader](https://github.com/decillium/ermozhi/blob/main/src/data/reader.py): `src/data/reader.py`
- [Market ingestion](https://github.com/decillium/ermozhi/blob/main/src/data/ingestion/runner.py): `src/data/ingestion/runner.py`
- [Market source adapters](https://github.com/decillium/ermozhi/blob/main/src/data/ingestion/adapters.py): `src/data/ingestion/adapters.py`
- [Market normalization](https://github.com/decillium/ermozhi/blob/main/src/data/ingestion/normalizer.py): `src/data/ingestion/normalizer.py`
- [Snapshot publishing](https://github.com/decillium/ermozhi/blob/main/src/data/snapshots/publisher.py): `src/data/snapshots/publisher.py`

### Response delivery

- [Localized response](https://github.com/decillium/ermozhi/blob/main/src/language/engine.py): `src/language/engine.py`
- [Tamil response templates](https://github.com/decillium/ermozhi/blob/main/src/language/templates.py): `src/language/templates.py`
- [Voice synthesis](https://github.com/decillium/ermozhi/blob/main/src/language/tts.py): `src/language/tts.py`
- [WhatsApp dispatch](https://github.com/decillium/ermozhi/blob/main/src/channels/meta/client.py): `src/channels/meta/client.py`

### Storage and operations

- [Blob repository](https://github.com/decillium/ermozhi/blob/main/src/data/storage/blob_repo.py): `src/data/storage/blob_repo.py`
- [PII masking](https://github.com/decillium/ermozhi/blob/main/src/platform/telemetry/masking.py): `src/platform/telemetry/masking.py`
- [Storage cleanup](https://github.com/decillium/ermozhi/blob/main/src/worker/jobs/cleanup.py): `src/worker/jobs/cleanup.py`
- [Job reconciliation](https://github.com/decillium/ermozhi/blob/main/src/worker/jobs/reconciliation.py): `src/worker/jobs/reconciliation.py`

### Other components

- **Farmer**
- **WhatsApp Cloud**
- **AGMARKNET / data.gov.in**

## Connections

- Farmer → WhatsApp Cloud: sends offer (evidence: `README.md`)
- WhatsApp Cloud → Webhook intake: posts webhook (evidence: `src/gateway/routes/meta.py`)
- Webhook intake → Webhook security: verifies signature (evidence: `src/gateway/routes/meta.py`)
- Webhook intake → Sender rate limiting: checks sender (evidence: `src/gateway/routes/meta.py`)
- Webhook intake → Inbound event store: persists inbound (evidence: `src/gateway/routes/meta.py`)
- Inbound event store → Blob repository: stores events (evidence: `src/platform/storage/event_store.py`)
- Work leasing → Blob repository: leases inbox (evidence: `src/worker/lease_manager.py`)
- Message pipeline → Offer extraction: extracts offer (evidence: `src/worker/pipeline.py`)
- Message pipeline → Price decision: evaluates offer (evidence: `src/worker/pipeline.py`)
- Message pipeline → Snapshot reader: loads snapshot (evidence: `src/worker/pipeline.py`)
- Message pipeline → Localized response: renders response (evidence: `src/worker/pipeline.py`)
- Message pipeline → WhatsApp dispatch: dispatches response (evidence: `src/worker/pipeline.py`)
- Message pipeline → Blob repository: uses repository (evidence: `src/worker/pipeline.py`)
- Offer extraction → Extraction validation: validates extraction (evidence: `src/intelligence/adapter.py`)
- Offer extraction → Blob repository: stores inbound media (evidence: `src/intelligence/adapter.py`)
- Extraction validation → Market normalization: normalizes variety (evidence: `src/intelligence/validator.py`)
- Snapshot reader → Blob repository: reads snapshot (evidence: `src/data/reader.py`)
- Market ingestion → Market source adapters: fetches source data (evidence: `src/data/ingestion/runner.py`)
- Market ingestion → Market normalization: normalizes records (evidence: `src/data/ingestion/runner.py`)
- Market ingestion → Snapshot publishing: publishes snapshots (evidence: `src/data/ingestion/runner.py`)
- Market ingestion → Blob repository: stores market data (evidence: `src/data/ingestion/runner.py`)
- Snapshot publishing → Blob repository: writes snapshots (evidence: `src/data/snapshots/publisher.py`)
- AGMARKNET / data.gov.in → Market source adapters: supplies prices
- Localized response → Tamil response templates: renders text (evidence: `src/language/engine.py`)
- Localized response → Voice synthesis: synthesizes voice (evidence: `src/language/engine.py`)
- Voice synthesis → Blob repository: stores audio (evidence: `src/language/tts.py`)
- WhatsApp dispatch → WhatsApp Cloud: sends messages (evidence: `src/channels/meta/client.py`)
- Storage cleanup → Blob repository: cleans storage (evidence: `src/worker/jobs/cleanup.py`)
- Job reconciliation → Blob repository: checks storage (evidence: `src/worker/jobs/reconciliation.py`)
- Job reconciliation → Work leasing: reconciles leases (evidence: `src/worker/jobs/reconciliation.py`)
