# jina-ai/node-deepresearch architecture

> Architecture diagram of the GitHub repository jina-ai/node-deepresearch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jina-ai/node-deepresearch
- Repository: https://github.com/jina-ai/node-deepresearch

## Overview

##### Main Components
- Core Processing Engine – Represent the iterative “deep research” loop that processes a user query through a chain: it gathers the question, generates a prompt, sends that to an LLM, then examines the type of action (answer, reflect, search, visit) and loops until a final answer is produced. This is best represented as a loop or flow that captures: Get Question → Generate Prompt → Model Generation → Action Check → (Answer/Reflect/Search/Visit) → Loop back OR termination.
- LLM Integration Module – Show the interface for external LLM providers (Gemini, OpenAI, or Local LLM services). Indicate that these modules are invoked to generate responses.
- External Search and Reading – Highlight that integration with the Jina Reader (or Jina API) supports the search and read steps for obtaining web content.

- From the Client Interfaces to the Core Processing Engine (requests coming from CLI or API calls).
- Interactions from various utility components (logging, error handling, configuration) being used by the core modules.

##### Architectural Patterns & Design Principles
- Iterative Workflow Pattern – Emphasize the cyclic process that continues until the token budget is exceeded or a “definitive” answer is reached.
- Separation of Concerns – The structure already divides responsibilities: the “src” directory deals with general application logic, and “jina-ai” encapsulates specialized functionalities (possibly microservice-like behavior for Jina-specific operations).
- Extensibility – Tools in the “src/tools” and “src/lib” directories indicate modular design. Note how new LLM integrations or search strategies could be added thanks to a well-defined interface.

##### Technologies, Frameworks, and Libraries
- Node.js runtime and Express (inferred from server.ts files) for the API server.
- Docker and Docker Compose for containerization and deployment.
- Testing frameworks such as Jest (noted by jest.config.js and __tests__ directories) for quality assurance.
- Integration with external APIs (OpenAI, Gemini, Jina Reader).
- Use of TypeScript (indicated by tsconfig.json files) which suggests a typed code base.

