# eruaro/open-gemini-deep-research architecture

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

- Interactive diagram: https://gitdiagram.com/eruaro/open-gemini-deep-research
- Repository: https://github.com/eruaro/open-gemini-deep-research

## Overview

##### Project Type and Purpose
- This is an open-source CLI research assistant written in Python that orchestrates multi-layered queries through Google’s Gemini AI, processes results concurrently, tracks progress in a tree structure, and outputs a detailed report with citations.

##### File-Structure Analysis
- Top-level:
– main.py (CLI entry point)
– dockerfile & .devcontainer/ (Dev Container setup)
– requirements.txt & .env (dependencies and API key)
- src/:
– deep_research.py (core research engine)
- Outputs (implicit):
– final_report.md
– research_tree.json (progress tree)
- Patterns: monolithic service, modularized into CLI layer and research engine, uses external API, file-based persistence.

##### Key Architectural Insights from README
- Three research modes driving breadth/depth parameters
- Query Analysis → Query Generation → Research Tree Building → (recursive) Deep Research → Report Generation
- Concurrency for parallel queries
- ResearchProgress class implements a parent-child tree with UUIDs
- External dependency: Google Gemini AI API

a. Components
1. CLI Layer (main.py)
2. Research Engine (deep_research.py)
- Query Analyzer
- Query Generator
- ResearchProgress (tree manager)
- Deep Research Worker (recursive logic)
- Report Generator
3. Concurrency Manager (Python’s asyncio/threadpool)
4. External Service (Google Gemini AI)
5. Local Data Store (filesystem)
- research_tree.json
- final_report.md
6. Dev Container / Docker Environment
b. Data Flows
- User CLI → CLI Layer parses args → Research Engine
- Engine → Query Analyzer sets breadth/depth
- Query Generator emits seed queries → Concurrency Manager
- Workers call Gemini API → receive results → ResearchProgress updates tree
- Recursive calls for comprehensive mode
- Completed tree passed to Report Generator → writes final_report.md & research_tree.json
c. Architectural Patterns
– Modular layering (CLI vs. engine)
– Pipeline/chain of responsibility (analysis → generation → execution → aggregation)
– Recursive tree data structure
– Concurrent execution of tasks
d. Technologies
– Python 3.9+ with asyncio/concurrent.futures
– Google Gemini AI REST API
– Docker / Dev Container for environment consistency
– JSON for tree persistence; Markdown for final report

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Dev Container / Docker Environment"
        direction TB
        dockerfile["dockerfile"]:::env
        devcontainer[".devcontainer/devcontainer.json"]:::env
        requirements["requirements.txt"]:::env
    end

    CLI["CLI Layer\n(main.py)"]:::internal
    subgraph "Research Engine\n(src/deep_research.py)"
        direction TB
        Analyzer["Query Analyzer"]:::internal
        Generator["Query Generator"]:::internal
        Concurrency["Concurrency Manager\n(asyncio/threadpool)"]:::internal
        Worker["Deep Research Worker"]:::internal
        Progress["ResearchProgress\n(tree manager)"]:::internal
        Reporter["Report Generator"]:::internal
    end

    External["Google Gemini AI\n(External Service)"]:::external
    subgraph "Local Data Store"
        direction TB
        JSON["research_tree.json"]:::datastore
        MD["final_report.md"]:::datastore
    end

    CLI -->|"parse CLI args"| Analyzer
    Analyzer -->|"set breadth/depth"| Generator
    Generator -->|"emit seed queries"| Concurrency
    Concurrency -->|"spawn tasks"| Worker
    Worker -->|"HTTP request"| External
    External -->|"API response"| Progress
    Worker -->|"results"| Progress
    Progress -->|"update UUID tree"| Generator
    Worker -->|"recursive sub-queries"| Generator
    Progress --> Reporter
    Reporter -->|"write JSON"| JSON
    Reporter -->|"write MD"| MD

    click CLI "https://github.com/eruaro/open-gemini-deep-research/blob/main/main.py"
    click Analyzer "https://github.com/eruaro/open-gemini-deep-research/blob/main/src/deep_research.py"
    click Generator "https://github.com/eruaro/open-gemini-deep-research/blob/main/src/deep_research.py"
    click Concurrency "https://github.com/eruaro/open-gemini-deep-research/blob/main/src/deep_research.py"
    click Worker "https://github.com/eruaro/open-gemini-deep-research/blob/main/src/deep_research.py"
    click Progress "https://github.com/eruaro/open-gemini-deep-research/blob/main/src/deep_research.py"
    click Reporter "https://github.com/eruaro/open-gemini-deep-research/blob/main/src/deep_research.py"
    click External "https://github.com/eruaro/open-gemini-deep-research/blob/main/.env"
    click JSON "https://github.com/eruaro/open-gemini-deep-research/blob/main/research_tree.json"
    click MD "https://github.com/eruaro/open-gemini-deep-research/blob/main/final_report.md"
    click dockerfile "https://github.com/eruaro/open-gemini-deep-research/tree/main/dockerfile"
    click devcontainer "https://github.com/eruaro/open-gemini-deep-research/blob/main/.devcontainer/devcontainer.json"
    click requirements "https://github.com/eruaro/open-gemini-deep-research/blob/main/requirements.txt"

    classDef internal fill:#9f6,stroke:#333,stroke-width:1px
    classDef external fill:#6cf,stroke:#333,stroke-width:1px
    classDef datastore fill:#fc6,stroke:#333,stroke-width:1px
    classDef env fill:#ccc,stroke:#333,stroke-width:1px
```
