# shalcoder/jansathi architecture

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

- Interactive diagram: https://gitdiagram.com/shalcoder/jansathi
- Repository: https://github.com/shalcoder/jansathi

## Overview

JanSathi is a voice-first civic-readiness service: citizens ask about benefits by phone or web, then receive eligibility guidance, document preparation, and follow-up artifacts. The documented workflow proceeds through intent, scheme retrieval, slot gathering, deterministic eligibility rules, verification/escalation, and notification or receipt delivery; the admin dashboard provides review and operational visibility. The README describes these capabilities and the high-level flow. Source excerpts confirm selected routing, rules, session, and retrieval behavior; unsampled feature implementations and some runtime wiring are represented only where documented.

Main entry points: [`backend/agents/supervisor.py`](https://github.com/shalcoder/jansathi/blob/main/backend/agents/supervisor.py) (Agent supervisor), [`backend/agentic_engine/workflow_engine.py`](https://github.com/shalcoder/jansathi/blob/main/backend/agentic_engine/workflow_engine.py) (Workflow engine), [`backend/app/api/v1_routes.py`](https://github.com/shalcoder/jansathi/blob/main/backend/app/api/v1_routes.py) (V1 API), [`backend/app/services/rag_service.py`](https://github.com/shalcoder/jansathi/blob/main/backend/app/services/rag_service.py) (Scheme retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Citizen entry"]
  node_phone["Phone IVR<br/>[ivr_service.py]"]
  node_web["Web phone"]
  node_api["V1 API<br/>[v1_routes.py]"]
end

subgraph group_intelligence["Civic intelligence"]
  node_intent["Intent classification<br/>[intent_service.py]"]
  node_rag["Scheme retrieval<br/>[rag_service.py]"]
  node_smart_rag["Adaptive RAG"]
  node_slots["Slot collection"]
  node_rules["Eligibility rules<br/>[rules_engine.py]"]
  node_supervisor["Agent supervisor<br/>[supervisor.py]"]
  node_workflow["Workflow engine<br/>[workflow_engine.py]"]
end

subgraph group_delivery["Decision and delivery"]
  node_verifier["Decision verification"]
  node_hitl["Human review<br/>[hitl_service.py]"]
  node_grievance["Grievance drafting"]
  node_receipt["Benefit receipt<br/>[receipt_service.py]"]
  node_sms["SMS notification<br/>[notify_service.py]"]
end

subgraph group_state["Session and data"]
  node_session["Session manager<br/>[session_manager.py]"]
  node_storage[("Session storage<br/>[storage.py]")]
  node_schemes[("Scheme catalog")]
end

subgraph group_operations["Admin and oversight"]
  node_admin["Admin dashboard<br/>[page.tsx]"]
  node_audit[("Audit trail<br/>[audit_service.py]")]
end

node_citizen(("Citizen"))
node_kendra[("Amazon Kendra")]
node_bedrock["Amazon Bedrock"]
node_dynamodb[("DynamoDB")]
node_human(("Reviewer"))

node_citizen -->|"calls"| node_phone
node_citizen -->|"uses"| node_web
node_phone -->|"submits query"| node_api
node_web -->|"submits query"| node_api
node_api -.->|"routes request"| node_supervisor
node_api -->|"starts workflow"| node_workflow
node_supervisor -->|"classifies"| node_intent
node_supervisor -->|"retrieves schemes"| node_rag
node_supervisor -->|"collects slots"| node_slots
node_supervisor -->|"evaluates eligibility"| node_rules
node_supervisor -->|"verifies result"| node_verifier
node_rag -->|"searches"| node_kendra
node_smart_rag -->|"searches"| node_kendra
node_smart_rag -->|"generates fallback"| node_bedrock
node_workflow -->|"manages session"| node_session
node_session -->|"reads and writes"| node_storage
node_storage -.->|"persists sessions"| node_dynamodb
node_verifier -->|"escalates cases"| node_hitl
node_human -->|"reviews cases"| node_hitl
node_workflow -->|"drafts grievance"| node_grievance
node_workflow -->|"generates receipt"| node_receipt
node_workflow -->|"dispatches summary"| node_sms
node_rag -->|"uses scheme data"| node_schemes
node_admin -->|"shows review queue"| node_hitl
node_admin -->|"shows audit trail"| node_audit

click node_phone "https://github.com/shalcoder/jansathi/blob/main/backend/app/services/ivr_service.py"
click node_web "https://github.com/shalcoder/jansathi/blob/main/frontend/src/components/features/dashboard/PhoneEmulatorPage.tsx"
click node_api "https://github.com/shalcoder/jansathi/blob/main/backend/app/api/v1_routes.py"
click node_intent "https://github.com/shalcoder/jansathi/blob/main/backend/app/services/intent_service.py"
click node_rag "https://github.com/shalcoder/jansathi/blob/main/backend/app/services/rag_service.py"
click node_smart_rag "https://github.com/shalcoder/jansathi/blob/main/backend/app/services/smart_rag_service.py"
click node_slots "https://github.com/shalcoder/jansathi/blob/main/backend/agents/slot_collection_agent.py"
click node_rules "https://github.com/shalcoder/jansathi/blob/main/backend/app/services/rules_engine.py"
click node_supervisor "https://github.com/shalcoder/jansathi/blob/main/backend/agents/supervisor.py"
click node_workflow "https://github.com/shalcoder/jansathi/blob/main/backend/agentic_engine/workflow_engine.py"
click node_verifier "https://github.com/shalcoder/jansathi/blob/main/backend/app/services/verifier_service.py"
click node_hitl "https://github.com/shalcoder/jansathi/blob/main/backend/app/services/hitl_service.py"
click node_grievance "https://github.com/shalcoder/jansathi/blob/main/backend/agents/life_event_agent.py"
click node_receipt "https://github.com/shalcoder/jansathi/blob/main/backend/app/services/receipt_service.py"
click node_sms "https://github.com/shalcoder/jansathi/blob/main/backend/app/services/notify_service.py"
click node_session "https://github.com/shalcoder/jansathi/blob/main/backend/agentic_engine/session_manager.py"
click node_storage "https://github.com/shalcoder/jansathi/blob/main/backend/agentic_engine/storage.py"
click node_schemes "https://github.com/shalcoder/jansathi/blob/main/backend/app/services/scheme_feed_service.py"
click node_admin "https://github.com/shalcoder/jansathi/blob/main/frontend/src/app/admin/dashboard/page.tsx"
click node_audit "https://github.com/shalcoder/jansathi/blob/main/backend/app/services/audit_service.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_phone,node_web,node_api,node_human toneBlue
class node_intent,node_rag,node_smart_rag,node_slots,node_rules,node_supervisor,node_workflow,node_kendra,node_dynamodb toneAmber
class node_verifier,node_hitl,node_grievance,node_receipt,node_sms toneMint
class node_session,node_storage,node_schemes toneRose
class node_admin,node_audit,node_citizen,node_bedrock toneIndigo
```

## Components

### Citizen entry

- [Phone IVR](https://github.com/shalcoder/jansathi/blob/main/backend/app/services/ivr_service.py): `backend/app/services/ivr_service.py`
- [Web phone](https://github.com/shalcoder/jansathi/blob/main/frontend/src/components/features/dashboard/PhoneEmulatorPage.tsx): `frontend/src/components/features/dashboard/PhoneEmulatorPage.tsx`
- [V1 API](https://github.com/shalcoder/jansathi/blob/main/backend/app/api/v1_routes.py): `backend/app/api/v1_routes.py`

### Civic intelligence

- [Intent classification](https://github.com/shalcoder/jansathi/blob/main/backend/app/services/intent_service.py): `backend/app/services/intent_service.py`
- [Scheme retrieval](https://github.com/shalcoder/jansathi/blob/main/backend/app/services/rag_service.py): `backend/app/services/rag_service.py`
- [Adaptive RAG](https://github.com/shalcoder/jansathi/blob/main/backend/app/services/smart_rag_service.py): `backend/app/services/smart_rag_service.py`
- [Slot collection](https://github.com/shalcoder/jansathi/blob/main/backend/agents/slot_collection_agent.py): `backend/agents/slot_collection_agent.py`
- [Eligibility rules](https://github.com/shalcoder/jansathi/blob/main/backend/app/services/rules_engine.py): `backend/app/services/rules_engine.py`
- [Agent supervisor](https://github.com/shalcoder/jansathi/blob/main/backend/agents/supervisor.py): `backend/agents/supervisor.py`
- [Workflow engine](https://github.com/shalcoder/jansathi/blob/main/backend/agentic_engine/workflow_engine.py): `backend/agentic_engine/workflow_engine.py`

### Decision and delivery

- [Decision verification](https://github.com/shalcoder/jansathi/blob/main/backend/app/services/verifier_service.py): `backend/app/services/verifier_service.py`
- [Human review](https://github.com/shalcoder/jansathi/blob/main/backend/app/services/hitl_service.py): `backend/app/services/hitl_service.py`
- [Grievance drafting](https://github.com/shalcoder/jansathi/blob/main/backend/agents/life_event_agent.py): `backend/agents/life_event_agent.py`
- [Benefit receipt](https://github.com/shalcoder/jansathi/blob/main/backend/app/services/receipt_service.py): `backend/app/services/receipt_service.py`
- [SMS notification](https://github.com/shalcoder/jansathi/blob/main/backend/app/services/notify_service.py): `backend/app/services/notify_service.py`

### Session and data

- [Session manager](https://github.com/shalcoder/jansathi/blob/main/backend/agentic_engine/session_manager.py): `backend/agentic_engine/session_manager.py`
- [Session storage](https://github.com/shalcoder/jansathi/blob/main/backend/agentic_engine/storage.py): `backend/agentic_engine/storage.py`
- [Scheme catalog](https://github.com/shalcoder/jansathi/blob/main/backend/app/services/scheme_feed_service.py): `backend/app/services/scheme_feed_service.py`

### Admin and oversight

- [Admin dashboard](https://github.com/shalcoder/jansathi/blob/main/frontend/src/app/admin/dashboard/page.tsx): `frontend/src/app/admin/dashboard/page.tsx`
- [Audit trail](https://github.com/shalcoder/jansathi/blob/main/backend/app/services/audit_service.py): `backend/app/services/audit_service.py`

### Other components

- **Citizen**
- **Amazon Kendra**
- **Amazon Bedrock**
- **DynamoDB**
- **Reviewer**

## Connections

- Citizen → Phone IVR: calls (evidence: `README.md`)
- Citizen → Web phone: uses (evidence: `README.md`)
- Phone IVR → V1 API: submits query (evidence: `README.md`)
- Web phone → V1 API: submits query (evidence: `README.md`)
- V1 API → Agent supervisor: routes request (evidence: `backend/app/api/v1_routes.py`)
- V1 API → Workflow engine: starts workflow (evidence: `README.md`)
- Agent supervisor → Intent classification: classifies (evidence: `backend/agents/supervisor.py`)
- Agent supervisor → Scheme retrieval: retrieves schemes (evidence: `backend/agents/supervisor.py`)
- Agent supervisor → Slot collection: collects slots (evidence: `backend/agents/supervisor.py`)
- Agent supervisor → Eligibility rules: evaluates eligibility (evidence: `backend/agents/supervisor.py`)
- Agent supervisor → Decision verification: verifies result (evidence: `backend/agents/supervisor.py`)
- Scheme retrieval → Amazon Kendra: searches (evidence: `README.md`)
- Adaptive RAG → Amazon Kendra: searches (evidence: `backend/app/services/smart_rag_service.py`)
- Adaptive RAG → Amazon Bedrock: generates fallback (evidence: `backend/app/services/smart_rag_service.py`)
- Workflow engine → Session manager: manages session (evidence: `backend/agentic_engine/workflow_engine.py`)
- Session manager → Session storage: reads and writes (evidence: `backend/agentic_engine/session_manager.py`)
- Session storage → DynamoDB: persists sessions
- Decision verification → Human review: escalates cases (evidence: `README.md`)
- Reviewer → Human review: reviews cases (evidence: `README.md`)
- Workflow engine → Grievance drafting: drafts grievance (evidence: `backend/agentic_engine/workflow_engine.py`)
- Workflow engine → Benefit receipt: generates receipt (evidence: `README.md`)
- Workflow engine → SMS notification: dispatches summary (evidence: `README.md`)
- Scheme retrieval → Scheme catalog: uses scheme data (evidence: `backend/app/services/rag_service.py`)
- Admin dashboard → Human review: shows review queue (evidence: `README.md`)
- Admin dashboard → Audit trail: shows audit trail (evidence: `README.md`)
