# vonhatthinh/deep-research-agent architecture

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

- Interactive diagram: https://gitdiagram.com/vonhatthinh/deep-research-agent
- Repository: https://github.com/vonhatthinh/deep-research-agent

## Overview

##### Project Type and Purpose
- This is a full-stack Python application consisting of a FastAPI backend and a Streamlit frontend.
- It implements a multimodal “Deep Research Agent” pipeline: users submit text, images, or documents via the UI; the backend orchestrates a series of specialized agents (QueryAnalyzer, TaskPlanner, Researcher, Visualizer, Evaluator); results are streamed back in real time and assembled into a final report.

##### File Structure Overview
- Top-level:
- main.py – entry point for the FastAPI server
- ui/app.py – Streamlit frontend
- agent/ – core multi-agent modules (base_agent.py, multi_agent.py, schema.py, tools.py, agent.py)
- core/config.py – configuration handling
- database/vector_store.py – wrapper around a vector database for knowledge storage/retrieval
- resources/ – static assets (e.g., workflow_diagram.png)
- .devcontainer, DockerFile – dev environment and containerization
- Patterns & Layers:
- Presentation Layer: Streamlit UI
- API Layer: FastAPI endpoints & SSE streaming
- Orchestration Layer: multi_agent.py coordinating agent pipeline
- Agent Modules: each agent implements one research stage
- Data Layer: vector_store + file‐upload handling
- External Integrations: OpenAI Assistants API, Tavily Search API, Gemini Vision, DALL-E3

##### Key Architectural Patterns
- Modular, single‐responsibility agents in a pipeline (QueryAnalyzer → TaskPlanner → Researcher → Visualizer → Evaluator)
- Asynchronous, streaming communication (FastAPI’s StreamingResponse + Streamlit’s st.write_stream)
- Clear separation of concerns: UI ↔ API ↔ Agents ↔ Data layer ↔ External services
- Pluggable “tools” abstraction for search, image generation, document parsing

##### Main Components & Their Relationships
A. Streamlit UI (ui/app.py)
- Submits user queries/files via HTTP POST to backend `/query` endpoint
- Listens for Server-Sent Events and renders the agent’s step‐by‐step output
B. FastAPI Backend (main.py + agent modules)
- Exposes `/status` and POST `/query`
- Parses inputs, persists/uploaded files or images if needed
- Invokes the MultiAgent orchestrator asynchronously
- Streams intermediate events back to UI
C. MultiAgent Orchestrator (agent/multi_agent.py)
- Imports specialized agents from agent/base_agent.py and agent/agent.py
- Uses agent/tools.py for external calls
- Emits events conforming to agent/schema.py
D. Vector Store (database/vector_store.py)
- Persists research snippets into a vector‐searchable index
- Queried by the Researcher agent for context or similarity retrieval
E. External Services
- OpenAI Assistants API for generative steps
- Tavily Search API for live web search
- Gemini Vision for image comprehension
- DALL-E 3 for image generation

##### Essential Details to Capture
- Entry points: ui/app.py and main.py.
- Agent pipeline sequence and the dual role of agent/tools.py (adapters to external APIs).
- Vector store interactions (read/write).
- File and image upload handling within the API layer.
- Asynchronous streaming flow.
- Environment setup (DockerFile, devcontainer) as a side note or deployment layer.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["Streamlit App\nStreamlit"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        API["FastAPI Server\nFastAPI\nPOST /query\n/status"]:::api
        Config["Configuration\n(core/config.py)"]:::api
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        MultiAgent["MultiAgent Orchestrator"]:::orchestrator
        BaseAgent["BaseAgent Abstractions"]:::orchestrator
        AgentImpl["Specialized Agent Implementations"]:::orchestrator
        Schema["Agent Event Schema"]:::orchestrator
        Tools["Agent Tools (External Adapters)"]:::orchestrator

        subgraph "Agent Pipeline"
            QA["QueryAnalyzer"]:::orchestrator
            TP["TaskPlanner"]:::orchestrator
            R["Researcher"]:::orchestrator
            V["Visualizer"]:::orchestrator
            E["Evaluator"]:::orchestrator
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        VectorStore["Vector Store\nVector DB"]:::db
        Resources["Static Resources"]:::db
    end

    %% External Services
    subgraph "External Services"
        OpenAI["OpenAI Assistant API"]:::external
        Tavily["Tavily Search API"]:::external
        Gemini["Gemini Vision API"]:::external
        Dalle["DALL·E 3 API"]:::external
    end

    %% Deployment Layer
    subgraph "Deployment"
        Dev["DevContainer Setup"]:::dev
        Docker["DockerFile"]:::dev
    end

    %% Connections
    UI -->|"POST /query"| API
    API -->|"load config"| Config
    API -->|"invoke orchestrator"| MultiAgent

    MultiAgent --> BaseAgent
    MultiAgent --> AgentImpl
    MultiAgent --> Tools
    MultiAgent --> Schema

    MultiAgent -->|"1"| QA
    QA -->|"2"| TP
    TP -->|"3"| R
    R -->|"4"| V
    V -->|"5"| E

    R -->|"read/write"| VectorStore
    Tools --> OpenAI
    Tools --> Tavily
    Tools --> Gemini
    Tools --> Dalle
    OpenAI --> Tools
    Tavily --> Tools
    Gemini --> Tools
    Dalle --> Tools

    E -->|"emit events"| API
    API -.->|"SSE Streaming"| UI

    API --> Dev
    API --> Docker
    UI --> Dev
    UI --> Docker

    %% Click Events
    click UI "https://github.com/vonhatthinh/deep-research-agent/blob/main/ui/app.py"
    click API "https://github.com/vonhatthinh/deep-research-agent/blob/main/main.py"
    click Config "https://github.com/vonhatthinh/deep-research-agent/blob/main/core/config.py"
    click MultiAgent "https://github.com/vonhatthinh/deep-research-agent/blob/main/agent/multi_agent.py"
    click BaseAgent "https://github.com/vonhatthinh/deep-research-agent/blob/main/agent/base_agent.py"
    click AgentImpl "https://github.com/vonhatthinh/deep-research-agent/blob/main/agent/agent.py"
    click Schema "https://github.com/vonhatthinh/deep-research-agent/blob/main/agent/schema.py"
    click Tools "https://github.com/vonhatthinh/deep-research-agent/blob/main/agent/tools.py"
    click VectorStore "https://github.com/vonhatthinh/deep-research-agent/blob/main/database/vector_store.py"
    click Resources "https://github.com/vonhatthinh/deep-research-agent/tree/main/resources/"
    click Dev "https://github.com/vonhatthinh/deep-research-agent/tree/main/.devcontainer/"
    click Docker "https://github.com/vonhatthinh/deep-research-agent/tree/main/DockerFile"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0099FF,stroke-width:2px
    classDef api fill:#E0F7FF,stroke:#00AACC,stroke-width:2px
    classDef orchestrator fill:#DFFFE0,stroke:#33AA33,stroke-width:2px
    classDef db fill:#FFE8CC,stroke:#FF9933,stroke-width:2px
    classDef external fill:#F0F0F0,stroke:#888888,stroke-width:2px
    classDef dev fill:#F9E0FF,stroke:#CC33AA,stroke-width:2px
```
