# minh-ton/simple-deep-research architecture

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

- Interactive diagram: https://gitdiagram.com/minh-ton/simple-deep-research
- Repository: https://github.com/minh-ton/simple-deep-research

## Overview

##### Project Type & Purpose
- This is a research agent designed to perform “deep research” by interacting with LLMs (for follow-up questions, precise search queries, and evaluation) and external services (e.g., Firecrawl for search results).
- Its objective is to take a user’s research query, iteratively clarify and transform it into precise search queries, fetch and evaluate web content, and finally compile a research report. The approach is modular and task-based.

a. User Interface/Input:
– A starting point where the user provides the research query and possibly answers follow-up questions.
b. Core Agent/Workflow Orchestrator:
– Represented by the entry point (index.ts) that sets the research process in motion. This orchestrator coordinates multiple tasks.
c. Task Modules (located under src/tasks):
– “follow-up” task: Generates clarifying follow-up questions.
– “precise-query” task: Converts the user’s input into precise search queries.
– “generate-research” task: Combines step outputs into a final research report.
– “assess-sufficiency” task: Verifies if the fetched content addresses the research query.
– “extract-insights” task: Extracts key insights from the web page content.
d. Supporting Library Components (inside src/lib):
– “aisdk.ts”: Handles interactions with the OpenAI API.
– “firecrawl.ts”: Manages interactions with the Firecrawl API for Google searches.
e. External Services:
– OpenAI API for generating queries and evaluating content.
– Firecrawl API for conducting searches.
f. Data / Configuration:
– “constant-config.json” provides configuration parameters (controlled research depth, query limits, timeouts, etc.).
– Environment variables for API keys are configured using a .env file.
g. Output / Report:
– The final research report is output as a Markdown file (research/research.md).

##### Relationships & Data Flow
- The Workflow Orchestrator triggers:
- A “follow-up” step to get additional clarifying information from the LLM.
- A “precise-query” step to transform the input into refined queries.
- These queries are then used to call the Firecrawl API for a Google search. Search results are processed further.
- For each result:
- The “assess-sufficiency” module uses the LLM to decide if the content is relevant.
- The “extract-insights” module extracts the useful details.
- Finally, the “generate-research” module compiles the findings into a coherent research report.

##### Architectural Patterns & Design Principles
- The project employs a multi-step, pipeline-like architecture where each task/module focuses on a single responsibility.
- It makes use of modular design by dividing functionalities into clear, segregated tasks.
- External service interactions (with OpenAI and Firecrawl) are abstracted via dedicated libraries, reinforcing separation of concerns and ease of replacement or modification.

##### Recommendations for the Principal Software Engineer
- Components from “src/lib” to show how the system interfaces with external APIs.
- That any dependencies (for instance, using the “o3-mini” model on the OpenAI API or the specific settings from constant-config.json) are annotated to clarify behavior and configuration parameters.
- Avoid over-complicating; use as many distinct components as necessary so that every function (clarification, query generation, evaluation, extraction, final report) is clearly depicted.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Configuration
    Config1["Configuration (constant-config.json)"]:::config
    Config2["Env Variables (.env.example)"]:::config
    
    %% User Input
    User["User Input"]:::user

    %% Core Orchestrator
    Orchestrator["Workflow Orchestrator (index.ts)"]:::orchestrator

    %% Task Modules
    FollowUp["Follow-up Questions (src/tasks/follow-up.ts)"]:::task
    Precise["Precise Query Generation (src/tasks/precise-query.ts)"]:::task
    Assess["Assess Sufficiency (src/tasks/assess-sufficiency.ts)"]:::task
    Extract["Extract Insights (src/tasks/extract-insights.ts)"]:::task
    Generate["Generate Research Report (src/tasks/generate-research.ts)"]:::task

    %% Supporting Libraries / External APIs
    OpenAI["OpenAI API (src/lib/aisdk.ts)"]:::external
    Firecrawl["Firecrawl API (src/lib/firecrawl.ts)"]:::external

    %% Output
    Report["Research Report (research/research.md)"]:::output

    %% Data Flow
    Config1 -->|"provides"| Orchestrator
    Config2 -->|"provides"| Orchestrator
    User -->|"submits_query"| Orchestrator
    Orchestrator -->|"triggers"| FollowUp
    FollowUp -->|"clarifies_query"| Precise
    FollowUp -->|"LLM_query"| OpenAI
    Precise -->|"calls_search"| Firecrawl
    Firecrawl -->|"returns_results"| Assess
    Assess -->|"evaluates_content"| OpenAI
    Assess -->|"filters_data"| Extract
    Extract -->|"sends_insights"| Generate
    Generate -->|"compiles_report"| Report

    %% Styles
    classDef user fill:#ffdead,stroke:#333,stroke-width:2px;
    classDef orchestrator fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef task fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef external fill:#f94144,stroke:#333,stroke-width:2px;
    classDef config fill:#577590,stroke:#fff,stroke-width:2px,color:#fff;
    classDef output fill:#43aa8b,stroke:#333,stroke-width:2px;

    %% Click Events
    click Orchestrator "https://github.com/minh-ton/simple-deep-research/blob/main/index.ts"
    click FollowUp "https://github.com/minh-ton/simple-deep-research/blob/main/src/tasks/follow-up.ts"
    click Precise "https://github.com/minh-ton/simple-deep-research/blob/main/src/tasks/precise-query.ts"
    click Generate "https://github.com/minh-ton/simple-deep-research/blob/main/src/tasks/generate-research.ts"
    click Assess "https://github.com/minh-ton/simple-deep-research/blob/main/src/tasks/assess-sufficiency.ts"
    click Extract "https://github.com/minh-ton/simple-deep-research/blob/main/src/tasks/extract-insights.ts"
    click OpenAI "https://github.com/minh-ton/simple-deep-research/blob/main/src/lib/aisdk.ts"
    click Firecrawl "https://github.com/minh-ton/simple-deep-research/blob/main/src/lib/firecrawl.ts"
    click Config1 "https://github.com/minh-ton/simple-deep-research/blob/main/constant-config.json"
    click Config2 "https://github.com/minh-ton/simple-deep-research/blob/main/.env.example"
    click Report "https://github.com/minh-ton/simple-deep-research/blob/main/research/research.md"
```
