# pushkrjain/deep_research_agent architecture

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

- Interactive diagram: https://gitdiagram.com/pushkrjain/deep_research_agent
- Repository: https://github.com/pushkrjain/deep_research_agent

## Overview

##### Project type and purpose
- This is a Python-based, AI-powered research tool (a CLI “full-stack” application without a browser GUI) that orchestrates multiple agent components to:
- Crawl and collect web data (Research Agent)
- Generate structured reports in Markdown (Draft Agent)
- Produce reliability charts (Visualization Agent)
- Export the final report to Word with embedded visuals (Export Agent)

##### File structure
- Top level:
- app.py            → entry point / orchestrator
- requirements.txt  → lists dependencies (LangChain, LangGraph, Matplotlib, Seaborn, python‐docx, etc.)
- research/         → package containing the four agent modules
- research/:
- research_agent.py → web‐crawling + data structuring
- draft_agent.py    → prompt engineering + report generation
- export.py         → document export to .docx, writes to disk
- Configuration files: .gitignore, LICENSE
- Output directories/logs implied (research_outputs/, research.log)

##### Key insights from README
- Multi-agent architecture built on LangChain and LangGraph
- External dependencies:
- Tavily API (web search)
- Google Gemini API (NLP)
- CLI interface: user enters query, app.py invokes the pipeline
- Outputs saved with timestamps in research_outputs/

1. User CLI (app.py)
2. Agent Orchestrator (part of app.py)
3. Research Agent
4. Draft Agent
5. Visualization Agent
6. Export Agent
7. External Services:
– Tavily API
– Google Gemini API
8. Local Storage:
– research_outputs/ (reports, images)
– research.log
- User → CLI/App.py: “Enter research query”
- App.py → Research Agent: passes query
- Research Agent → Tavily API: fetch raw data
- Tavily API → Research Agent: structured data
- App.py → Visualization Agent: passes structured data
- Visualization Agent → Matplotlib/Seaborn → generates chart → local storage
- App.py → Draft Agent: passes structured data + optional chart metadata
- Draft Agent → Google Gemini API: prompt for report → returns Markdown
- App.py → Export Agent: passes Markdown + chart file paths
- Export Agent → python-docx → writes .docx to research_outputs/
- All modules → research.log: log entries/errors
c. Architectural patterns / design principles:
- **Separation of Concerns**: each agent has a single responsibility
- **Pipeline Orchestration**: app.py sequences the four agents
- **External API Abstraction** via LangChain/LangGraph wrappers
- **Modular & Extensible**: new agents can be added under research/
d. Key technologies / libraries:
- Language orchestration: LangChain, LangGraph
- HTTP clients / API wrappers: Tavily client, Google Gemini SDK
- Visualization: Matplotlib, Seaborn
- Document export: python-docx (or similar)
- Logging: Python’s logging module (research.log)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Orchestrator
    CLI["User CLI / Agent Orchestrator\n(app.py)"]:::internal
    click CLI "https://github.com/pushkrjain/deep_research_agent/blob/main/app.py"

    %% Agents
    Research["Research Agent\n(research/research_agent.py)"]:::internal
    click Research "https://github.com/pushkrjain/deep_research_agent/blob/main/research/research_agent.py"
    Draft["Draft Agent\n(research/draft_agent.py)"]:::internal
    click Draft "https://github.com/pushkrjain/deep_research_agent/blob/main/research/draft_agent.py"
    Visual["Visualization Agent\n(research/visualize.py)"]:::internal
    click Visual "https://github.com/pushkrjain/deep_research_agent/blob/main/research/visualize.py"
    Export["Export Agent\n(research/export.py)"]:::internal
    click Export "https://github.com/pushkrjain/deep_research_agent/blob/main/research/export.py"

    %% External Services
    Tavily["Tavily API"]:::external
    Gemini["Google Gemini API"]:::external

    %% Storage
    Outputs["research_outputs/"]:::storage
    Log["research.log"]:::storage

    %% Configuration Files
    subgraph "Configuration & Metadata"
        Requirements["requirements.txt"]:::config
        click Requirements "https://github.com/pushkrjain/deep_research_agent/blob/main/requirements.txt"
        Init["research/__init__.py"]:::config
        click Init "https://github.com/pushkrjain/deep_research_agent/blob/main/research/__init__.py"
        Readme["README.md"]:::config
        click Readme "https://github.com/pushkrjain/deep_research_agent/blob/main/README.md"
        Gitignore[".gitignore"]:::config
        click Gitignore "https://github.com/pushkrjain/deep_research_agent/blob/main/.gitignore"
        License["LICENSE"]:::config
        click License "https://github.com/pushkrjain/deep_research_agent/tree/main/LICENSE"
    end

    %% Data Flow
    CLI -->|"enter research query"| Research
    Research -->|"fetch raw data"| Tavily
    Tavily -->|"return structured data"| Research
    Research -->|"structured data"| CLI

    CLI -->|"pass structured data"| Visual
    Visual -->|"generate charts"| Outputs

    CLI -->|"pass structured data & chart metadata"| Draft
    Draft -->|"prompt for report"| Gemini
    Gemini -->|"return Markdown report"| Draft
    Draft -->|"Markdown report"| CLI

    CLI -->|"pass Markdown & chart paths"| Export
    Export -->|"write .docx report"| Outputs

    %% Logging from all modules
    CLI -->|"log entries"| Log
    Research -->|"log entries"| Log
    Visual -->|"log entries"| Log
    Draft -->|"log entries"| Log
    Export -->|"log entries"| Log

    %% Styles
    classDef internal fill:#D0E6FA,stroke:#0366d6,stroke-width:1px;
    classDef external fill:#E6F4EA,stroke:#1a7f37,stroke-width:1px;
    classDef storage fill:#FFF5B1,stroke:#B08800,stroke-width:1px;
    classDef config fill:#F0F0F0,stroke:#888888,stroke-width:1px;
```
