# rim0o8/deep-research-ts architecture

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

- Interactive diagram: https://gitdiagram.com/rim0o8/deep-research-ts
- Repository: https://github.com/rim0o8/deep-research-ts

## Overview

##### Project Type and Purpose
- This is a full-stack Next.js application built in TypeScript.
- Its main functionality is to serve as a “sophisticated AI research agent” — automating information gathering, analysis, and report generation.
- The README and file structure indicate that the project uses AI language models (e.g., OpenAI, Claude) along with a search engine integration, and leverages the Langchain library for conversation graph management.

##### File Structure
- The project follows a modular structure:
- Frontend layer: Under src/app and src/components. This comprises the UI (including theme-provider and a set of custom UI components under src/components/ui) and Next.js specific application pages (layout.tsx, page.tsx, globals.css).
- API layer: The API endpoints (e.g., src/app/api/deep-research/route.ts) provide a REST or route-based interface to the underlying AI deep research functionalities.
- Business Logic and Engine: Located under src/lib/deep-research. This directory is rich with submodules (action scripts, a builder, helper utilities, configuration, prompts, and state management) that encapsulate the core logic for conducting deep research tasks.
- External integrations: The project includes directories for LLM integration (src/lib/llm) and for search engine adapters (src/lib/deep-research/searchEngine), illustrating its reliance on external AI services.
- Additional support: Modules for language chain conversation graphs are in src/lib/langchain, and configuration files intersperse throughout (e.g., in src/config and src/utils/config).

- Main Components to Include:
- Frontend/UI Layer: Represent the Next.js pages, global styles, and individual UI components (both general UI elements and deep research components like ResearchForm, ResearchReport, ProgressIndicator, etc.).
- API/Backend Layer: Highlight the API endpoint(s) located in src/app/api/deep-research that handle incoming requests and route them to the business logic.
- Deep Research Engine: A comprehensive module that includes:
▪ Action modules (e.g., compileFinalReport, processSections) for driving the research workflow.
▪ Builder modules that orchestrate the assembly of research reports.
▪ Helper utilities (such as those for LLM interactions) that abstract complex logic.
▪ A state management layer (e.g., state.ts) that coordinates the workflow.
▪ Configuration and prompt handling.
- External Integration Components:
▪ LLM Providers: Separate nodes for OpenAI and Claude providers as defined in src/lib/llm.
▪ Search Engine Integration: Components handling search via modules like tavily in the searchEngine directory.
▪ Langchain for managing conversational graphs.

- Relationships and Interactions:
- The Frontend makes HTTP calls to the API endpoints to trigger deep research operations.
- The API layer acts as the bridge between the frontend clients and the deep research engine.
- The deep research engine orchestrates processing by invoking various action sequences, using helper functions, and interfacing with LLM providers and search engines.
- The configuration modules supply necessary environmental and dependency configurations (e.g., API keys, llm parameters) throughout the system.

