# amar-cmd/college-ai-helpdesk-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/amar-cmd/college-ai-helpdesk-chatbot
- Repository: https://github.com/amar-cmd/college-ai-helpdesk-chatbot

## Overview

AI Buddy is a college helpdesk chatbot with student chat, an admin-managed knowledge base, and operational diagnostics. A user submits a question through the chat interface; the chat API validates it, checks limits and cached or knowledge context, optionally searches the web, and requests generation through configured providers with fallback behavior. It saves chat and provider-attempt data and returns the response. Admin pages manage knowledge and inspect provider and rate-limit activity. The graph follows documented capabilities and visible imports/calls; unsampled details are left unconnected where evidence is insufficient.

Main entry points: [`src/app/api/chat/route.ts`](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/app/api/chat/route.ts) (Chat API), [`src/app/chat/page.tsx`](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/app/chat/page.tsx) (Chat page), [`src/app/admin/diagnostics/page.tsx`](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/app/admin/diagnostics/page.tsx) (Diagnostics page), [`src/lib/llm/router.ts`](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/llm/router.ts) (Provider router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_chat_ui["Chat interface<br/>[ChatWindow.tsx]"]
  node_chat_page["Chat page<br/>[page.tsx]"]
end

subgraph group_chatflow["Chat response flow"]
  node_chat_api["Chat API<br/>[route.ts]"]
  node_validation["Input validation<br/>[validateInput.ts]"]
  node_rate_limits["Rate limits"]
  node_answer_cache["Answer cache<br/>[answerCache.ts]"]
  node_knowledge_retrieval["Knowledge retrieval"]
  node_web_search["Brave web search"]
end

subgraph group_generation["Answer generation"]
  node_prompt["Prompt construction<br/>[prompt.ts]"]
  node_llm_router["Provider router<br/>[router.ts]"]
  node_provider_adapters["Provider adapters"]
  node_fallback["Controlled fallback<br/>[fallback.ts]"]
end

subgraph group_operations["Admin operations"]
  node_admin_knowledge["Knowledge management<br/>[actions.ts]"]
  node_admin_diagnostics["Diagnostics page<br/>[page.tsx]"]
  node_diagnostics_view["Diagnostics view"]
end

subgraph group_platform["Persistence and services"]
  node_chat_sessions["Chat sessions<br/>[chatSessions.ts]"]
  node_chat_messages["Chat messages<br/>[chatMessages.ts]"]
  node_provider_logs["Provider logs<br/>[providerLogs.ts]"]
  node_knowledge_store["Knowledge store<br/>[knowledgeBase.ts]"]
  node_supabase["Supabase client<br/>[server.ts]"]
  node_postgres[("Supabase / PostgreSQL")]
  node_rate_logs["Rate-limit logs<br/>[rateLimitLogs.ts]"]
end

node_student(("Student"))
node_brave{{"Brave Search"}}
node_llm_services{{"LLM services"}}

node_student -->|"opens chat"| node_chat_page
node_chat_page -->|"renders"| node_chat_ui
node_chat_ui -.->|"submits question"| node_chat_api
node_chat_api -->|"validates input"| node_validation
node_chat_api -->|"checks limits"| node_rate_limits
node_chat_api -->|"checks and saves"| node_answer_cache
node_chat_api -->|"retrieves context"| node_knowledge_retrieval
node_chat_api -->|"retrieves fallback context"| node_web_search
node_chat_api -->|"builds prompt"| node_prompt
node_chat_api -->|"requests generation"| node_llm_router
node_llm_router -->|"dispatches providers"| node_provider_adapters
node_llm_router -->|"returns fallback"| node_fallback
node_provider_adapters -.->|"calls providers"| node_llm_services
node_web_search -->|"searches"| node_brave
node_chat_api -->|"loads session"| node_chat_sessions
node_chat_api -->|"saves messages"| node_chat_messages
node_chat_api -->|"records attempts"| node_provider_logs
node_chat_api -->|"creates client"| node_supabase
node_chat_page -->|"prepares session"| node_chat_sessions
node_chat_page -->|"loads history"| node_chat_messages
node_supabase -->|"connects to"| node_postgres
node_admin_knowledge -.->|"manages entries"| node_knowledge_store
node_admin_diagnostics -->|"loads activity"| node_provider_logs
node_admin_diagnostics -->|"loads events"| node_rate_logs
node_admin_diagnostics -->|"renders"| node_diagnostics_view

click node_chat_ui "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/components/chat/ChatWindow.tsx"
click node_chat_page "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/app/chat/page.tsx"
click node_chat_api "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/app/api/chat/route.ts"
click node_validation "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/safety/validateInput.ts"
click node_rate_limits "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/tree/master/src/lib/rate-limit"
click node_answer_cache "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/db/answerCache.ts"
click node_knowledge_retrieval "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/rag/retrieveKnowledge.ts"
click node_web_search "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/web-search/retrieveWebSearch.ts"
click node_prompt "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/llm/prompt.ts"
click node_llm_router "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/llm/router.ts"
click node_provider_adapters "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/tree/master/src/lib/llm/providers"
click node_fallback "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/llm/fallback.ts"
click node_chat_sessions "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/db/chatSessions.ts"
click node_chat_messages "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/db/chatMessages.ts"
click node_provider_logs "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/db/providerLogs.ts"
click node_knowledge_store "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/db/knowledgeBase.ts"
click node_supabase "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/supabase/server.ts"
click node_admin_knowledge "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/app/admin/knowledge/actions.ts"
click node_admin_diagnostics "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/app/admin/diagnostics/page.tsx"
click node_diagnostics_view "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/components/admin/AdminDiagnostics.tsx"
click node_rate_logs "https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/db/rateLimitLogs.ts"

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_chat_ui,node_chat_page toneBlue
class node_chat_api,node_validation,node_rate_limits,node_answer_cache,node_knowledge_retrieval,node_web_search toneAmber
class node_prompt,node_llm_router,node_provider_adapters,node_fallback toneMint
class node_admin_knowledge,node_admin_diagnostics,node_diagnostics_view toneRose
class node_chat_sessions,node_chat_messages,node_provider_logs,node_knowledge_store,node_supabase,node_postgres,node_rate_logs,node_student,node_brave,node_llm_services toneIndigo
```

## Components

### User experience

- [Chat interface](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/components/chat/ChatWindow.tsx): `src/components/chat/ChatWindow.tsx`
- [Chat page](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/app/chat/page.tsx): `src/app/chat/page.tsx`

### Chat response flow

- [Chat API](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [Input validation](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/safety/validateInput.ts): `src/lib/safety/validateInput.ts`
- [Rate limits](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/tree/master/src/lib/rate-limit): `src/lib/rate-limit`
- [Answer cache](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/db/answerCache.ts): `src/lib/db/answerCache.ts`
- [Knowledge retrieval](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/rag/retrieveKnowledge.ts): `src/lib/rag/retrieveKnowledge.ts`
- [Brave web search](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/web-search/retrieveWebSearch.ts): `src/lib/web-search/retrieveWebSearch.ts`

### Answer generation

- [Prompt construction](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/llm/prompt.ts): `src/lib/llm/prompt.ts`
- [Provider router](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/llm/router.ts): `src/lib/llm/router.ts`
- [Provider adapters](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/tree/master/src/lib/llm/providers): `src/lib/llm/providers`
- [Controlled fallback](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/llm/fallback.ts): `src/lib/llm/fallback.ts`

### Admin operations

- [Knowledge management](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/app/admin/knowledge/actions.ts): `src/app/admin/knowledge/actions.ts`
- [Diagnostics page](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/app/admin/diagnostics/page.tsx): `src/app/admin/diagnostics/page.tsx`
- [Diagnostics view](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/components/admin/AdminDiagnostics.tsx): `src/components/admin/AdminDiagnostics.tsx`

### Persistence and services

- [Chat sessions](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/db/chatSessions.ts): `src/lib/db/chatSessions.ts`
- [Chat messages](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/db/chatMessages.ts): `src/lib/db/chatMessages.ts`
- [Provider logs](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/db/providerLogs.ts): `src/lib/db/providerLogs.ts`
- [Knowledge store](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/db/knowledgeBase.ts): `src/lib/db/knowledgeBase.ts`
- [Supabase client](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/supabase/server.ts): `src/lib/supabase/server.ts`
- **Supabase / PostgreSQL**
- [Rate-limit logs](https://github.com/amar-cmd/college-ai-helpdesk-chatbot/blob/master/src/lib/db/rateLimitLogs.ts): `src/lib/db/rateLimitLogs.ts`

### Other components

- **Student**
- **Brave Search**
- **LLM services**

## Connections

- Student → Chat page: opens chat (evidence: `README.md`)
- Chat page → Chat interface: renders (evidence: `src/app/chat/page.tsx`)
- Chat interface → Chat API: submits question
- Chat API → Input validation: validates input (evidence: `src/app/api/chat/route.ts`)
- Chat API → Rate limits: checks limits (evidence: `src/app/api/chat/route.ts`)
- Chat API → Answer cache: checks and saves (evidence: `src/app/api/chat/route.ts`)
- Chat API → Knowledge retrieval: retrieves context (evidence: `src/app/api/chat/route.ts`)
- Chat API → Brave web search: retrieves fallback context (evidence: `src/app/api/chat/route.ts`)
- Chat API → Prompt construction: builds prompt (evidence: `src/app/api/chat/route.ts`)
- Chat API → Provider router: requests generation (evidence: `src/app/api/chat/route.ts`)
- Provider router → Provider adapters: dispatches providers (evidence: `src/lib/llm/router.ts`)
- Provider router → Controlled fallback: returns fallback (evidence: `src/lib/llm/router.ts`)
- Provider adapters → LLM services: calls providers
- Brave web search → Brave Search: searches (evidence: `src/lib/web-search/retrieveWebSearch.ts`)
- Chat API → Chat sessions: loads session (evidence: `src/app/api/chat/route.ts`)
- Chat API → Chat messages: saves messages (evidence: `src/app/api/chat/route.ts`)
- Chat API → Provider logs: records attempts (evidence: `src/app/api/chat/route.ts`)
- Chat API → Supabase client: creates client (evidence: `src/app/api/chat/route.ts`)
- Chat page → Chat sessions: prepares session (evidence: `src/app/chat/page.tsx`)
- Chat page → Chat messages: loads history (evidence: `src/app/chat/page.tsx`)
- Supabase client → Supabase / PostgreSQL: connects to (evidence: `src/lib/supabase/server.ts`)
- Knowledge management → Knowledge store: manages entries
- Diagnostics page → Provider logs: loads activity (evidence: `src/app/admin/diagnostics/page.tsx`)
- Diagnostics page → Rate-limit logs: loads events (evidence: `src/app/admin/diagnostics/page.tsx`)
- Diagnostics page → Diagnostics view: renders (evidence: `src/app/admin/diagnostics/page.tsx`)
