How amar-cmd/college-ai-helpdesk-chatbot works
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: route.ts Chat API · chat/page.tsx Chat page · diagnostics/page.tsx Diagnostics page · router.ts Provider router
Components 25
User experience
- Chat interface
src/components/chat/ChatWindow.tsx - Chat page
src/app/chat/page.tsx
Chat response flow
- Chat API
src/app/api/chat/route.ts - Input validation
src/lib/safety/validateInput.ts - Rate limits
src/lib/rate-limit - Answer cache
src/lib/db/answerCache.ts - Knowledge retrieval
src/lib/rag/retrieveKnowledge.ts - Brave web search
src/lib/web-search/retrieveWebSearch.ts
Answer generation
- Prompt construction
src/lib/llm/prompt.ts - Provider router
src/lib/llm/router.ts - Provider adapters
src/lib/llm/providers - Controlled fallback
src/lib/llm/fallback.ts
Admin operations
- Knowledge management
src/app/admin/knowledge/actions.ts - Diagnostics page
src/app/admin/diagnostics/page.tsx - Diagnostics view
src/components/admin/AdminDiagnostics.tsx
Persistence and services
- Chat sessions
src/lib/db/chatSessions.ts - Chat messages
src/lib/db/chatMessages.ts - Provider logs
src/lib/db/providerLogs.ts - Knowledge store
src/lib/db/knowledgeBase.ts - Supabase client
src/lib/supabase/server.ts - Supabase / PostgreSQL
- Rate-limit logs
src/lib/db/rateLimitLogs.ts
Other components
- Student
- Brave Search
- LLM services
Connections 25
- Student → Chat page: opens chat
README.md - Chat page → Chat interface: renders
src/app/chat/page.tsx - Chat interface → Chat API: submits question
- Chat API → Input validation: validates input
src/app/api/chat/route.ts - Chat API → Rate limits: checks limits
src/app/api/chat/route.ts - Chat API → Answer cache: checks and saves
src/app/api/chat/route.ts - Chat API → Knowledge retrieval: retrieves context
src/app/api/chat/route.ts - Chat API → Brave web search: retrieves fallback context
src/app/api/chat/route.ts - Chat API → Prompt construction: builds prompt
src/app/api/chat/route.ts - Chat API → Provider router: requests generation
src/app/api/chat/route.ts - Provider router → Provider adapters: dispatches providers
src/lib/llm/router.ts - Provider router → Controlled fallback: returns fallback
src/lib/llm/router.ts - Provider adapters → LLM services: calls providers
- Brave web search → Brave Search: searches
src/lib/web-search/retrieveWebSearch.ts - Chat API → Chat sessions: loads session
src/app/api/chat/route.ts - Chat API → Chat messages: saves messages
src/app/api/chat/route.ts - Chat API → Provider logs: records attempts
src/app/api/chat/route.ts - Chat API → Supabase client: creates client
src/app/api/chat/route.ts - Chat page → Chat sessions: prepares session
src/app/chat/page.tsx - Chat page → Chat messages: loads history
src/app/chat/page.tsx - Supabase client → Supabase / PostgreSQL: connects to
src/lib/supabase/server.ts - Knowledge management → Knowledge store: manages entries
- Diagnostics page → Provider logs: loads activity
src/app/admin/diagnostics/page.tsx - Diagnostics page → Rate-limit logs: loads events
src/app/admin/diagnostics/page.tsx - Diagnostics page → Diagnostics view: renders
src/app/admin/diagnostics/page.tsx