sequenceDiagram
    participant User
    participant Frontend as Frontend<br/>(script.js)
    participant API as FastAPI<br/>(app.py)
    participant RAG as RAG System<br/>(rag_system.py)
    participant AI as AI Generator<br/>(ai_generator.py)
    participant Tools as Search Tools<br/>(search_tools.py)
    participant Vector as Vector Store<br/>(vector_store.py)
    participant Claude as Anthropic<br/>Claude API

    User->>Frontend: Types query & clicks send
    Frontend->>Frontend: Disable input, show loading
    Frontend->>API: POST /api/query<br/>{query, session_id}
    
    API->>RAG: rag_system.query(query, session_id)
    RAG->>RAG: Create prompt:<br/>"Answer this question about course materials: {query}"
    RAG->>RAG: Get conversation history from session
    
    RAG->>AI: generate_response(query, history, tools, tool_manager)
    AI->>AI: Build system prompt + context
    AI->>Claude: API call with tools enabled
    
    Note over Claude: Claude decides if search is needed
    Claude-->>AI: Response with tool_use (search request)
    
    AI->>AI: _handle_tool_execution()
    AI->>Tools: execute_tool("search_course_content", query, filters)
    Tools->>Vector: search(query, course_name, lesson_number)
    Vector->>Vector: ChromaDB semantic search
    Vector-->>Tools: Search results with metadata
    Tools->>Tools: Format results with course/lesson context
    Tools-->>AI: Formatted search results
    
    AI->>Claude: Follow-up API call with search results
    Claude-->>AI: Final response synthesizing search results
    AI-->>RAG: Generated response
    
    RAG->>RAG: Get sources from tool_manager
    RAG->>RAG: Update session history
    RAG-->>API: (response, sources)
    
    API-->>Frontend: QueryResponse<br/>{answer, sources, session_id}
    Frontend->>Frontend: Remove loading, display response
    Frontend->>User: Shows AI response + source citations