diagram.mmd

sequenceDiagram
    participant U as User
    participant App as app.py
    participant UI as ui/app.py
    participant OH as objective_handlers.py
    participant QH as question_handlers.py
    participant FH as feedback_handlers.py
    participant CP as ContentProcessor
    participant QG as QuizGenerator
    participant State as state.py
    participant OpenAI as OpenAI API

    Note over U, OpenAI: Application Startup
    U->>App: python app.py
    App->>App: load_dotenv()
    App->>App: Check OPENAI_API_KEY
    App->>UI: create_ui()
    UI->>UI: Create Gradio interface with 3 tabs
    UI->>U: Launch web interface at http://127.0.0.1:7860

    Note over U, OpenAI: Tab 1: Generate Learning Objectives
    U->>UI: Upload files (.vtt, .srt, .ipynb)
    U->>UI: Set parameters (objectives, runs, model, temperature)
    U->>UI: Click "Generate Learning Objectives"
    
    UI->>OH: process_files(files, params)
    OH->>OH: _extract_file_paths(files)
    OH->>CP: process_files(file_paths)
    CP->>OH: file_contents (with XML tags)
    OH->>State: set_processed_contents(file_contents)
    
    OH->>QG: QuizGenerator(api_key, model, temperature)
    OH->>OH: _generate_multiple_runs()
    loop For each run
        OH->>QG: generate_base_learning_objectives()
        QG->>OpenAI: API call for objectives
        OpenAI->>QG: Base learning objectives
    end
    
    OH->>OH: _group_base_objectives_add_incorrect_answers()
    OH->>QG: group_base_learning_objectives()
    QG->>OpenAI: API call for grouping/ranking
    OpenAI->>QG: Grouped objectives
    OH->>QG: generate_lo_incorrect_answer_options()
    QG->>OpenAI: API call for incorrect answers
    OpenAI->>QG: Enhanced objectives
    
    OH->>State: set_learning_objectives(grouped_result)
    OH->>OH: _format_objective_results()
    OH->>UI: Return formatted results
    UI->>U: Display objectives in 3 text boxes

    Note over U, OpenAI: Tab 2: Generate Questions
    U->>UI: Review objectives JSON (auto-populated)
    U->>UI: Set question generation parameters
    U->>UI: Click "Generate Questions"
    
    UI->>QH: generate_questions(objectives_json, params)
    QH->>QH: _parse_learning_objectives(objectives_json)
    QH->>State: get_processed_contents()
    QH->>QG: QuizGenerator(api_key, model, temperature)
    
    QH->>QH: _generate_questions_multiple_runs()
    loop For each run
        QH->>QG: generate_questions_in_parallel()
        QG->>OpenAI: API calls for questions
        OpenAI->>QG: Multiple choice questions
    end
    
    QH->>QH: _group_and_rank_questions()
    QH->>QG: group_questions()
    QG->>OpenAI: API call for grouping
    OpenAI->>QG: Grouped questions
    QH->>QG: rank_questions()
    QG->>OpenAI: API call for ranking
    OpenAI->>QG: Ranked questions
    
    QH->>QH: _format_question_results()
    QH->>UI: Return formatted quiz results
    UI->>U: Display questions and formatted quiz

    Note over U, OpenAI: Tab 3: Propose/Edit Question
    U->>UI: Enter question guidance/feedback
    U->>UI: Set model parameters
    U->>UI: Click "Generate Question"
    
    UI->>FH: propose_question_handler(guidance, params)
    FH->>State: get_processed_contents()
    FH->>QG: QuizGenerator(api_key, model, temperature)
    FH->>QG: generate_multiple_choice_question_from_feedback()
    QG->>OpenAI: API call with feedback
    OpenAI->>QG: Single question
    FH->>UI: Return formatted question JSON
    UI->>U: Display generated question

    Note over U, OpenAI: Optional: Regenerate Objectives
    U->>UI: Provide feedback on objectives
    U->>UI: Click "Regenerate Learning Objectives"
    UI->>OH: regenerate_objectives(objectives, feedback, params)
    OH->>State: get_processed_contents()
    OH->>OH: Add feedback to file_contents
    OH->>QG: Generate with feedback context
    QG->>OpenAI: API calls with feedback
    OpenAI->>QG: Improved objectives
    OH->>UI: Return regenerated objectives
    UI->>U: Display updated objectives