graph TB
    subgraph cli_layer [CLI Layer]
        CLI[CLI Entry Point]
    end
    
    subgraph future [Future - Not in Scope]
        FastAPI[FastAPI Endpoint]
    end
    
    subgraph orchestration [Orchestration Layer]
        Orchestrator[Orchestrator]
        PlannerAgent[Planner Agent<br>ReAct Prompting]
        HITL[Human Review<br>Plan Approval]
    end
    
    subgraph agents_layer [Agent Layer]
        ResearchAgent[Research Agent]
        WriterAgent[Writer Agent]
        EditorAgent[Editor Agent]
    end
    
    subgraph tools_layer [Tools Layer]
        Tavily[Tavily Search<br>Primary Discovery]
        Wikipedia[Wikipedia Extractor<br>Conditional]
        ArXiv[ArXiv Extractor<br>Conditional]
    end
    
    subgraph output [Output]
        Report[Markdown Report]
    end
    
    CLI --> Orchestrator
    FastAPI -.->|Future| Orchestrator
    Orchestrator --> PlannerAgent
    PlannerAgent --> HITL
    HITL -->|Approved/Modified| ResearchAgent
    PlannerAgent --> WriterAgent
    ResearchAgent --> Tavily
    Tavily -->|Wikipedia links| Wikipedia
    Tavily -->|ArXiv/paper links| ArXiv
    WriterAgent --> EditorAgent
    EditorAgent -->|Feedback Loop| WriterAgent
    EditorAgent --> Report

flowchart TD
    Planner[Planner Agent] --> Plan[Research Plan]
    Plan --> Display[Display Plan to Human]
    Display --> Decision{Human Decision}
    Decision -->|Approve| Execute[Execute Plan]
    Decision -->|Modify| Edit[Human Edits Plan]
    Decision -->|Reject| Replan[Planner Tries Again]
    Edit --> Execute
    Replan --> Planner

flowchart LR
    subgraph discovery [Discovery Phase]
        Query[User Query] --> Tavily[Tavily Search]
    end
    
    subgraph enrichment [Enrichment Phase]
        Tavily --> LinkAnalyzer{Analyze URLs}
        LinkAnalyzer -->|arxiv.org links| ArXiv[ArXiv Extractor]
        LinkAnalyzer -->|wikipedia.org links| Wikipedia[Wikipedia Extractor]
        LinkAnalyzer -->|Other links| WebContent[Web Content]
    end
    
    subgraph aggregation [Aggregation]
        ArXiv --> Results[Research Findings]
        Wikipedia --> Results
        WebContent --> Results
    end

sequenceDiagram
    participant User
    participant Orchestrator
    participant Planner as PlannerAgent
    participant Human as Human Review
    participant Researcher as ResearchAgent
    participant Writer as WriterAgent
    participant Editor as EditorAgent
    
    User->>Orchestrator: Submit question
    Orchestrator->>Planner: Create research plan
    
    loop ReAct Loop
        Planner->>Planner: Thought/Action/Observation
    end
    
    Planner-->>Orchestrator: ResearchPlan
    
    rect rgb(255, 245, 230)
        Note over Orchestrator,Human: Human-in-the-Loop Checkpoint
        Orchestrator->>Human: Display plan for review
        Human-->>Orchestrator: HumanPlanReview
        
        alt Rejected
            Orchestrator->>Planner: Replan with feedback
            Planner-->>Orchestrator: New ResearchPlan
            Orchestrator->>Human: Display new plan
        else Modified
            Note over Human: Human edits plan inline
        end
    end
    
    loop For each task in approved plan
        Orchestrator->>Researcher: Execute task
        Note over Researcher: Tavily + conditional enrichment
        Researcher-->>Orchestrator: ResearchFindings
    end
    
    Orchestrator->>Writer: Write report from findings
    Writer-->>Orchestrator: Draft report
    
    loop Quality Threshold Loop
        Orchestrator->>Editor: Review draft
        Editor-->>Orchestrator: EditorFeedback
        alt Not approved AND iterations < max
            Orchestrator->>Writer: Revise with feedback
            Writer-->>Orchestrator: Revised draft
        end
    end
    
    Orchestrator-->>User: FinalReport