# shreevathsa05/statathon-narad architecture

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

- Interactive diagram: https://gitdiagram.com/shreevathsa05/statathon-narad
- Repository: https://github.com/shreevathsa05/statathon-narad

## Overview

NARAD is a multi-channel survey platform: administrators design and publish surveys, respondents complete them through web, messaging, telephone, or field channels, and the core API stores responses for operational use and analytics. The AI service supports context-grounded questionnaire generation and multilingual speech workflows; the IVR service transcribes recorded answers and submits them to the core API. WhatsApp session persistence and mobile offline synchronization are supported by sampled source. Some README-described services are represented by their enclosing directories because their implementation was not sampled.

Main entry points: [`backend/main2/src/app.js`](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/main2/src/app.js) (Core API), [`backend/ai/app.js`](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/ai/app.js) (AI Survey Engine), [`backend/exotel/src/controllers/callController.js`](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/exotel/src/controllers/callController.js) (IVR Service), [`backend/whatsapp_delivery_bot/controllers/whatsapp.controller.js`](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/whatsapp_delivery_bot/controllers/whatsapp.controller.js) (WhatsApp Survey Flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_design["Survey Design"]
  node_admin["Survey Admin<br/>[App.jsx]"]
  node_ai_builder["AI Builder"]
end

subgraph group_core["Core Data API"]
  node_core_api["Core API<br/>[app.js]"]
  node_survey_ctrl["Survey Management"]
  node_response_ctrl["Response Management"]
  node_auth["Authentication<br/>[authController.js]"]
  node_analytics["Analytics Dashboard"]
end

subgraph group_channels["Collection Channels"]
  node_citizen["Citizen Web App<br/>[SurveyPage.jsx]"]
  node_mobile["Mobile App<br/>[active.tsx]"]
  node_whatsapp["WhatsApp Bot<br/>[app.js]"]
  node_wa_controller["WhatsApp Survey Flow"]
  node_ivr["IVR Service<br/>[callController.js]"]
  node_telegram["Telegram Delivery"]
end

subgraph group_ai["AI Services"]
  node_ai_service["AI Survey Engine<br/>[app.js]"]
  node_generation["Question Generation"]
  node_agents["Agent Pipeline<br/>[agents.js]"]
  node_speech["Speech Processing"]
  node_minio[("Media Storage<br/>[client.js]")]
end

subgraph group_state["Survey State"]
  node_survey_store[("Survey Store<br/>[surveySchema.js]")]
  node_response_store[("Response Store<br/>[responsesSchema.js]")]
  node_offline[("Offline Survey State<br/>[filestorage.js]")]
  node_wa_session[("WhatsApp Sessions<br/>[session.service.js]")]
end

node_mcp["MoSPI MCP"]
node_telephony["Twilio / Exotel"]

node_admin -->|"configures"| node_ai_builder
node_ai_builder -->|"requests generation"| node_ai_service
node_ai_service -->|"routes requests"| node_generation
node_generation -->|"runs pipeline"| node_agents
node_agents -.->|"retrieves context"| node_mcp
node_generation -->|"saves generated survey"| node_survey_store
node_admin -->|"manages surveys"| node_core_api
node_core_api -->|"routes survey requests"| node_survey_ctrl
node_core_api -->|"routes response requests"| node_response_ctrl
node_core_api -->|"routes authentication"| node_auth
node_survey_ctrl -->|"reads and writes"| node_survey_store
node_response_ctrl -->|"reads and writes"| node_response_store
node_citizen -->|"fetches surveys and submits"| node_core_api
node_mobile -->|"fetches and syncs"| node_core_api
node_mobile -->|"stores offline surveys"| node_offline
node_offline -->|"syncs pending responses"| node_core_api
node_whatsapp -->|"dispatches webhooks"| node_wa_controller
node_wa_controller -->|"stores session and answers"| node_wa_session
node_wa_controller -->|"records responses"| node_response_store
node_ivr -->|"starts calls and handles webhooks"| node_telephony
node_ivr -->|"fetches survey and submits responses"| node_core_api
node_ivr -->|"requests transcription and audio"| node_ai_service
node_ai_service -->|"routes speech requests"| node_speech
node_speech -->|"accesses generated media"| node_minio
node_telegram -->|"delivers surveys"| node_survey_store
node_analytics -->|"retrieves survey data"| node_core_api

click node_admin "https://github.com/shreevathsa05/statathon-narad/blob/main/frontend/admin/src/App.jsx"
click node_ai_builder "https://github.com/shreevathsa05/statathon-narad/blob/main/frontend/admin/src/pages/sdrd/AIPromptBuilder.jsx"
click node_ai_service "https://github.com/shreevathsa05/statathon-narad/blob/main/backend/ai/app.js"
click node_generation "https://github.com/shreevathsa05/statathon-narad/blob/main/backend/ai/src/router/question_generation_route.js"
click node_agents "https://github.com/shreevathsa05/statathon-narad/blob/main/backend/ai/src/models/agents.js"
click node_speech "https://github.com/shreevathsa05/statathon-narad/blob/main/backend/ai/src/router/speech_conversion.js"
click node_minio "https://github.com/shreevathsa05/statathon-narad/blob/main/backend/ai/src/utils/minio/client.js"
click node_core_api "https://github.com/shreevathsa05/statathon-narad/blob/main/backend/main2/src/app.js"
click node_survey_ctrl "https://github.com/shreevathsa05/statathon-narad/blob/main/backend/main2/src/controllers/surveyController.js"
click node_response_ctrl "https://github.com/shreevathsa05/statathon-narad/blob/main/backend/main2/src/controllers/responseController.js"
click node_auth "https://github.com/shreevathsa05/statathon-narad/blob/main/backend/main2/src/controllers/authController.js"
click node_survey_store "https://github.com/shreevathsa05/statathon-narad/blob/main/backend/main2/src/models/surveySchema.js"
click node_response_store "https://github.com/shreevathsa05/statathon-narad/blob/main/backend/main2/src/models/responsesSchema.js"
click node_citizen "https://github.com/shreevathsa05/statathon-narad/blob/main/frontend/citizen/src/pages/SurveyPage.jsx"
click node_mobile "https://github.com/shreevathsa05/statathon-narad/blob/main/frontend/mobile-app/src/app/(tabs)/active.tsx"
click node_offline "https://github.com/shreevathsa05/statathon-narad/blob/main/frontend/mobile-app/src/utils/filestorage.js"
click node_whatsapp "https://github.com/shreevathsa05/statathon-narad/blob/main/backend/whatsapp_delivery_bot/app.js"
click node_wa_controller "https://github.com/shreevathsa05/statathon-narad/blob/main/backend/whatsapp_delivery_bot/controllers/whatsapp.controller.js"
click node_wa_session "https://github.com/shreevathsa05/statathon-narad/blob/main/backend/whatsapp_delivery_bot/services/session.service.js"
click node_ivr "https://github.com/shreevathsa05/statathon-narad/blob/main/backend/exotel/src/controllers/callController.js"
click node_telegram "https://github.com/shreevathsa05/statathon-narad/tree/main/backend/delivery_bot"
click node_analytics "https://github.com/shreevathsa05/statathon-narad/blob/main/frontend/admin/src/pages/AnalyticsDashboard.jsx"

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_admin,node_ai_builder toneBlue
class node_core_api,node_survey_ctrl,node_response_ctrl,node_auth,node_analytics toneAmber
class node_citizen,node_mobile,node_whatsapp,node_wa_controller,node_ivr,node_telegram toneMint
class node_ai_service,node_generation,node_agents,node_speech,node_minio toneRose
class node_survey_store,node_response_store,node_offline,node_wa_session,node_mcp,node_telephony toneIndigo
```

## Components

### Survey Design

- [Survey Admin](https://github.com/shreevathsa05/statathon-narad/blob/main/frontend/admin/src/App.jsx): `frontend/admin/src/App.jsx`
- [AI Builder](https://github.com/shreevathsa05/statathon-narad/blob/main/frontend/admin/src/pages/sdrd/AIPromptBuilder.jsx): `frontend/admin/src/pages/sdrd/AIPromptBuilder.jsx`

### Core Data API

- [Core API](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/main2/src/app.js): `backend/main2/src/app.js`
- [Survey Management](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/main2/src/controllers/surveyController.js): `backend/main2/src/controllers/surveyController.js`
- [Response Management](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/main2/src/controllers/responseController.js): `backend/main2/src/controllers/responseController.js`
- [Authentication](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/main2/src/controllers/authController.js): `backend/main2/src/controllers/authController.js`
- [Analytics Dashboard](https://github.com/shreevathsa05/statathon-narad/blob/main/frontend/admin/src/pages/AnalyticsDashboard.jsx): `frontend/admin/src/pages/AnalyticsDashboard.jsx`

### Collection Channels

- [Citizen Web App](https://github.com/shreevathsa05/statathon-narad/blob/main/frontend/citizen/src/pages/SurveyPage.jsx): `frontend/citizen/src/pages/SurveyPage.jsx`
- [Mobile App](https://github.com/shreevathsa05/statathon-narad/blob/main/frontend/mobile-app/src/app/(tabs)/active.tsx): `frontend/mobile-app/src/app/(tabs)/active.tsx`
- [WhatsApp Bot](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/whatsapp_delivery_bot/app.js): `backend/whatsapp_delivery_bot/app.js`
- [WhatsApp Survey Flow](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/whatsapp_delivery_bot/controllers/whatsapp.controller.js): `backend/whatsapp_delivery_bot/controllers/whatsapp.controller.js`
- [IVR Service](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/exotel/src/controllers/callController.js): `backend/exotel/src/controllers/callController.js`
- [Telegram Delivery](https://github.com/shreevathsa05/statathon-narad/tree/main/backend/delivery_bot): `backend/delivery_bot`

### AI Services

- [AI Survey Engine](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/ai/app.js): `backend/ai/app.js`
- [Question Generation](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/ai/src/router/question_generation_route.js): `backend/ai/src/router/question_generation_route.js`
- [Agent Pipeline](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/ai/src/models/agents.js): `backend/ai/src/models/agents.js`
- [Speech Processing](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/ai/src/router/speech_conversion.js): `backend/ai/src/router/speech_conversion.js`
- [Media Storage](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/ai/src/utils/minio/client.js): `backend/ai/src/utils/minio/client.js`

### Survey State

- [Survey Store](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/main2/src/models/surveySchema.js): `backend/main2/src/models/surveySchema.js`
- [Response Store](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/main2/src/models/responsesSchema.js): `backend/main2/src/models/responsesSchema.js`
- [Offline Survey State](https://github.com/shreevathsa05/statathon-narad/blob/main/frontend/mobile-app/src/utils/filestorage.js): `frontend/mobile-app/src/utils/filestorage.js`
- [WhatsApp Sessions](https://github.com/shreevathsa05/statathon-narad/blob/main/backend/whatsapp_delivery_bot/services/session.service.js): `backend/whatsapp_delivery_bot/services/session.service.js`

### Other components

- **MoSPI MCP**
- **Twilio / Exotel**

## Connections

- Survey Admin → AI Builder: configures
- AI Builder → AI Survey Engine: requests generation
- AI Survey Engine → Question Generation: routes requests
- Question Generation → Agent Pipeline: runs pipeline
- Agent Pipeline → MoSPI MCP: retrieves context
- Question Generation → Survey Store: saves generated survey
- Survey Admin → Core API: manages surveys
- Core API → Survey Management: routes survey requests
- Core API → Response Management: routes response requests
- Core API → Authentication: routes authentication
- Survey Management → Survey Store: reads and writes
- Response Management → Response Store: reads and writes
- Citizen Web App → Core API: fetches surveys and submits
- Mobile App → Core API: fetches and syncs
- Mobile App → Offline Survey State: stores offline surveys
- Offline Survey State → Core API: syncs pending responses
- WhatsApp Bot → WhatsApp Survey Flow: dispatches webhooks
- WhatsApp Survey Flow → WhatsApp Sessions: stores session and answers
- WhatsApp Survey Flow → Response Store: records responses
- IVR Service → Twilio / Exotel: starts calls and handles webhooks
- IVR Service → Core API: fetches survey and submits responses
- IVR Service → AI Survey Engine: requests transcription and audio
- AI Survey Engine → Speech Processing: routes speech requests
- Speech Processing → Media Storage: accesses generated media
- Telegram Delivery → Survey Store: delivers surveys
- Analytics Dashboard → Core API: retrieves survey data