From d2eba7a80bf03ef9000a1284281cc61a98f81bee Mon Sep 17 00:00:00 2001
From: Amit <kuamit@nvidia.com>
Date: Sat, 2 May 2026 22:08:36 +0530
Subject: [PATCH] Add CLAUDE.md and code flow diagram

- CLAUDE.md documents run commands, uv-only dependency management, architecture, and course document format
- flow_diagram.html provides a visual reference of the full RAG query flow

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md         |  88 +++++++++
 flow_diagram.html | 492 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 580 insertions(+)
 create mode 100644 CLAUDE.md
 create mode 100644 flow_diagram.html

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..cefb831a4
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,88 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Running the Application
+
+**Prerequisites:** Python 3.13+, `uv`, and an Anthropic API key in a `.env` file:
+```
+ANTHROPIC_API_KEY=your-key-here
+```
+
+**Start the server:**
+```bash
+./run.sh
+# or manually:
+cd backend && uv run uvicorn app:app --reload --port 8000
+```
+
+**Install / sync dependencies:**
+```bash
+uv sync
+```
+
+> **Always use `uv` for all dependency management and running Python — never use `pip`, `pip install`, or bare `python` directly.**
+> - Add packages: `uv add <package>`
+> - Remove packages: `uv remove <package>`
+> - Sync environment: `uv sync`
+> - Run a script: `uv run <script>`
+
+App runs at `http://localhost:8000`. API docs at `http://localhost:8000/docs`.
+
+There is no test suite and no linter configured in this project.
+
+## Architecture
+
+This is a full-stack RAG (Retrieval-Augmented Generation) app. The backend is a FastAPI server that serves both the REST API and the static frontend files.
+
+### Query flow (the critical path)
+
+```
+Frontend (script.js)
+  → POST /api/query  (app.py)
+  → RAGSystem.query()  (rag_system.py)
+  → AIGenerator.generate_response()  (ai_generator.py)
+      Round 1: Claude decides whether to call the search tool
+      If tool_use → ToolManager.execute_tool()
+                  → CourseSearchTool.execute()
+                  → VectorStore.search()  [ChromaDB]
+      Round 2: Claude synthesises the final answer
+  → SessionManager.add_exchange()  stores history
+  → returns { answer, sources, session_id }
+```
+
+Claude makes **two API calls per RAG query**: once to decide if search is needed, once to synthesise. General-knowledge questions skip retrieval entirely.
+
+### Key design decisions
+
+- **Tool-based retrieval:** Claude autonomously decides when to call `search_course_content`. The tool accepts `query`, optional `course_name` (fuzzy-matched), and optional `lesson_number`.
+- **Two ChromaDB collections:** `course_catalog` resolves fuzzy course names via semantic search; `course_content` stores the actual text chunks for retrieval.
+- **Session history as plain text:** Conversation history is formatted as `"User: ...\nAssistant: ..."` and injected into the system prompt (not as structured messages). Capped at `MAX_HISTORY * 2 = 4` messages.
+- **ChromaDB persisted locally** at `./chroma_db` (relative to the `backend/` directory). The vector store is populated automatically on startup from the `../docs/` folder.
+- **All config lives in `config.py`:** model name, chunk size/overlap, max results, history length, ChromaDB path. The active Claude model is `claude-sonnet-4-20250514`.
+
+### Course document format
+
+Documents in `docs/` must follow this plain-text format for `DocumentProcessor` to parse them correctly:
+
+```
+Course Title: <title>
+Course Link: <url>
+Course Instructor: <name>
+
+Lesson 1: <lesson title>
+Lesson Link: <url>
+<lesson content...>
+
+Lesson 2: <lesson title>
+Lesson Link: <url>
+<lesson content...>
+```
+
+The `course_title` field is used as the unique ID in ChromaDB — duplicate titles are skipped on startup.
+
+### Adding a new tool
+
+1. Subclass `Tool` (abstract base in `search_tools.py`) and implement `get_tool_definition()` + `execute()`.
+2. Register it via `tool_manager.register_tool(your_tool)` in `RAGSystem.__init__`.
+3. If the tool produces sources for the UI, add a `last_sources` list attribute — `ToolManager.get_last_sources()` checks for it automatically.
diff --git a/flow_diagram.html b/flow_diagram.html
new file mode 100644
index 000000000..4524f3ce0
--- /dev/null
+++ b/flow_diagram.html
@@ -0,0 +1,492 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>RAG Chatbot — Code Flow</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+
+    body {
+      font-family: 'Segoe UI', system-ui, sans-serif;
+      background: #0f1117;
+      color: #e2e8f0;
+      min-height: 100vh;
+      padding: 40px 20px;
+    }
+
+    h1 {
+      text-align: center;
+      font-size: 1.6rem;
+      font-weight: 600;
+      color: #a78bfa;
+      margin-bottom: 8px;
+      letter-spacing: 0.04em;
+    }
+
+    .subtitle {
+      text-align: center;
+      color: #64748b;
+      font-size: 0.85rem;
+      margin-bottom: 48px;
+    }
+
+    .flow {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      gap: 0;
+      max-width: 780px;
+      margin: 0 auto;
+    }
+
+    /* ── Layer cards ── */
+    .layer {
+      width: 100%;
+      border-radius: 12px;
+      padding: 18px 24px;
+      position: relative;
+    }
+
+    .layer-label {
+      font-size: 0.65rem;
+      font-weight: 700;
+      letter-spacing: 0.12em;
+      text-transform: uppercase;
+      margin-bottom: 6px;
+      opacity: 0.7;
+    }
+
+    .layer-title {
+      font-size: 1rem;
+      font-weight: 600;
+      margin-bottom: 4px;
+    }
+
+    .layer-file {
+      font-size: 0.72rem;
+      font-family: 'Cascadia Code', 'Fira Code', monospace;
+      opacity: 0.55;
+      margin-bottom: 10px;
+    }
+
+    .layer-body {
+      font-size: 0.82rem;
+      line-height: 1.6;
+      color: #cbd5e1;
+    }
+
+    .layer-body code {
+      font-family: 'Cascadia Code', 'Fira Code', monospace;
+      background: rgba(255,255,255,0.07);
+      padding: 1px 5px;
+      border-radius: 4px;
+      font-size: 0.78rem;
+    }
+
+    /* ── Colour themes ── */
+    .c-frontend  { background: #1e1b4b; border: 1px solid #4338ca; }
+    .c-frontend .layer-label  { color: #818cf8; }
+    .c-frontend .layer-title  { color: #a5b4fc; }
+
+    .c-api       { background: #1a2035; border: 1px solid #2563eb; }
+    .c-api .layer-label       { color: #60a5fa; }
+    .c-api .layer-title       { color: #93c5fd; }
+
+    .c-rag       { background: #1e2a1e; border: 1px solid #16a34a; }
+    .c-rag .layer-label       { color: #4ade80; }
+    .c-rag .layer-title       { color: #86efac; }
+
+    .c-ai        { background: #2a1f2e; border: 1px solid #9333ea; }
+    .c-ai .layer-label        { color: #c084fc; }
+    .c-ai .layer-title        { color: #d8b4fe; }
+
+    .c-tool      { background: #2a2010; border: 1px solid #d97706; }
+    .c-tool .layer-label      { color: #fbbf24; }
+    .c-tool .layer-title      { color: #fde68a; }
+
+    .c-vector    { background: #1a2535; border: 1px solid #0891b2; }
+    .c-vector .layer-label    { color: #22d3ee; }
+    .c-vector .layer-title    { color: #67e8f9; }
+
+    .c-session   { background: #251a1a; border: 1px solid #dc2626; }
+    .c-session .layer-label   { color: #f87171; }
+    .c-session .layer-title   { color: #fca5a5; }
+
+    /* ── Arrows ── */
+    .arrow {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      gap: 2px;
+      margin: 2px 0;
+    }
+
+    .arrow-line {
+      width: 2px;
+      height: 20px;
+      background: linear-gradient(to bottom, #475569, #334155);
+    }
+
+    .arrow-head {
+      width: 0;
+      height: 0;
+      border-left: 7px solid transparent;
+      border-right: 7px solid transparent;
+      border-top: 10px solid #475569;
+    }
+
+    .arrow-label {
+      font-size: 0.68rem;
+      color: #64748b;
+      font-family: monospace;
+      background: #0f1117;
+      padding: 1px 8px;
+      border-radius: 20px;
+      border: 1px solid #1e293b;
+      margin-top: -2px;
+      margin-bottom: 2px;
+      white-space: nowrap;
+    }
+
+    /* ── Tool branch (side-by-side sub-flow) ── */
+    .branch-wrapper {
+      width: 100%;
+      display: flex;
+      gap: 16px;
+      align-items: stretch;
+    }
+
+    .branch-spine {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      width: 2px;
+      flex-shrink: 0;
+    }
+
+    .branch-spine-line {
+      flex: 1;
+      width: 2px;
+      background: #9333ea44;
+    }
+
+    .branch-content {
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+      gap: 0;
+    }
+
+    /* ── Inline tags ── */
+    .tag {
+      display: inline-block;
+      font-size: 0.68rem;
+      font-weight: 600;
+      padding: 1px 7px;
+      border-radius: 20px;
+      margin-right: 4px;
+      vertical-align: middle;
+    }
+    .tag-round1  { background: #312e81; color: #a5b4fc; }
+    .tag-round2  { background: #2d1b4e; color: #c084fc; }
+    .tag-opt     { background: #3f2a00; color: #fde68a; }
+    .tag-result  { background: #0c3321; color: #86efac; }
+
+    /* ── Two-col items ── */
+    .cols {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 10px;
+      margin-top: 10px;
+    }
+    .col-item {
+      background: rgba(255,255,255,0.04);
+      border-radius: 8px;
+      padding: 10px 12px;
+      font-size: 0.78rem;
+      line-height: 1.5;
+      color: #94a3b8;
+    }
+    .col-item strong {
+      display: block;
+      color: #e2e8f0;
+      font-size: 0.8rem;
+      margin-bottom: 3px;
+    }
+
+    /* ── Chroma badge ── */
+    .chroma-badge {
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      background: #0c2231;
+      border: 1px solid #0e7490;
+      border-radius: 6px;
+      padding: 4px 10px;
+      font-size: 0.75rem;
+      color: #67e8f9;
+      margin-top: 6px;
+      margin-right: 8px;
+    }
+    .chroma-dot {
+      width: 7px; height: 7px;
+      border-radius: 50%;
+      background: #22d3ee;
+    }
+
+    /* ── Return path ── */
+    .return-arrow {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      gap: 10px;
+      margin: 4px 0;
+      color: #64748b;
+      font-size: 0.72rem;
+      font-family: monospace;
+    }
+    .return-line {
+      flex: 1;
+      height: 1px;
+      background: linear-gradient(to right, transparent, #334155, transparent);
+    }
+
+    /* ── Legend ── */
+    .legend {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 10px;
+      justify-content: center;
+      margin-top: 48px;
+      padding-top: 24px;
+      border-top: 1px solid #1e293b;
+    }
+    .legend-item {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      font-size: 0.73rem;
+      color: #94a3b8;
+    }
+    .legend-dot {
+      width: 10px; height: 10px;
+      border-radius: 3px;
+    }
+  </style>
+</head>
+<body>
+
+<h1>RAG Chatbot — Code Flow</h1>
+<p class="subtitle">From user input to final answer</p>
+
+<div class="flow">
+
+  <!-- 1. FRONTEND -->
+  <div class="layer c-frontend">
+    <div class="layer-label">Layer 1 · Browser</div>
+    <div class="layer-title">Frontend</div>
+    <div class="layer-file">frontend/script.js · sendMessage()</div>
+    <div class="layer-body">
+      User types a question and presses Enter or clicks Send.<br>
+      Calls <code>POST /api/query</code> with <code>{ query, session_id }</code>.
+    </div>
+  </div>
+
+  <div class="arrow">
+    <div class="arrow-line"></div>
+    <div class="arrow-label">POST /api/query · JSON</div>
+    <div class="arrow-line"></div>
+    <div class="arrow-head"></div>
+  </div>
+
+  <!-- 2. FASTAPI -->
+  <div class="layer c-api">
+    <div class="layer-label">Layer 2 · HTTP</div>
+    <div class="layer-title">FastAPI Endpoint</div>
+    <div class="layer-file">backend/app.py:57 · query_documents()</div>
+    <div class="layer-body">
+      Creates a new session via <code>SessionManager</code> if none supplied.<br>
+      Delegates to <code>rag_system.query(query, session_id)</code>.
+    </div>
+  </div>
+
+  <div class="arrow">
+    <div class="arrow-line"></div>
+    <div class="arrow-label">rag_system.query()</div>
+    <div class="arrow-line"></div>
+    <div class="arrow-head"></div>
+  </div>
+
+  <!-- 3. RAG SYSTEM -->
+  <div class="layer c-rag">
+    <div class="layer-label">Layer 3 · Orchestrator</div>
+    <div class="layer-title">RAGSystem</div>
+    <div class="layer-file">backend/rag_system.py:102 · query()</div>
+    <div class="layer-body">
+      Wraps query → <code>"Answer this question about course materials: {query}"</code><br>
+      Loads conversation history from <code>SessionManager</code>.<br>
+      Calls <code>AIGenerator.generate_response(query, history, tools)</code>.
+    </div>
+  </div>
+
+  <div class="arrow">
+    <div class="arrow-line"></div>
+    <div class="arrow-label">generate_response()</div>
+    <div class="arrow-line"></div>
+    <div class="arrow-head"></div>
+  </div>
+
+  <!-- 4. AI GENERATOR -->
+  <div class="layer c-ai">
+    <div class="layer-label">Layer 4 · LLM</div>
+    <div class="layer-title">AIGenerator — Round 1</div>
+    <div class="layer-file">backend/ai_generator.py:43 · generate_response()</div>
+    <div class="layer-body">
+      <span class="tag tag-round1">Round 1</span> Sends to Claude API:<br>
+      &nbsp;&nbsp;• System prompt + conversation history<br>
+      &nbsp;&nbsp;• User query + tool definition <code>search_course_content</code><br><br>
+      <strong style="color:#d8b4fe">Two possible outcomes:</strong>
+      <div class="cols">
+        <div class="col-item">
+          <strong>General question</strong>
+          Claude answers directly — no tool call.<br>
+          <code>stop_reason = "end_turn"</code>
+        </div>
+        <div class="col-item">
+          <strong>Course-specific question</strong>
+          Claude calls the search tool.<br>
+          <code>stop_reason = "tool_use"</code>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <div class="arrow">
+    <div class="arrow-line"></div>
+    <div class="arrow-label">stop_reason == "tool_use"  →  _handle_tool_execution()</div>
+    <div class="arrow-line"></div>
+    <div class="arrow-head"></div>
+  </div>
+
+  <!-- 5. TOOL MANAGER -->
+  <div class="layer c-tool">
+    <div class="layer-label">Layer 5 · Tools</div>
+    <div class="layer-title">ToolManager → CourseSearchTool</div>
+    <div class="layer-file">backend/search_tools.py:116 · execute_tool() → CourseSearchTool.execute()</div>
+    <div class="layer-body">
+      <span class="tag tag-opt">optional</span> Only runs when Claude requests it.<br><br>
+      Receives <code>{ query, course_name?, lesson_number? }</code> from Claude.<br>
+      Calls <code>VectorStore.search()</code> and formats results as context string.<br>
+      Stores source labels (<em>course title + lesson number</em>) for the UI.
+    </div>
+  </div>
+
+  <div class="arrow">
+    <div class="arrow-line"></div>
+    <div class="arrow-label">vector_store.search()</div>
+    <div class="arrow-line"></div>
+    <div class="arrow-head"></div>
+  </div>
+
+  <!-- 6. VECTOR STORE -->
+  <div class="layer c-vector">
+    <div class="layer-label">Layer 6 · Retrieval</div>
+    <div class="layer-title">VectorStore (ChromaDB)</div>
+    <div class="layer-file">backend/vector_store.py:61 · search()</div>
+    <div class="layer-body">
+      <strong style="color:#67e8f9">Two-stage lookup:</strong>
+      <div class="cols">
+        <div class="col-item">
+          <strong>① Course resolution</strong>
+          Semantic search on <code>course_catalog</code> collection to match fuzzy course names.
+        </div>
+        <div class="col-item">
+          <strong>② Content retrieval</strong>
+          Embedding similarity search on <code>course_content</code> collection with optional filters.
+        </div>
+      </div>
+      <div style="margin-top:10px">
+        <span class="chroma-badge"><span class="chroma-dot"></span>course_catalog</span>
+        <span class="chroma-badge"><span class="chroma-dot"></span>course_content</span>
+      </div>
+      <div style="margin-top:8px;font-size:0.78rem;color:#94a3b8">
+        Returns ranked <code>documents[]</code> + <code>metadata[]</code> (course title, lesson number).
+      </div>
+    </div>
+  </div>
+
+  <!-- Return arrows upward -->
+  <div class="arrow">
+    <div class="arrow-line"></div>
+    <div class="arrow-label">formatted context string</div>
+    <div class="arrow-line"></div>
+    <div class="arrow-head"></div>
+  </div>
+
+  <!-- 7. AI Round 2 -->
+  <div class="layer c-ai">
+    <div class="layer-label">Layer 4 · LLM (continued)</div>
+    <div class="layer-title">AIGenerator — Round 2</div>
+    <div class="layer-file">backend/ai_generator.py:89 · _handle_tool_execution()</div>
+    <div class="layer-body">
+      <span class="tag tag-round2">Round 2</span> Sends follow-up to Claude API:<br>
+      &nbsp;&nbsp;• Full message thread: <code>[user_query → tool_use → tool_result]</code><br>
+      &nbsp;&nbsp;• No tools offered — Claude synthesises the answer.<br><br>
+      Returns final answer text.
+    </div>
+  </div>
+
+  <div class="arrow">
+    <div class="arrow-line"></div>
+    <div class="arrow-label">answer text</div>
+    <div class="arrow-line"></div>
+    <div class="arrow-head"></div>
+  </div>
+
+  <!-- 8. SESSION MANAGER -->
+  <div class="layer c-session">
+    <div class="layer-label">Layer 7 · Memory</div>
+    <div class="layer-title">SessionManager</div>
+    <div class="layer-file">backend/session_manager.py:37 · add_exchange()</div>
+    <div class="layer-body">
+      Appends <code>(user_query, assistant_answer)</code> to in-memory session history.<br>
+      Trims to last <code>MAX_HISTORY × 2</code> messages to stay within context budget.<br>
+      History injected as plain text into system prompt on the next turn.
+    </div>
+  </div>
+
+  <div class="arrow">
+    <div class="arrow-line"></div>
+    <div class="arrow-label">{ answer, sources, session_id }</div>
+    <div class="arrow-line"></div>
+    <div class="arrow-head"></div>
+  </div>
+
+  <!-- 9. RESPONSE -->
+  <div class="layer c-frontend">
+    <div class="layer-label">Layer 1 · Browser (response)</div>
+    <div class="layer-title">Frontend — Render Answer</div>
+    <div class="layer-file">frontend/script.js · addMessage()</div>
+    <div class="layer-body">
+      <span class="tag tag-result">Done</span>
+      Displays the answer in the chat bubble.<br>
+      Shows source chips (<em>Course name · Lesson N</em>) below the answer.<br>
+      Stores <code>session_id</code> locally for the next message.
+    </div>
+  </div>
+
+</div><!-- /flow -->
+
+<!-- Legend -->
+<div class="legend">
+  <div class="legend-item"><span class="legend-dot" style="background:#4338ca"></span>Frontend</div>
+  <div class="legend-item"><span class="legend-dot" style="background:#2563eb"></span>FastAPI</div>
+  <div class="legend-item"><span class="legend-dot" style="background:#16a34a"></span>RAG Orchestrator</div>
+  <div class="legend-item"><span class="legend-dot" style="background:#9333ea"></span>AI Generator (Claude)</div>
+  <div class="legend-item"><span class="legend-dot" style="background:#d97706"></span>Tool Layer</div>
+  <div class="legend-item"><span class="legend-dot" style="background:#0891b2"></span>Vector Store (ChromaDB)</div>
+  <div class="legend-item"><span class="legend-dot" style="background:#dc2626"></span>Session Memory</div>
+</div>
+
+</body>
+</html>