┌─────────────────────────────────────────────────────────────────────────────────┐
│                                 FRONTEND                                        │
├─────────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐    1. User Input     ┌──────────────────────────────────┐  │
│  │   Chat Input    │ ──────────────────► │        sendMessage()             │  │
│  │  "What is MCP?" │                     │   - Disable input                │  │
│  └─────────────────┘                     │   - Add user message to chat    │  │
│                                          │   - Show loading spinner         │  │
│                                          └──────────────────────────────────┘  │
│                                                          │                     │
│                                          2. HTTP POST    │                     │
│                                             /api/query   │                     │
└─────────────────────────────────────────────────────────┼─────────────────────┘
                                                          │
┌─────────────────────────────────────────────────────────┼─────────────────────┐
│                              FASTAPI SERVER             │                     │
├─────────────────────────────────────────────────────────┼─────────────────────┤
│  ┌──────────────────────────────────────────────────────▼──────────────────┐  │
│  │                    @app.post("/api/query")                              │  │
│  │  - Extract query & session_id                                          │  │
│  │  - Create session if needed                                            │  │
│  │  - Call rag_system.query()                                             │  │
│  │  - Return QueryResponse(answer, sources, session_id)                   │  │
│  └─────────────────────────────────────────────────────────────────────────┘  │
│                                          │                                     │
│                              3. Process  │                                     │
└─────────────────────────────────────────┼─────────────────────────────────────┘
                                          │
┌─────────────────────────────────────────┼─────────────────────────────────────┐
│                        RAG SYSTEM       │                                     │
├─────────────────────────────────────────┼─────────────────────────────────────┤
│  ┌──────────────────────────────────────▼──────────────────────────────────┐  │
│  │                    rag_system.query()                                   │  │
│  │  4a. Get conversation history from SessionManager                       │  │
│  │  4b. Create prompt: "Answer this question about course materials: ..." │  │
│  │  4c. Call ai_generator.generate_response()                              │  │
│  │  4d. Extract sources from tool_manager                                  │  │
│  │  4e. Update conversation history                                        │  │
│  └─────────────────────────────────────────────────────────────────────────┘  │
│                                          │                                     │
│                              5. Generate │                                     │
└─────────────────────────────────────────┼─────────────────────────────────────┘
                                          │
┌─────────────────────────────────────────┼─────────────────────────────────────┐
│                      AI GENERATOR       │                                     │
├─────────────────────────────────────────┼─────────────────────────────────────┤
│  ┌──────────────────────────────────────▼──────────────────────────────────┐  │
│  │               generate_response()                                        │  │
│  │  6a. Build system prompt + conversation history                         │  │
│  │  6b. Call Claude API with tools enabled                                 │  │
│  │  ┌─────────────────────────────────────────────────────────────────┐   │  │
│  │  │            🤖 CLAUDE DECIDES TO USE TOOL                        │   │  │
│  │  │  "I should search for information about MCP"                   │   │  │
│  │  │  Tool: search_course_content                                    │   │  │
│  │  │  Parameters: {query: "MCP", course_name: null}                 │   │  │
│  │  └─────────────────────────────────────────────────────────────────┘   │  │
│  │  6c. Execute tool via tool_manager                                      │  │
│  └─────────────────────────────────────────────────────────────────────────┘  │
│                                          │                                     │
│                        7. Tool Execution │                                     │
└─────────────────────────────────────────┼─────────────────────────────────────┘
                                          │
┌─────────────────────────────────────────┼─────────────────────────────────────┐
│                    SEARCH TOOLS         │                                     │
├─────────────────────────────────────────┼─────────────────────────────────────┤
│  ┌──────────────────────────────────────▼──────────────────────────────────┐  │
│  │              CourseSearchTool.execute()                                 │  │
│  │  8a. Call vector_store.search(query="MCP")                              │  │
│  │  8b. Format results with course/lesson context                          │  │
│  │  8c. Store sources in last_sources for frontend                         │  │
│  └─────────────────────────────────────────────────────────────────────────┘  │
│                                          │                                     │
│                         9. Vector Search │                                     │
└─────────────────────────────────────────┼─────────────────────────────────────┘
                                          │
