+
+
📚 Architecture Components Overview
+
+
+
🎨 Frontend Layer
+
+ - Technology: Vanilla HTML5/CSS3/JavaScript
+ - Pages: Single-page chat interface
+ - Components: Message rendering, loading states
+ - Libraries: Marked.js for Markdown
+ - State: Session-based conversation tracking
+
+
+
+
+
🔌 API Layer
+
+ - Framework: FastAPI with Uvicorn ASGI
+ - Endpoints: /api/query, /api/courses
+ - Sessions: In-memory with 2 exchange limit
+ - CORS: Enabled for development
+ - Serving: Static files + API unified
+
+
+
+
+
🤖 RAG/AI Layer
+
+ - AI Model: Anthropic Claude Sonnet 4
+ - RAG Core: Query orchestration & ingestion
+ - Tools: CourseSearchTool with semantic search
+ - Config: Temperature 0, max 800 tokens
+ - Features: Tool calling, source tracking
+
+
+
+
+
💾 Database/Storage Layer
+
+ - Vector DB: ChromaDB (persistent)
+ - Collections: course_catalog, course_content
+ - Embeddings: Sentence Transformers (all-MiniLM-L6-v2)
+ - Chunking: 800 chars with 100 overlap
+ - Files: Structured .txt course documents
+
+
+
+
+
+
+
+graph TB
+ User([👤 User])
+
+ subgraph Layer1["🎨 FRONTEND LAYER - Vanilla HTML/CSS/JavaScript"]
+ direction LR
+ FE1["📄 Static Pages
• index.html
• Chat Interface
• Statistics Panel"]
+ FE2["🧩 UI Components
• Message Renderer
• Loading States
• Event Handlers"]
+ FE3["⚡ Utilities
• Marked.js
• Fetch Client
• Session Mgmt"]
+
+ FE1 -.-> FE2 -.-> FE3
+ end
+
+ subgraph Layer2["🔌 API LAYER - FastAPI + Uvicorn"]
+ direction LR
+ API1["📡 FastAPI Endpoints
• POST /api/query
• GET /api/courses
• Static serving
• CORS enabled"]
+ API2["📝 Session Manager
• In-memory sessions
• 2 exchange limit
• Context formatting"]
+
+ API1 -.-> API2
+ end
+
+ subgraph Layer3["🤖 RAG/AI LAYER - Anthropic Claude + Tools"]
+ direction LR
+ RAG1["🔄 RAG System
• Query orchestration
• Doc ingestion
• Analytics"]
+ RAG2["🧠 AI Generator
• Claude Sonnet 4
• Tool calling
• Temp: 0"]
+ RAG3["🔧 Tools
• CourseSearchTool
• ToolManager
• Source tracking"]
+
+ RAG1 -.-> RAG2 -.-> RAG3
+ end
+
+ subgraph Layer4["💾 DATABASE/STORAGE LAYER - ChromaDB + File System"]
+ direction LR
+ DB1["📊 Vector Store
• ChromaDB
• course_catalog
• course_content"]
+ DB2["📥 Doc Processor
• 800 char chunks
• 100 char overlap
• Metadata extract"]
+ DB3["📁 File Storage
• /docs folder
• .txt files
• UTF-8"]
+
+ DB2 -.-> DB3
+ DB2 -.-> DB1
+ end
+
+ %% Force vertical layout by creating explicit path
+ User --> Layer1
+ Layer1 --> Layer2
+ Layer2 --> Layer3
+ Layer3 --> Layer4
+
+ %% Styling
+ classDef frontendStyle fill:#e3f2fd,stroke:#1976d2,stroke-width:4px,color:#000
+ classDef apiStyle fill:#fff3e0,stroke:#f57c00,stroke-width:4px,color:#000
+ classDef ragStyle fill:#e8f5e9,stroke:#388e3c,stroke-width:4px,color:#000
+ classDef databaseStyle fill:#f3e5f5,stroke:#7b1fa2,stroke-width:4px,color:#000
+
+ class Layer1 frontendStyle
+ class Layer2 apiStyle
+ class Layer3 ragStyle
+ class Layer4 databaseStyle
+
+
+
+
+
🔄 Sequence Flow Breakdown
+
+
+
1-3: User Interaction
+
+ - User types question in chat interface
+ - Frontend shows loading state
+ - POST request sent to /api/query endpoint
+
+
+
+
+
4-6: Session & Context
+
+ - API retrieves conversation history from Session Manager
+ - Last 2 exchanges loaded for context
+ - Query passed to RAG System with context
+
+
+
+
+
7-16: RAG Processing
+
+ - RAG formats message and sends to Claude AI
+ - AI analyzes query and decides to use search tool
+ - CourseSearchTool executes semantic vector search
+ - ChromaDB returns relevant chunks with metadata
+ - AI generates answer based on retrieved context
+
+
+
+
+
17-21: Response & Display
+
+ - Exchange saved to session (user msg + AI response)
+ - Session limited to 2 most recent exchanges
+ - Response sent back through API to frontend
+ - Frontend renders Markdown answer
+ - Sources displayed in collapsible section
+
+
+
+
+
+
+
+sequenceDiagram
+ autonumber
+ actor User
+ participant FE as 🎨 Frontend
+ participant API as 🔌 API Layer
+ participant Session as 📝 Session Mgr
+ participant RAG as 🤖 RAG System
+ participant AI as 🧠 Claude AI
+ participant Tools as 🔧 Search Tools
+ participant DB as 💾 Vector DB
+
+ Note over User,DB: Core User Query Flow
+
+ %% User submits query
+ User->>+FE: Type question and click send
+ FE->>FE: Show loading state
+ FE->>+API: POST /api/query
+
+ %% Session management
+ API->>+Session: Get conversation history
+ Session-->>-API: Return last 2 exchanges
+
+ %% RAG processing
+ API->>+RAG: Process query with context
+ RAG->>RAG: Format user message
+
+ %% AI decides to search
+ RAG->>+AI: Send message with tool definitions
+ AI->>AI: Analyze query
+ AI-->>-RAG: Tool call: CourseSearchTool
+
+ %% Tool execution
+ RAG->>+Tools: Execute search tool
+ Tools->>+DB: Semantic vector search
+ DB->>DB: Find similar chunks
+ DB-->>-Tools: Return chunks and metadata
+ Tools-->>-RAG: Format search results
+
+ %% AI generates response
+ RAG->>+AI: Send tool results
+ AI->>AI: Generate answer (temp: 0)
+ AI-->>-RAG: Response text
+
+ %% Save to session
+ RAG->>+Session: Save exchange
+ Session->>Session: Limit to 2 exchanges
+ Session-->>-RAG: Confirmed
+
+ %% Return to frontend
+ RAG-->>-API: Return answer and sources
+ API-->>-FE: JSON response
+ FE->>FE: Render markdown answer
+ FE->>FE: Display sources
+ FE-->>-User: Show AI response
+
+ Note over User,DB: User sees answer with course sources
+
+
+
+
+
🤖 RAG & Storage Components Overview
+
+
+
🤖 RAG/AI Layer
+
+ - RAG System: Main orchestrator coordinating AI, tools, and sessions
+ - AI Generator: Claude Sonnet 4 with tool calling capability
+ - Tool Manager: Registry and executor for search tools
+ - Course Search Tool: Semantic search with course/lesson filtering
+ - Session Manager: In-memory conversation state (2 exchanges max)
+
+
+
+
+
💾 Storage Layer
+
+ - ChromaDB Client: Persistent vector database with sentence transformers
+ - Course Catalog Collection: Metadata (titles, instructors, links)
+ - Course Content Collection: Chunked text with lesson mapping
+ - Document Processor: Parses files and creates chunks
+ - Chunking Strategy: 800 chars + 100 overlap, sentence-aware
+
+
+
+
+
📋 File Mappings
+
+ - rag_system.py: Main RAG orchestration logic
+ - ai_generator.py: Claude API integration
+ - search_tools.py: Tool framework and CourseSearchTool
+ - vector_store.py: ChromaDB client and operations
+ - document_processor.py: File parsing and chunking
+ - session_manager.py: Conversation state management
+
+
+
+
+
🔄 Internal Data Flows
+
+ - Orchestration: RAG System coordinates all components
+ - AI Invocation: AI Generator can autonomously invoke search tools
+ - Tool Execution: Search Tool queries vector database
+ - Document Pipeline: Files → Processor → Chunks → ChromaDB
+ - Cross-Layer: Search tools bridge RAG and Storage layers
+
+
+
+
+
+
+
+flowchart TB
+ RAG1[🔄 RAG System]
+ RAG2[🧠 AI Generator]
+ RAG3[🛠️ Tool Manager]
+ RAG4[🔍 Course Search]
+ RAG5[📝 Session Manager]
+
+ ST1[🗄️ ChromaDB]
+ ST2[📚 course_catalog]
+ ST3[📄 course_content]
+ ST4[📥 Doc Processor]
+ ST5[✂️ Chunking]
+ ST6[📁 /docs]
+
+ RAG1 --> RAG2
+ RAG1 --> RAG3
+ RAG1 --> RAG5
+ RAG3 --> RAG4
+ RAG2 -.-> RAG4
+
+ ST6 --> ST4
+ ST4 --> ST5
+ ST5 --> ST1
+ ST1 --> ST2
+ ST1 --> ST3
+
+ RAG4 --> ST1
+
+ style RAG1 fill:#e8f5e9,stroke:#388e3c
+ style RAG2 fill:#e8f5e9,stroke:#388e3c
+ style RAG3 fill:#e8f5e9,stroke:#388e3c
+ style RAG4 fill:#e8f5e9,stroke:#388e3c
+ style RAG5 fill:#e8f5e9,stroke:#388e3c
+ style ST1 fill:#f3e5f5,stroke:#7b1fa2
+ style ST2 fill:#f3e5f5,stroke:#7b1fa2
+ style ST3 fill:#f3e5f5,stroke:#7b1fa2
+ style ST4 fill:#f3e5f5,stroke:#7b1fa2
+ style ST5 fill:#f3e5f5,stroke:#7b1fa2
+ style ST6 fill:#f3e5f5,stroke:#7b1fa2
+
+
+
+
+
🔬 RAG Processing Flow Breakdown
+
+
+
Steps 1-4: Request & Context Loading
+
+ - User submits question through chat interface
+ - Frontend sends POST request to FastAPI with session_id and message
+ - RAG System retrieves conversation history (last 2 exchanges)
+ - Provides context continuity for follow-up questions
+
+
+
+
+
Steps 5-6: AI Decision Point
+
+ - RAG sends user message with available tool definitions to Claude
+ - AI analyzes query to determine if vector search is needed
+ - Decision Logic: Search for course content vs. general conversation
+ - AI has autonomy to skip search for greetings, clarifications, etc.
+
+
+
+
+
Steps 7-13: Search Path (Conditional)
+
+ - Course Resolution: Fuzzy match course name to course_id
+ - Vector Search: Generate embeddings and find similar chunks
+ - Metadata Filtering: Apply course_id and lesson_id filters
+ - Context Generation: AI receives chunks to ground response
+ - Source Tracking: Each chunk includes origin metadata
+
+
+
+
+
Steps 14-17: Response & Session Management
+
+ - RAG saves complete exchange (user message + AI response) to session
+ - Session kept to 2 most recent exchanges (FIFO eviction)
+ - Response with sources sent back through API to frontend
+ - Frontend renders markdown answer and displays collapsible sources
+
+
+
+
+
+
+
RAG Processing Flow (Mid-Level Detail)
+
+sequenceDiagram
+ autonumber
+ participant User
+ participant Frontend as 🎨 Frontend
+ participant API as 🔌 FastAPI
+ participant RAG as 🤖 RAG System
+ participant AI as 🧠 Claude AI
+ participant Vector as 💾 Vector Store
+
+ Note over User,Vector: Mid-Level RAG Processing Flow
+
+ %% Request phase
+ User->>Frontend: Submit question
+ Frontend->>API: POST /api/query {session_id, message}
+
+ %% Context gathering
+ API->>RAG: Process query
+ RAG->>RAG: Load last 2 conversation exchanges
+
+ %% AI decision making
+ RAG->>AI: Send message + tool definitions
+ AI->>AI: Analyze: Does this need search?
+
+ alt Query needs search
+ AI->>RAG: Tool call: search(query, course, lesson)
+
+ %% Search execution
+ RAG->>Vector: Resolve course name (if provided)
+ Vector-->>RAG: Matched course_id
+
+ RAG->>Vector: Semantic search with filters
+ Vector->>Vector: Generate embeddings + similarity search
+ Vector-->>RAG: Top relevant chunks + metadata
+
+ %% Final generation with context
+ RAG->>AI: Generate answer with search results
+ AI-->>RAG: Response with sources
+ else No search needed
+ AI-->>RAG: Direct response
+ end
+
+ %% Save and return
+ RAG->>RAG: Save exchange to session (keep last 2)
+ RAG-->>API: Answer + sources
+ API-->>Frontend: JSON response
+ Frontend->>Frontend: Render markdown + sources
+ Frontend-->>User: Display AI answer
+
+ Note over User,Vector: Complete response with context
+
+
+
+
+
🎯 Key Technical Details
+
+
+
🔍 Search Mechanics
+
+ - Two-Stage Search: First resolves course name, then searches content
+ - Fuzzy Course Matching: Uses embeddings to find closest course name
+ - Metadata Filtering: Applies course_id and lesson_id filters
+ - Semantic Similarity: Cosine distance on vector embeddings
+ - Top-K Results: Returns most relevant chunks with sources
+
+
+
+
+
📦 Data Structures
+
+ - Course Chunk: {text, course_id, lesson_id, chunk_index}
+ - Metadata: Extracted from structured .txt files
+ - Embeddings: 384-dimensional vectors (MiniLM-L6-v2)
+ - Collections: Separate indexes for catalog and content
+ - Persistence: Stored in ./backend/chroma_db/ directory
+
+
+
+
+
⚙️ Processing Pipeline
+
+ - Document Ingestion: Read → Parse → Chunk → Embed → Store
+ - Query Flow: Format → AI Analyze → Tool Call → Search → Generate
+ - Session Context: Included in every AI request for continuity
+ - Tool Decision: AI autonomously decides when to search
+ - Source Tracking: Every chunk includes origin metadata
+
+
+
+
+
🧮 Configuration
+
+ - Chunk Size: 800 characters (sentence-aware splitting)
+ - Chunk Overlap: 100 characters to preserve context
+ - Temperature: 0 (deterministic AI responses)
+ - Max Tokens: 800 per response
+ - Session Limit: 2 exchanges (cost optimization)
+ - Embedding Model: sentence-transformers/all-MiniLM-L6-v2
+
+
+
+
+