ranger-drax/ai-powered-chatbot

1. The repo is split into two independent runtimes plus an offline data pipeline.

The Python side contains both the ingestion/build pipeline (src/) and the serving backend (backend/). The TypeScript side is a separate Next.js frontend (frontend/). They communicate only through the backend HTTP API.

2. The knowledge base is built offline from local course files.

Raw university documents live outside version control in raw/. The pipeline converts them into persistent artifacts in storage/ and vector_store/chroma/, which are then read at runtime. This is a clear boundary: ingestion writes the index, chat serving only reads it.

3. Ingestion is a 3-stage document pipeline.

Stage 1 parses PDFs/DOCX/PPTX into structured elements using Unstructured.io and LlamaIndex. Stage 2 turns those elements into overlap-aware chunks while preserving metadata. Stage 3 embeds chunks with all-MiniLM-L6-v2 and stores them in a local ChromaDB collection named course_knowledge.

4. The src/ingestion package holds the reusable ingestion plumbing.

It contains file discovery, loader integrations, settings, and utility code. The stage scripts (stage1_ingest.py, stage2_chunk.py, stage3_embed_store.py) orchestrate these helpers, while stage4_retrieval_test.py and stage5_rag_answer_groq.py are CLI validation tools for the retrieval and full RAG paths.

5. The backend is a small FastAPI service centered on one chat endpoint.

backend/main.py creates the app, applies startup/lifespan setup, and configures CORS for the frontend. backend/routers/chat.py exposes POST /api/chat. Pydantic models in backend/models/schemas.py define the request and response shapes.

6. The runtime answer flow is retrieval-augmented generation, not direct LLM chat.

The chat service in backend/services/rag_service.py embeds the user question, searches Chroma for relevant chunks, and then sends the retrieved context plus the question to Groq’s hosted LLM (llama-3.3-70b-versatile). The answer returned to the client includes both generated text and provenance data.

7. Course detection is a separate preprocessing step before retrieval.

backend/services/course_detection.py looks for course code patterns like CSE220, CSE 220, CSE-220, or HST103. If a code is found, it resolves it to the indexed metadata course name and switches retrieval into a course-filtered mode; if not, retrieval falls back to a global search over all chunks.

8. The retrieval boundary is local and persistent.

ChromaDB is the only runtime datastore. There is no separate application database. The backend reads from the local Chroma collection, uses a distance threshold to decide whether the retrieved context is good enough, and can return a fallback message when evidence is weak.

9. The frontend is a thin chat shell with no knowledge-base logic.

frontend/app/page.tsx composes the page layout and state. ChatWindow, ChatInput, MessageBubble, and Sidebar handle presentation. frontend/lib/api.ts is the only client-side integration point to the backend. The UI accepts just a question; it does not expose course selection.

10. The user-facing API is intentionally minimal, but the response is rich.

The frontend sends question and optionally session_id. The backend response includes answer, status, detected_course_code, resolved_course, retrieval_mode, retrieved_chunks, best_distance, and sources. Those fields are the main outputs you’d want to show on an architecture diagram.

11. Operationally, the system is designed to run locally with environment-based configuration.

The important runtime dependencies are the Groq API key, the Chroma directory path, embedding model name, retrieval top-k, and token/context limits. Generated data and secrets are excluded from git, so a fresh clone needs either rebuilt embeddings or a copied Chroma store.

12. Tests focus on the orchestration boundary, not external services.

tests/test_chat.py mocks Chroma retrieval and Groq calls, so the normal test suite does not depend on raw documents or live API access. Live RAG checks are optional and gated by environment variables.