┌─────────────────────────────────────────┼─────────────────────────────────────┐
│                    VECTOR STORE         │                                     │
├─────────────────────────────────────────┼─────────────────────────────────────┤
│  ┌──────────────────────────────────────▼──────────────────────────────────┐  │
│  │                  vector_store.search()                                  │  │
│  │  10a. Resolve course name (if provided) via semantic search             │  │
│  │  10b. Build ChromaDB filter                                             │  │
│  │  10c. Query ChromaDB collections:                                       │  │
│  │       ┌─────────────────┐    ┌──────────────────────────────────────┐   │  │
│  │       │ course_catalog  │    │         course_content              │   │  │
│  │       │ - Course titles │    │ ┌────────────────────────────────┐   │   │  │
│  │       │ - Instructors   │    │ │ Chunk: "MCP (Model Context     │   │   │  │
│  │       │ - Metadata      │    │ │ Protocol) allows AI models..." │   │   │  │
│  │       └─────────────────┘    │ │ Metadata: {course: "Building   │   │   │  │
│  │                              │ │          Toward Computer Use", │   │   │  │
│  │                              │ │          lesson: 2}            │   │   │  │
│  │                              │ └────────────────────────────────┘   │   │  │
│  │                              └──────────────────────────────────────┘   │  │
│  │  10d. Return SearchResults with documents, metadata, distances          │  │
│  └─────────────────────────────────────────────────────────────────────────┘  │
│                                          │                                     │
└─────────────────────────────────────────┼─────────────────────────────────────┘
                                          │
                              ┌───────────┴───────────┐
                              │    RESULTS FLOW       │
                              │      BACKWARD         │
                              └───────────┬───────────┘
                                          │
┌─────────────────────────────────────────┼─────────────────────────────────────┐
│                      AI GENERATOR       │                                     │
├─────────────────────────────────────────┼─────────────────────────────────────┤
│  ┌──────────────────────────────────────▼──────────────────────────────────┐  │
│  │            _handle_tool_execution()                                      │  │
│  │  11a. Collect all tool results                                          │  │
│  │  11b. Send tool results back to Claude                                  │  │
│  │  ┌─────────────────────────────────────────────────────────────────┐   │  │
│  │  │        🤖 CLAUDE SYNTHESIZES FINAL RESPONSE                     │   │  │
│  │  │  "MCP (Model Context Protocol) is a communication standard..."  │   │  │
│  │  └─────────────────────────────────────────────────────────────────┘   │  │
│  │  11c. Return final response text                                        │  │
│  └─────────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────┼─────────────────────────────────────┘
                                          │
┌─────────────────────────────────────────┼─────────────────────────────────────┐
│                    SESSION MANAGER      │                                     │
├─────────────────────────────────────────┼─────────────────────────────────────┤
│  ┌──────────────────────────────────────▼──────────────────────────────────┐  │
│  │                add_exchange()                                            │  │
│  │  12. Store conversation:                                                 │  │
│  │      User: "What is MCP?"                                               │  │
│  │      Assistant: "MCP (Model Context Protocol) is..."                   │  │
│  └─────────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────┼─────────────────────────────────────┘
                                          │
┌─────────────────────────────────────────┼─────────────────────────────────────┐
│                        FASTAPI          │                                     │
├─────────────────────────────────────────┼─────────────────────────────────────┤
│  ┌──────────────────────────────────────▼──────────────────────────────────┐  │
│  │  13. Return JSON Response:                                               │  │
│  │      {                                                                   │  │
│  │        "answer": "MCP (Model Context Protocol) is...",                  │  │
│  │        "sources": ["Building Toward Computer Use - Lesson 2"],          │  │
│  │        "session_id": "session_1"                                        │  │
│  │      }                                                                   │  │
│  └─────────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────┼─────────────────────────────────────┘
                                          │
┌─────────────────────────────────────────┼─────────────────────────────────────┐
│                                 FRONTEND │                                     │
├─────────────────────────────────────────┼─────────────────────────────────────┤
│  ┌──────────────────────────────────────▼──────────────────────────────────┐  │
│  │  14. Process Response:                                                   │  │
│  │      - Remove loading spinner                                           │  │
│  │      - Add assistant message to chat with markdown formatting           │  │
│  │      - Show collapsible sources section                                 │  │
│  │      - Update session_id for future queries                             │  │
│  │      - Re-enable input and focus                                        │  │
│  └─────────────────────────────────────────────────────────────────────────┘  │
│                                                                               │
│  ┌───────────────────────────────────────────────────────────────────────┐   │
│  │                         CHAT DISPLAY                                 │   │
│  │  User: What is MCP?                                                   │   │
│  │  ┌─────────────────────────────────────────────────────────────────┐ │   │
│  │  │ Assistant: MCP (Model Context Protocol) is a communication     │ │   │
│  │  │ standard that enables AI applications to securely access...    │ │   │
│  │  │ ▼ Sources: Building Toward Computer Use - Lesson 2             │ │   │
│  │  └─────────────────────────────────────────────────────────────────┘ │   │
│  └───────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────────┘

KEY FEATURES:
• 🔄 Conversation Context: Session history maintained across queries
• 🤖 Smart Tool Usage: Claude autonomously decides when to search vs use general knowledge  
• 🔍 Semantic Search: ChromaDB vector similarity matching with SentenceTransformer embeddings
• 📚 Hierarchical Filtering: Course → Lesson → Chunk level search capabilities
• 🎯 Source Attribution: Search results tracked and displayed to user
• ⚡ Async Processing: Non-blocking frontend with loading states