# iam-sharath/college_ai_chat_assistant architecture

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

- Interactive diagram: https://gitdiagram.com/iam-sharath/college_ai_chat_assistant
- Repository: https://github.com/iam-sharath/college_ai_chat_assistant

## Overview

College AI Assistant serves student questions through a web chat and optional WhatsApp, then returns grounded answers with sources and confidence. The Python engine rewrites queries, retrieves and reranks knowledge-base chunks, and generates answers through provider failover; repeated successful answers can be cached. Administrators upload, list, and delete documents through a protected panel, with ingestion feeding searchable indexes and SQLite tracking documents and chunks. The graph follows documented routes and excerpted calls; unsampled frontend and WhatsApp internals are represented only where README or route registration supports the relationship.

Main entry points: [`rag-engine/retrieval.py`](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/retrieval.py) (Knowledge store), [`backend/server.js`](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/backend/server.js) (Express server), [`rag-engine/app.py`](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/app.py) (RAG endpoints), [`backend/routes/admin.js`](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/backend/routes/admin.js) (Admin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_webchat["Web chat<br/>[app.js]"]
  node_adminui["Admin panel<br/>[admin.js]"]
end

subgraph group_api["API gateway"]
  node_gateway["Express server<br/>[server.js]"]
  node_chatapi["Chat API<br/>[chat.js]"]
  node_whatsappapi["WhatsApp route<br/>[whatsapp.js]"]
  node_adminapi["Admin API<br/>[admin.js]"]
  node_adminauth["Admin auth<br/>[adminAuth.js]"]
  node_responses["Response formatter<br/>[response.js]"]
end

subgraph group_rag["RAG engine"]
  node_ragapp["RAG endpoints<br/>[app.py]"]
  node_rewriter["Query rewriting<br/>[query_rewriter.py]"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.py]"]
  node_llm["LLM failover<br/>[llm_router.py]"]
  node_cache["Response cache<br/>[cache.py]"]
  node_config["Engine config<br/>[config.py]"]
end

subgraph group_knowledge["Knowledge management"]
  node_adminroutes["Document endpoints<br/>[app.py]"]
  node_ingestion["Document ingestion<br/>[ingestion.py]"]
  node_store["Knowledge store<br/>[retrieval.py]"]
  node_registry[("Document registry<br/>[db.py]")]
  node_vectorindex[("FAISS index<br/>[retrieval.py]")]
end

node_student(("Student"))
node_twilio["Twilio WhatsApp"]

node_student -->|"asks"| node_webchat
node_webchat -->|"uses"| node_gateway
node_gateway -->|"routes to"| node_chatapi
node_chatapi -->|"posts question"| node_ragapp
node_ragapp -->|"checks and stores"| node_cache
node_ragapp -->|"searches"| node_store
node_ragapp -->|"generates answer"| node_llm
node_store -->|"rewrites query"| node_rewriter
node_store -->|"searches and updates"| node_vectorindex
node_store -->|"reads and writes chunks"| node_registry
node_adminui -->|"manages documents"| node_gateway
node_gateway -->|"routes to"| node_adminapi
node_adminapi -->|"protects routes"| node_adminauth
node_adminapi -->|"formats responses"| node_responses
node_adminapi -->|"proxies document requests"| node_adminroutes
node_adminroutes -->|"lists and records"| node_registry
node_adminroutes -->|"extracts and chunks"| node_ingestion
node_adminroutes -->|"adds and removes chunks"| node_store
node_store -->|"persists chunk mappings"| node_registry
node_store -->|"persists vectors"| node_vectorindex
node_twilio -->|"sends webhook"| node_whatsappapi
node_gateway -->|"routes to"| node_whatsappapi
node_whatsappapi -.->|"forwards messages"| node_ragapp

click node_webchat "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/frontend/app.js"
click node_adminui "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/frontend/admin.js"
click node_gateway "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/backend/server.js"
click node_chatapi "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/backend/routes/chat.js"
click node_whatsappapi "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/backend/routes/whatsapp.js"
click node_adminapi "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/backend/routes/admin.js"
click node_adminauth "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/backend/middleware/adminAuth.js"
click node_responses "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/backend/utils/response.js"
click node_ragapp "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/app.py"
click node_rewriter "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/query_rewriter.py"
click node_retrieval "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/retrieval.py"
click node_llm "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/llm_router.py"
click node_cache "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/cache.py"
click node_config "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/config.py"
click node_adminroutes "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/app.py"
click node_ingestion "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/ingestion.py"
click node_store "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/retrieval.py"
click node_registry "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/db.py"
click node_vectorindex "https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/retrieval.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_webchat,node_adminui toneBlue
class node_gateway,node_chatapi,node_whatsappapi,node_adminapi,node_adminauth,node_responses toneAmber
class node_ragapp,node_rewriter,node_retrieval,node_llm,node_cache,node_config toneMint
class node_adminroutes,node_ingestion,node_store,node_registry,node_vectorindex toneRose
class node_student,node_twilio toneIndigo
```

## Components

### User interfaces

- [Web chat](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/frontend/app.js): `frontend/app.js`
- [Admin panel](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/frontend/admin.js): `frontend/admin.js`

### API gateway

- [Express server](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/backend/server.js): `backend/server.js`
- [Chat API](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/backend/routes/chat.js): `backend/routes/chat.js`
- [WhatsApp route](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/backend/routes/whatsapp.js): `backend/routes/whatsapp.js`
- [Admin API](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/backend/routes/admin.js): `backend/routes/admin.js`
- [Admin auth](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/backend/middleware/adminAuth.js): `backend/middleware/adminAuth.js`
- [Response formatter](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/backend/utils/response.js): `backend/utils/response.js`

### RAG engine

- [RAG endpoints](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/app.py): `rag-engine/app.py`
- [Query rewriting](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/query_rewriter.py): `rag-engine/query_rewriter.py`
- [Hybrid retrieval](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/retrieval.py): `rag-engine/retrieval.py`
- [LLM failover](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/llm_router.py): `rag-engine/llm_router.py`
- [Response cache](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/cache.py): `rag-engine/cache.py`
- [Engine config](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/config.py): `rag-engine/config.py`

### Knowledge management

- [Document endpoints](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/app.py): `rag-engine/app.py`
- [Document ingestion](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/ingestion.py): `rag-engine/ingestion.py`
- [Knowledge store](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/retrieval.py): `rag-engine/retrieval.py`
- [Document registry](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/db.py): `rag-engine/db.py`
- [FAISS index](https://github.com/iam-sharath/college_ai_chat_assistant/blob/main/rag-engine/retrieval.py): `rag-engine/retrieval.py`

### Other components

- **Student**
- **Twilio WhatsApp**

## Connections

- Student → Web chat: asks (evidence: `README.md`)
- Web chat → Express server: uses (evidence: `README.md`)
- Express server → Chat API: routes to (evidence: `backend/server.js`)
- Chat API → RAG endpoints: posts question (evidence: `backend/routes/chat.js`)
- RAG endpoints → Response cache: checks and stores (evidence: `rag-engine/app.py`)
- RAG endpoints → Knowledge store: searches (evidence: `rag-engine/app.py`)
- RAG endpoints → LLM failover: generates answer (evidence: `rag-engine/app.py`)
- Knowledge store → Query rewriting: rewrites query (evidence: `rag-engine/retrieval.py`)
- Knowledge store → FAISS index: searches and updates (evidence: `rag-engine/retrieval.py`)
- Knowledge store → Document registry: reads and writes chunks (evidence: `rag-engine/retrieval.py`)
- Admin panel → Express server: manages documents (evidence: `README.md`)
- Express server → Admin API: routes to (evidence: `backend/server.js`)
- Admin API → Admin auth: protects routes (evidence: `backend/routes/admin.js`)
- Admin API → Response formatter: formats responses (evidence: `backend/routes/admin.js`)
- Admin API → Document endpoints: proxies document requests (evidence: `backend/routes/admin.js`)
- Document endpoints → Document registry: lists and records (evidence: `rag-engine/app.py`)
- Document endpoints → Document ingestion: extracts and chunks (evidence: `rag-engine/app.py`)
- Document endpoints → Knowledge store: adds and removes chunks (evidence: `rag-engine/app.py`)
- Knowledge store → Document registry: persists chunk mappings (evidence: `rag-engine/retrieval.py`)
- Knowledge store → FAISS index: persists vectors (evidence: `rag-engine/retrieval.py`)
- Twilio WhatsApp → WhatsApp route: sends webhook (evidence: `README.md`)
- Express server → WhatsApp route: routes to (evidence: `backend/server.js`)
- WhatsApp route → RAG endpoints: forwards messages
