# dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot architecture

> Architecture diagram of the GitHub repository dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot, 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/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot
- Repository: https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot

## Overview

Knoq-AI is a campus helpdesk whose main flow runs from the student chat UI through the API’s chat orchestration, optional cache/FAQ/RAG context gathering, and Gemini response generation; navigation requests additionally use campus route data or Google Maps. The frontend also supports student accounts and an admin knowledge-ingestion workflow. Some modules are represented from the README and source index rather than inspected excerpts, so only documented or indexed relationships are connected.

Main entry points: [`backend/routes/chat.js`](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/routes/chat.js) (Chat Orchestrator), [`backend/server.js`](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/server.js) (Express Server), [`backend/services/gemini.js`](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/services/gemini.js) (Gemini Service), [`backend/routes/admin.js`](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/routes/admin.js) (Admin Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Student Web App"]
  node_app["App Router<br/>[App.jsx]"]
  node_chatui["Chat Panel<br/>[ChatPanel.jsx]"]
  node_adminui["Admin Console<br/>[Admin.jsx]"]
  node_crawlerui["Crawler UI<br/>[SiteCrawler.jsx]"]
  node_authctx["Auth Context<br/>[AuthContext.jsx]"]
  node_apiclient["API Client<br/>[client.js]"]
end

subgraph group_api["Backend API"]
  node_server["Express Server<br/>[server.js]"]
  node_authroutes["Auth Routes<br/>[auth.js]"]
  node_chatroutes["Chat Orchestrator<br/>[chat.js]"]
  node_adminroutes["Admin Routes<br/>[admin.js]"]
  node_crawlroute["Crawl Routes<br/>[crawl.js]"]
  node_authmw["Auth Middleware<br/>[auth.js]"]
end

subgraph group_knowledge["Knowledge and AI"]
  node_rag["RAG Retrieval<br/>[rag.js]"]
  node_gemini["Gemini Service<br/>[gemini.js]"]
  node_semcache["Semantic Cache<br/>[semanticCache.js]"]
end

subgraph group_data["Data and Integrations"]
  node_faq[("FAQ Knowledge<br/>[Faq.js]")]
  node_brochure[("Brochure Pages<br/>[BrochurePage.js]")]
  node_scraped[("Scraped Pages<br/>[ScrapedPage.js]")]
  node_campusroutes[("Campus Routes<br/>[CampusRoute.js]")]
  node_users[("User Accounts<br/>[User.js]")]
  node_chatlogs[("Chat Logs<br/>[ChatLog.js]")]
  node_maps["Google Maps Service<br/>[googleMaps.js]"]
end

node_student(("Student / Admin"))
node_geminiexternal{{"Google Gemini"}}
node_googlemaps{{"Google Maps"}}

node_student -->|"uses"| node_app
node_app -->|"renders chat"| node_chatui
node_chatui -->|"sends requests"| node_apiclient
node_adminui -->|"calls API"| node_apiclient
node_adminui -->|"renders crawler"| node_crawlerui
node_authctx -->|"calls API"| node_apiclient
node_apiclient -.->|"HTTP requests"| node_server
node_server -->|"mounts routes"| node_authroutes
node_server -->|"mounts routes"| node_chatroutes
node_server -->|"mounts routes"| node_adminroutes
node_server -->|"mounts routes"| node_crawlroute
node_authroutes -->|"reads and writes"| node_users
node_authroutes -->|"protects profile"| node_authmw
node_authmw -->|"loads account"| node_users
node_chatroutes -->|"searches FAQs"| node_faq
node_chatroutes -->|"records chats"| node_chatlogs
node_chatroutes -->|"looks up routes"| node_campusroutes
node_chatroutes -->|"retrieves context"| node_rag
node_chatroutes -->|"checks and saves"| node_semcache
node_chatroutes -->|"generates reply"| node_gemini
node_chatroutes -->|"resolves distance"| node_maps
node_rag -->|"searches pages"| node_brochure
node_rag -->|"searches pages"| node_scraped
node_rag -->|"embeds query"| node_gemini
node_gemini -->|"requests generation"| node_geminiexternal
node_maps -.->|"requests directions"| node_googlemaps
node_crawlroute -->|"stores crawl pages"| node_scraped
node_crawlroute -->|"creates FAQs"| node_faq
node_crawlroute -->|"extracts content"| node_gemini
node_adminroutes -->|"manages uploads"| node_brochure
node_adminroutes -->|"reads conversations"| node_chatlogs
node_adminroutes -->|"generates embeddings"| node_gemini
node_maps -->|"uses route data"| node_campusroutes

click node_app "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/frontend/src/App.jsx"
click node_chatui "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/frontend/src/components/ChatPanel.jsx"
click node_adminui "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/frontend/src/pages/Admin.jsx"
click node_crawlerui "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/frontend/src/components/SiteCrawler.jsx"
click node_authctx "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/frontend/src/contexts/AuthContext.jsx"
click node_apiclient "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/frontend/src/api/client.js"
click node_server "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/server.js"
click node_authroutes "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/routes/auth.js"
click node_chatroutes "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/routes/chat.js"
click node_adminroutes "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/routes/admin.js"
click node_crawlroute "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/routes/crawl.js"
click node_authmw "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/middleware/auth.js"
click node_rag "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/services/rag.js"
click node_gemini "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/services/gemini.js"
click node_semcache "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/services/semanticCache.js"
click node_faq "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/models/Faq.js"
click node_brochure "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/models/BrochurePage.js"
click node_scraped "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/models/ScrapedPage.js"
click node_campusroutes "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/models/CampusRoute.js"
click node_users "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/models/User.js"
click node_chatlogs "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/models/ChatLog.js"
click node_maps "https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/services/googleMaps.js"

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_app,node_chatui,node_adminui,node_crawlerui,node_authctx,node_apiclient toneBlue
class node_server,node_authroutes,node_chatroutes,node_adminroutes,node_crawlroute,node_authmw toneAmber
class node_rag,node_gemini,node_semcache toneMint
class node_faq,node_brochure,node_scraped,node_campusroutes,node_users,node_chatlogs,node_maps toneRose
class node_student,node_geminiexternal,node_googlemaps toneIndigo
```

## Components

### Student Web App

- [App Router](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Chat Panel](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/frontend/src/components/ChatPanel.jsx): `frontend/src/components/ChatPanel.jsx`
- [Admin Console](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/frontend/src/pages/Admin.jsx): `frontend/src/pages/Admin.jsx`
- [Crawler UI](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/frontend/src/components/SiteCrawler.jsx): `frontend/src/components/SiteCrawler.jsx`
- [Auth Context](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/frontend/src/contexts/AuthContext.jsx): `frontend/src/contexts/AuthContext.jsx`
- [API Client](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### Backend API

- [Express Server](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/server.js): `backend/server.js`
- [Auth Routes](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/routes/auth.js): `backend/routes/auth.js`
- [Chat Orchestrator](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/routes/chat.js): `backend/routes/chat.js`
- [Admin Routes](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/routes/admin.js): `backend/routes/admin.js`
- [Crawl Routes](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/routes/crawl.js): `backend/routes/crawl.js`
- [Auth Middleware](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/middleware/auth.js): `backend/middleware/auth.js`

### Knowledge and AI

- [RAG Retrieval](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/services/rag.js): `backend/services/rag.js`
- [Gemini Service](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/services/gemini.js): `backend/services/gemini.js`
- [Semantic Cache](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/services/semanticCache.js): `backend/services/semanticCache.js`

### Data and Integrations

- [FAQ Knowledge](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/models/Faq.js): `backend/models/Faq.js`
- [Brochure Pages](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/models/BrochurePage.js): `backend/models/BrochurePage.js`
- [Scraped Pages](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/models/ScrapedPage.js): `backend/models/ScrapedPage.js`
- [Campus Routes](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/models/CampusRoute.js): `backend/models/CampusRoute.js`
- [User Accounts](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/models/User.js): `backend/models/User.js`
- [Chat Logs](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/models/ChatLog.js): `backend/models/ChatLog.js`
- [Google Maps Service](https://github.com/dhruv4848l/knoq-ai-parul-university-helpdesk-chat-bot/blob/main/backend/services/googleMaps.js): `backend/services/googleMaps.js`

### Other components

- **Student / Admin**
- **Google Gemini**
- **Google Maps**

## Connections

- Student / Admin → App Router: uses (evidence: `README.md`)
- App Router → Chat Panel: renders chat (evidence: `frontend/src/App.jsx`)
- Chat Panel → API Client: sends requests (evidence: `frontend/src/components/ChatPanel.jsx`)
- Admin Console → API Client: calls API (evidence: `frontend/src/pages/Admin.jsx`)
- Admin Console → Crawler UI: renders crawler (evidence: `frontend/src/pages/Admin.jsx`)
- Auth Context → API Client: calls API (evidence: `frontend/src/contexts/AuthContext.jsx`)
- API Client → Express Server: HTTP requests
- Express Server → Auth Routes: mounts routes (evidence: `backend/server.js`)
- Express Server → Chat Orchestrator: mounts routes (evidence: `backend/server.js`)
- Express Server → Admin Routes: mounts routes (evidence: `backend/server.js`)
- Express Server → Crawl Routes: mounts routes (evidence: `backend/server.js`)
- Auth Routes → User Accounts: reads and writes (evidence: `backend/routes/auth.js`)
- Auth Routes → Auth Middleware: protects profile (evidence: `backend/routes/auth.js`)
- Auth Middleware → User Accounts: loads account (evidence: `backend/middleware/auth.js`)
- Chat Orchestrator → FAQ Knowledge: searches FAQs (evidence: `backend/routes/chat.js`)
- Chat Orchestrator → Chat Logs: records chats (evidence: `backend/routes/chat.js`)
- Chat Orchestrator → Campus Routes: looks up routes (evidence: `backend/routes/chat.js`)
- Chat Orchestrator → RAG Retrieval: retrieves context (evidence: `backend/routes/chat.js`)
- Chat Orchestrator → Semantic Cache: checks and saves (evidence: `backend/routes/chat.js`)
- Chat Orchestrator → Gemini Service: generates reply (evidence: `backend/routes/chat.js`)
- Chat Orchestrator → Google Maps Service: resolves distance (evidence: `backend/routes/chat.js`)
- RAG Retrieval → Brochure Pages: searches pages (evidence: `backend/services/rag.js`)
- RAG Retrieval → Scraped Pages: searches pages (evidence: `backend/services/rag.js`)
- RAG Retrieval → Gemini Service: embeds query (evidence: `backend/services/rag.js`)
- Gemini Service → Google Gemini: requests generation (evidence: `backend/services/gemini.js`)
- Google Maps Service → Google Maps: requests directions
- Crawl Routes → Scraped Pages: stores crawl pages (evidence: `backend/routes/crawl.js`)
- Crawl Routes → FAQ Knowledge: creates FAQs (evidence: `backend/routes/crawl.js`)
- Crawl Routes → Gemini Service: extracts content (evidence: `backend/routes/crawl.js`)
- Admin Routes → Brochure Pages: manages uploads (evidence: `backend/routes/admin.js`)
- Admin Routes → Chat Logs: reads conversations (evidence: `backend/routes/admin.js`)
- Admin Routes → Gemini Service: generates embeddings (evidence: `backend/routes/admin.js`)
- Google Maps Service → Campus Routes: uses route data (evidence: `backend/services/googleMaps.js`)
