# psykick-21/deep-research architecture

> Architecture diagram of the GitHub repository psykick-21/deep-research, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/psykick-21/deep-research
- Repository: https://github.com/psykick-21/deep-research

## Overview

##### Project Type and Purpose
- Deep Research is a Python-based research automation tool. It leverages LangChain/LangGraph to orchestrate multiple AI agents (nodes) that collaboratively gather, reflect on, and synthesize information into a structured research report. Users can interact via a CLI script (main.py) or a Jupyter notebook (main.ipynb).

##### Top-Level File Structure Analysis
- deep_research/
- configuration.py – loads settings and API keys
- graph.py – defines the LangGraph workflow (DAG orchestrator)
- nodes.py – implements individual research agents (planning, search, reflection, synthesis)
- prompts.py – houses the text prompts for LLM interactions
- state.py – manages in-memory or persisted research state
- struct.py – defines data models (sections, queries, results)
- utils.py – helper functions (logging, API wrappers)
- main.py / main.ipynb – entry points for batch or interactive runs
- temp/ – scratch notebook
- pyproject.toml – build & dependency config

##### Key Insights from README
- Two entry points: script and notebook
- Prereqs: Python 3.12, Poetry, four external APIs (OpenAI, Anthropic, Google AI, Tavily)
- Workflow: Initial planning → Section-wise research (loop of search, reflection, synthesis) → Final curation
- Outputs: logs/ (detailed process logs), reports/ (final research reports)

##### Main Components
a. User Interface
- CLI (main.py)
- Notebook (main.ipynb)
b. Configuration Loader
- Reads .env, configuration.py
c. Workflow Engine
- LangGraph orchestrator (graph.py)
d. Research Agents (Nodes)
- Structure Generator Agent
- Search Agent (Tavily + LLM knowledge base)
- Reflection Agent
- Query Generator Agent
- Synthesis Agent
e. State & Data Store
- In-memory state manager (state.py)
- Data models (struct.py)
f. External Services
- OpenAI, Anthropic, Google AI (LLM endpoints)
- Tavily (deep web search)
g. Utilities
- Logging subsystem (utils.py → logs/)
- Report writer (outputs to reports/)

##### Relationships and Data Flows
- User → starts main.py/notebook
- Configuration Loader → initializes API clients & graph parameters
- Workflow Engine → invokes Structure Generator → produces outline
- For each outline section:
- Search Agent ↔ External APIs → collects raw data
- Reflection Agent → reviews accumulated data
- Query Generator Agent → produces refined search queries
- Synthesis Agent → generates section text
- State Manager ← stores intermediate results
- Final Curation Step (LangGraph node) → merges all sections
- Report Writer → persists final document → logs progress

##### Architectural Patterns & Principles
- Agent-based pipeline: each node encapsulates a responsibility
- Directed acyclic workflow (LangGraph) for clear orchestration
- Recursive improvement loop for each section
- Separation of concerns: config, orchestration, node logic, state management, I/O

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    subgraph "User Interface"
        CLI["CLI (main.py)"]:::ui
        NB["Notebook (main.ipynb)"]:::ui
    end

    %% Configuration
    CFG["Configuration Loader\n(configuration.py)"]:::config

    %% Orchestration
    ENG["Workflow Engine\n(graph.py)"]:::orchestration

    %% Research Agents
    subgraph "Research Agents"
        SG["Structure Generator\n(nodes.py)"]:::agent
        QG["Query Generator\n(nodes.py)"]:::agent
        SA["Search Agent\n(nodes.py)"]:::agent
        RA["Reflection Agent\n(nodes.py)"]:::agent
        SY["Synthesis Agent\n(nodes.py)"]:::agent
        C["Final Curation\n(nodes.py)"]:::agent
    end

    %% State & Models
    STM["State Manager\n(state.py)"]:::storage
    DM["Data Models\n(struct.py)"]:::storage

    %% Utilities & Prompts
    UTIL["Utilities\n(utils.py)"]:::utilities
    PROM["Prompts\n(prompts.py)"]:::utilities

    %% External Services
    subgraph "External Services"
        OAI["OpenAI"]:::external
        ANT["Anthropic"]:::external
        GAI["Google AI"]:::external
        TAV["Tavily"]:::external
    end

    %% Outputs
    LOG["Logs\n(logs/)"]:::output
    REP["Reports\n(reports/)"]:::output

    %% Data Flows
    CLI --> CFG --> ENG
    NB --> CFG
    ENG --> SG
    SG --> STM
    STM --> QG
    QG -->|"initial queries"| SA
    SA -->|"search requests"| OAI
    SA -->|"search requests"| ANT
    SA -->|"search requests"| GAI
    SA -->|"search requests"| TAV
    OAI -->|"search results"| SA
    ANT -->|"search results"| SA
    GAI -->|"search results"| SA
    TAV -->|"search results"| SA
    SA -->|"raw data"| STM
    STM --> RA
    RA -->|"reflections"| QG
    QG --> SA
    RA --> SY
    SY -->|"section text"| STM
    STM --> C
    C -->|"final document"| REP
    C -->|"process logs"| LOG
    UTIL --> LOG

    %% Click Events
    click CLI "https://github.com/psykick-21/deep-research/blob/main/main.py"
    click NB "https://github.com/psykick-21/deep-research/blob/main/main.ipynb"
    click CFG "https://github.com/psykick-21/deep-research/blob/main/deep_research/configuration.py"
    click ENG "https://github.com/psykick-21/deep-research/blob/main/deep_research/graph.py"
    click SG "https://github.com/psykick-21/deep-research/blob/main/deep_research/nodes.py"
    click QG "https://github.com/psykick-21/deep-research/blob/main/deep_research/nodes.py"
    click SA "https://github.com/psykick-21/deep-research/blob/main/deep_research/nodes.py"
    click RA "https://github.com/psykick-21/deep-research/blob/main/deep_research/nodes.py"
    click SY "https://github.com/psykick-21/deep-research/blob/main/deep_research/nodes.py"
    click C "https://github.com/psykick-21/deep-research/blob/main/deep_research/nodes.py"
    click STM "https://github.com/psykick-21/deep-research/blob/main/deep_research/state.py"
    click DM "https://github.com/psykick-21/deep-research/blob/main/deep_research/struct.py"
    click UTIL "https://github.com/psykick-21/deep-research/blob/main/deep_research/utils.py"
    click PROM "https://github.com/psykick-21/deep-research/blob/main/deep_research/prompts.py"

    %% Styles
    classDef ui fill:#FFD580,stroke:#BB650B,color:#000;
    classDef config fill:#B2EBF2,stroke:#007C91,color:#000;
    classDef orchestration fill:#C8E6C9,stroke:#2E7D32,color:#000;
    classDef agent fill:#FFE0B2,stroke:#EF6C00,color:#000;
    classDef storage fill:#D1C4E9,stroke:#512DA8,color:#000;
    classDef utilities fill:#F0F4C3,stroke:#9E9D24,color:#000;
    classDef external fill:#F8BBD0,stroke:#C2185B,color:#000;
    classDef output fill:#CFD8DC,stroke:#455A64,color:#000;
```