- Architectural Patterns and Design Principles:
- Separation of concerns: Clearly divide the presentation layer (UI), service/API layer, and business logic (deep research engine).
- Modularity: Components are split into discrete modules (actions, builders, helpers) to promote reusability and ease of maintenance.
- Extensibility: The presence of separate integration modules (for LLM, search engine, "langchain" conversation graph) indicates that the system is designed for easy extension or swapping of underlying services.
- API-driven design: The deep research API is a central access point, crucial for integration with both internal and potentially external consumers.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Frontend (Next.js UI Layer)"
        FE_Layout("Next.js Layout (layout.tsx)")
        FE_Page("Next.js Page (page.tsx)")
        FE_Globals("Global Styles (globals.css)")
        FE_Components("UI Components (components)")
        FE_Theme("Theme Provider (theme-provider.tsx)")
        FE_DeepResearch("Deep Research UI (deep-research)")
        FE_UI_Custom("Custom UI Components (ui)")
    end

    subgraph "API Layer"
        API_Node("API Endpoint (deep-research/route.ts)")
    end

    subgraph "Deep Research Engine"
        DRE_Core("Deep Research Core (lib/deep-research)")
        DRE_Actions("Action Modules")
        DRE_Builder("Builder Modules")
        DRE_Helpers("Helper Utilities & State Management")
        DRE_Config("Configuration & Prompts")
    end

    subgraph "External Integrations"
        LLM_Node("LLM Providers (lib/llm)")
        Search_Node("Search Engine (deep-research/searchEngine)")
        Langchain_Node("Langchain Conversation Graph")
    end

    subgraph "Global Configurations"
        GCFG1("Global Config (config)")
        GCFG2("Utils Config (utils/config)")
    end

    %% Frontend to API
    FE_Layout -->|"HTTPCall"| API_Node
    FE_Page -->|"HTTPCall"| API_Node
    FE_Globals -->|"HTTPCall"| API_Node
    FE_Components -->|"HTTPCall"| API_Node
    FE_Theme -->|"HTTPCall"| API_Node
    FE_DeepResearch -->|"HTTPCall"| API_Node
    FE_UI_Custom -->|"HTTPCall"| API_Node

    %% API to Deep Research Engine
    API_Node -->|"Triggers"| DRE_Core

    %% Internal Deep Research Engine Dependencies
    DRE_Core -->|"Executes"| DRE_Actions
    DRE_Core -->|"Executes"| DRE_Builder
    DRE_Core -->|"Executes"| DRE_Helpers
    DRE_Core -->|"Executes"| DRE_Config

    %% Deep Research Engine uses External Services
    DRE_Core -->|"Uses"| LLM_Node
    DRE_Core -->|"Uses"| Search_Node
    DRE_Core -->|"Manages"| Langchain_Node

    %% Global Configurations supply settings
    GCFG1 -->|"Provides"| DRE_Core
    GCFG2 -->|"Provides"| DRE_Core
    GCFG1 -->|"Configures"| LLM_Node
    GCFG2 -->|"Configures"| LLM_Node

    %% Click Events for Frontend
    click FE_Layout "https://github.com/rim0o8/deep-research-ts/blob/main/src/app/layout.tsx"
    click FE_Page "https://github.com/rim0o8/deep-research-ts/blob/main/src/app/page.tsx"
    click FE_Globals "https://github.com/rim0o8/deep-research-ts/blob/main/src/app/globals.css"
    click FE_Components "https://github.com/rim0o8/deep-research-ts/tree/main/src/components"
    click FE_Theme "https://github.com/rim0o8/deep-research-ts/blob/main/src/components/theme-provider.tsx"
    click FE_DeepResearch "https://github.com/rim0o8/deep-research-ts/tree/main/src/components/deep-research"
    click FE_UI_Custom "https://github.com/rim0o8/deep-research-ts/tree/main/src/components/ui"

    %% Click Event for API
    click API_Node "https://github.com/rim0o8/deep-research-ts/blob/main/src/app/api/deep-research/route.ts"

    %% Click Event for Deep Research Engine
    click DRE_Core "https://github.com/rim0o8/deep-research-ts/tree/main/src/lib/deep-research"

    %% Click Event for LLM Providers
    click LLM_Node "https://github.com/rim0o8/deep-research-ts/tree/main/src/lib/llm"

    %% Click Event for Search Engine Integration
    click Search_Node "https://github.com/rim0o8/deep-research-ts/tree/main/src/lib/deep-research/searchEngine"

    %% Click Event for Langchain Integration
    click Langchain_Node "https://github.com/rim0o8/deep-research-ts/tree/main/src/lib/langchain"

    %% Click Event for Global Configurations
    click GCFG1 "https://github.com/rim0o8/deep-research-ts/tree/main/src/config"
    click GCFG2 "https://github.com/rim0o8/deep-research-ts/tree/main/src/utils/config"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef api fill:#ABEBC6,stroke:#1D8348,stroke-width:2px;
    classDef engine fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef integration fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef config fill:#F5B7B1,stroke:#943126,stroke-width:2px;

    class FE_Layout,FE_Page,FE_Globals,FE_Components,FE_Theme,FE_DeepResearch,FE_UI_Custom frontend;
    class API_Node api;
    class DRE_Core,DRE_Actions,DRE_Builder,DRE_Helpers,DRE_Config engine;
    class LLM_Node,Search_Node,Langchain_Node integration;
    class GCFG1,GCFG2 config;
```