1. Entry points (CLI and API).
2. The iterative reasoning loop (with details for each step if space allows).
3. Connections to external LLM and search services.
4. Deployment context (noting Docker and configuration).
- Remember to incorporate any architectural elements that might be unique to deep research (for instance, the special handling of tokens like <think>...</think> in the response flow).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Interfaces
    subgraph "Client Interfaces"
        CLI["CLI Interface"]:::client
        API["HTTP API Server"]:::client
    end

    %% Core Processing Engine
    subgraph "Core Processing Engine"
        Agent["Agent (Orchestrator)"]:::core
        App["App (Coordinator)"]:::core
        Agent -->|"process"| App
        App -->|"iteration"| Agent
    end

    %% LLM Integration Module
    subgraph "LLM Integration Module"
        LLM["LLM Integration"]:::external
        LLM_lib["LLM Libraries"]:::external
        LLM_dto["LLM DTO Definitions"]:::external
        LLM --> LLM_lib
        LLM --> LLM_dto
    end

    %% External Search and Reading
    subgraph "Search/Read Module"
        JinaSearch["Jina Search"]:::external
        BraveSearch["Brave Search"]:::external
        SerperSearch["Serper Search"]:::external
        Reader["Content Reader"]:::external
        JinaSearch -->|"retrieves"| Reader
        BraveSearch -->|"retrieves"| Reader
        SerperSearch -->|"retrieves"| Reader
    end

    %% Utility & Helper Modules
    subgraph "Utility & Helper Modules"
        ErrAnalyzer["Error Analyzer"]:::utility
        Dedup["Deduplication"]:::utility
        QueryRewriter["Query Rewriter"]:::utility
        TokenTracker["Token Tracker"]:::utility
        ActionTracker["Action Tracker"]:::utility
        SafeGenerator["Safe Generator"]:::utility
    end

    %% Configuration & Environment
    subgraph "Configuration & Environment"
        GlobalConfig["Global Config (config.json)"]:::config
        DockerCompose["Docker Compose"]:::config
        TSConfig["TSConfig"]:::config
        JinaConfig["Jina Config"]:::config
    end

    %% Connections from Client Interfaces to Core Processing Engine
    CLI -->|"user query"| Agent
    API -->|"user query"| Agent

    %% Connections from Core Engine to External Modules
    Agent -->|"LLM request"| LLM
    LLM -->|"LLM response"| Agent

    Agent -->|"search query"| JinaSearch
    Agent -->|"search query"| BraveSearch
    Agent -->|"search query"| SerperSearch
    Reader -->|"search results"| Agent

    %% Connections from Core Engine to Utility Modules
    Agent -->|"error/log/util"| ErrAnalyzer
    Agent -->|"error/log/util"| Dedup
    Agent -->|"error/log/util"| QueryRewriter
    Agent -->|"tracking"| TokenTracker
    Agent -->|"tracking"| ActionTracker
    Agent -->|"tracking"| SafeGenerator

    %% Connections from Configuration to Core Engine and LLM Integration
    GlobalConfig -->|"config settings"| Agent
    DockerCompose -->|"deployment config"| Agent
    TSConfig -->|"build config"| Agent
    JinaConfig -->|"Jina-specific config"| LLM

    %% Styling
    classDef client fill:#a2d9ce,stroke:#000,stroke-width:1px;
    classDef core fill:#f9e79f,stroke:#000,stroke-width:1px;
    classDef external fill:#fadbd8,stroke:#000,stroke-width:1px;
    classDef utility fill:#d2b4de,stroke:#000,stroke-width:1px;
    classDef config fill:#c5eff7,stroke:#000,stroke-width:1px;

    %% Click Events for Client Interfaces
    click CLI "https://github.com/jina-ai/node-deepresearch/blob/main/src/cli.ts"
    click API "https://github.com/jina-ai/node-deepresearch/blob/main/src/server.ts"

    %% Click Events for Core Processing Engine
    click Agent "https://github.com/jina-ai/node-deepresearch/blob/main/src/agent.ts"
    click App "https://github.com/jina-ai/node-deepresearch/blob/main/src/app.ts"

    %% Click Events for LLM Integration Module
    click LLM "https://github.com/jina-ai/node-deepresearch/blob/main/jina-ai/src/server.ts"
    click LLM_lib "https://github.com/jina-ai/node-deepresearch/tree/main/jina-ai/src/lib"
    click LLM_dto "https://github.com/jina-ai/node-deepresearch/tree/main/jina-ai/src/dto"

    %% Click Events for External Search and Reading
    click JinaSearch "https://github.com/jina-ai/node-deepresearch/blob/main/src/tools/jina-search.ts"
    click BraveSearch "https://github.com/jina-ai/node-deepresearch/blob/main/src/tools/brave-search.ts"
    click SerperSearch "https://github.com/jina-ai/node-deepresearch/blob/main/src/tools/serper-search.ts"
    click Reader "https://github.com/jina-ai/node-deepresearch/blob/main/src/tools/read.ts"

    %% Click Events for Utility & Helper Modules
    click ErrAnalyzer "https://github.com/jina-ai/node-deepresearch/blob/main/src/tools/error-analyzer.ts"
    click Dedup "https://github.com/jina-ai/node-deepresearch/blob/main/src/tools/dedup.ts"
    click QueryRewriter "https://github.com/jina-ai/node-deepresearch/blob/main/src/tools/query-rewriter.ts"
    click TokenTracker "https://github.com/jina-ai/node-deepresearch/blob/main/src/utils/token-tracker.ts"
    click ActionTracker "https://github.com/jina-ai/node-deepresearch/blob/main/src/utils/action-tracker.ts"
    click SafeGenerator "https://github.com/jina-ai/node-deepresearch/blob/main/src/utils/safe-generator.ts"

    %% Click Events for Configuration & Environment
    click GlobalConfig "https://github.com/jina-ai/node-deepresearch/blob/main/config.json"
    click DockerCompose "https://github.com/jina-ai/node-deepresearch/blob/main/docker-compose.yml"
    click TSConfig "https://github.com/jina-ai/node-deepresearch/blob/main/tsconfig.json"
    click JinaConfig "https://github.com/jina-ai/node-deepresearch/blob/main/jina-ai/config.json"
```
