# hemanth354/language-agnostic-chatbot architecture

> Architecture diagram of the GitHub repository hemanth354/language-agnostic-chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hemanth354/language-agnostic-chatbot
- Repository: https://github.com/hemanth354/language-agnostic-chatbot

## Overview

This is a multilingual campus-support chatbot: a student query is translated to English, matched against indexed college circulars, answered with grounded generation or fallback extraction, then translated back; low-confidence questions become faculty tickets. Volunteers can upload circulars, and faculty can resolve tickets. Web, WhatsApp, and Telegram are documented entry points, with voice interaction in the web UI. The graph follows relationships visible in excerpts or the README; unsampled routes and frontend wiring are not inferred.

Main entry points: [`app/main.py`](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/main.py) (FastAPI Routes), [`app/database.py`](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/database.py) (SQLite Records), [`app/rag_service.py`](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/rag_service.py) (Circular Retrieval), [`app/circular_parser.py`](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/circular_parser.py) (Circular Ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User Interfaces"]
  node_web["Web UI<br/>[index.html]"]
  node_voice["Voice Interaction<br/>[app.js]"]
  node_admin["Circular Portal<br/>[admin.html]"]
  node_faculty_ui["Faculty Dashboard<br/>[faculty.html]"]
  node_simulator["Channel Simulator<br/>[simulator.html]"]
end

subgraph group_orchestration["Chat Orchestration"]
  node_api["FastAPI Routes<br/>[main.py]"]
  node_translation["Language Translation"]
  node_llm["Answer Generation<br/>[llm_service.py]"]
end

subgraph group_knowledge["Circular Knowledge"]
  node_rag["Circular Retrieval<br/>[rag_service.py]"]
  node_parser["Circular Ingestion<br/>[circular_parser.py]"]
  node_circular_data["Sample Circulars"]
  node_vectorstore[("Chroma Index<br/>[rag_service.py]")]
end

subgraph group_resolution["Faculty Resolution"]
  node_database[("SQLite Records<br/>[database.py]")]
  node_faculty_service["Ticket Service<br/>[faculty_service.py]"]
end

subgraph group_channels["Messaging Channels"]
  node_whatsapp["WhatsApp Adapter<br/>[whatsapp.py]"]
  node_telegram["Telegram Adapter<br/>[telegram.py]"]
end

node_student(("Student"))
node_volunteer(("Volunteer"))
node_faculty(("Faculty"))
node_whatsapp_service{{"WhatsApp API"}}
node_telegram_service{{"Telegram API"}}

node_student -->|"uses"| node_web
node_web -.->|"submits queries"| node_api
node_api -->|"translates query"| node_translation
node_api -->|"loads history"| node_database
node_api -->|"searches circulars"| node_rag
node_api -->|"generates answer"| node_llm
node_api -->|"escalates query"| node_faculty_service
node_faculty_service -->|"creates tickets"| node_database
node_faculty_service -->|"translates replies"| node_translation
node_api -.->|"stores conversation"| node_database
node_volunteer -->|"manages notices"| node_admin
node_admin -.->|"uploads circulars"| node_api
node_api -->|"ingests uploads"| node_parser
node_parser -->|"indexes chunks"| node_rag
node_parser -->|"creates circular"| node_database
node_circular_data -.->|"seeds notices"| node_parser
node_rag -->|"searches index"| node_vectorstore
node_rag -->|"reads fallback chunks"| node_database
node_faculty -->|"resolves tickets"| node_faculty_ui
node_faculty_ui -.->|"manages tickets"| node_api
node_student -->|"tests channels"| node_simulator
node_api -->|"dispatches webhook"| node_whatsapp
node_whatsapp -->|"sends reply"| node_api
node_whatsapp -->|"sends messages"| node_whatsapp_service
node_api -.->|"routes webhook"| node_telegram
node_telegram -->|"sends messages"| node_telegram_service
node_web -->|"provides voice"| node_voice

click node_web "https://github.com/hemanth354/language-agnostic-chatbot/blob/main/templates/index.html"
click node_voice "https://github.com/hemanth354/language-agnostic-chatbot/blob/main/static/js/app.js"
click node_admin "https://github.com/hemanth354/language-agnostic-chatbot/blob/main/templates/admin.html"
click node_faculty_ui "https://github.com/hemanth354/language-agnostic-chatbot/blob/main/templates/faculty.html"
click node_simulator "https://github.com/hemanth354/language-agnostic-chatbot/blob/main/templates/simulator.html"
click node_api "https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/main.py"
click node_translation "https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/translation_service.py"
click node_rag "https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/rag_service.py"
click node_llm "https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/llm_service.py"
click node_parser "https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/circular_parser.py"
click node_circular_data "https://github.com/hemanth354/language-agnostic-chatbot/tree/main/data/circulars"
click node_vectorstore "https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/rag_service.py"
click node_database "https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/database.py"
click node_faculty_service "https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/faculty_service.py"
click node_whatsapp "https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/channels/whatsapp.py"
click node_telegram "https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/channels/telegram.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,node_voice,node_admin,node_faculty_ui,node_simulator toneBlue
class node_api,node_translation,node_llm toneAmber
class node_rag,node_parser,node_circular_data,node_vectorstore,node_whatsapp_service,node_telegram_service toneMint
class node_database,node_faculty_service toneRose
class node_whatsapp,node_telegram,node_student,node_volunteer,node_faculty toneIndigo
```

## Components

### User Interfaces

- [Web UI](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/templates/index.html): `templates/index.html`
- [Voice Interaction](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/static/js/app.js): `static/js/app.js`
- [Circular Portal](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/templates/admin.html): `templates/admin.html`
- [Faculty Dashboard](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/templates/faculty.html): `templates/faculty.html`
- [Channel Simulator](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/templates/simulator.html): `templates/simulator.html`

### Chat Orchestration

- [FastAPI Routes](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/main.py): `app/main.py`
- [Language Translation](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/translation_service.py): `app/translation_service.py`
- [Answer Generation](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/llm_service.py): `app/llm_service.py`

### Circular Knowledge

- [Circular Retrieval](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/rag_service.py): `app/rag_service.py`
- [Circular Ingestion](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/circular_parser.py): `app/circular_parser.py`
- [Sample Circulars](https://github.com/hemanth354/language-agnostic-chatbot/tree/main/data/circulars): `data/circulars`
- [Chroma Index](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/rag_service.py): `app/rag_service.py`

### Faculty Resolution

- [SQLite Records](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/database.py): `app/database.py`
- [Ticket Service](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/faculty_service.py): `app/faculty_service.py`

### Messaging Channels

- [WhatsApp Adapter](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/channels/whatsapp.py): `app/channels/whatsapp.py`
- [Telegram Adapter](https://github.com/hemanth354/language-agnostic-chatbot/blob/main/app/channels/telegram.py): `app/channels/telegram.py`

### Other components

- **Student**
- **Volunteer**
- **Faculty**
- **WhatsApp API**
- **Telegram API**

## Connections

- Student → Web UI: uses (evidence: `README.md`)
- Web UI → FastAPI Routes: submits queries
- FastAPI Routes → Language Translation: translates query (evidence: `app/main.py`)
- FastAPI Routes → SQLite Records: loads history (evidence: `app/main.py`)
- FastAPI Routes → Circular Retrieval: searches circulars (evidence: `app/main.py`)
- FastAPI Routes → Answer Generation: generates answer (evidence: `app/main.py`)
- FastAPI Routes → Ticket Service: escalates query (evidence: `app/main.py`)
- Ticket Service → SQLite Records: creates tickets (evidence: `app/faculty_service.py`)
- Ticket Service → Language Translation: translates replies (evidence: `app/faculty_service.py`)
- FastAPI Routes → SQLite Records: stores conversation (evidence: `app/main.py`)
- Volunteer → Circular Portal: manages notices (evidence: `README.md`)
- Circular Portal → FastAPI Routes: uploads circulars
- FastAPI Routes → Circular Ingestion: ingests uploads (evidence: `app/main.py`)
- Circular Ingestion → Circular Retrieval: indexes chunks (evidence: `app/circular_parser.py`)
- Circular Ingestion → SQLite Records: creates circular (evidence: `app/circular_parser.py`)
- Sample Circulars → Circular Ingestion: seeds notices
- Circular Retrieval → Chroma Index: searches index (evidence: `app/rag_service.py`)
- Circular Retrieval → SQLite Records: reads fallback chunks (evidence: `app/rag_service.py`)
- Faculty → Faculty Dashboard: resolves tickets (evidence: `README.md`)
- Faculty Dashboard → FastAPI Routes: manages tickets
- Student → Channel Simulator: tests channels (evidence: `README.md`)
- FastAPI Routes → WhatsApp Adapter: dispatches webhook (evidence: `app/main.py`)
- WhatsApp Adapter → FastAPI Routes: sends reply (evidence: `app/main.py`)
- WhatsApp Adapter → WhatsApp API: sends messages (evidence: `app/channels/whatsapp.py`)
- FastAPI Routes → Telegram Adapter: routes webhook (evidence: `app/main.py`)
- Telegram Adapter → Telegram API: sends messages (evidence: `app/channels/telegram.py`)
- Web UI → Voice Interaction: provides voice (evidence: `README.md`)