# pacovk/ollama-deep-researcher-ts architecture

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

- Interactive diagram: https://gitdiagram.com/pacovk/ollama-deep-researcher-ts
- Repository: https://github.com/pacovk/ollama-deep-researcher-ts

## Overview

##### Main Components
a. Agent Module:
- Located in src/agent, this module handles crucial functionality such as managing configurations (src/agent/configuration.ts), keeping graph state (src/agent/graph.ts), handling prompts (src/agent/prompts.ts) and tracking state (src/agent/state.ts).
- It is the orchestrator that triggers and tracks the iterative research workflow.

b. Nodes (Processing Steps):
- Found in src/nodes, the nodes represent the individual steps of the research process:
- generateQuery: Creates the web search query using the local LLM.
- webResearch: Invokes a search engine (via Tavily) to retrieve search results.
- summarizeSources: Summarizes the collected search results.
- reflectSummary: Analyses the summary to identify knowledge gaps.
- finalizeSummary: Produces the final markdown summary that includes the research findings.

c. Routing / API Layer:
- In src/route, specifically src/route/research.ts, this part likely exposes an interface (e.g., a REST API endpoint) to trigger the research process.

d. External Integrations:
- Local LLM via Ollama: Configured in the agent configuration to hit endpoints like “http://localhost:11434” and set to pull models (e.g., deepseek-r1).
- Tavily API: Used for performing web searches as part of the research nodes.
- LangGraph Studio: The project integrates with LangGraph’s visualization and graph state management, as suggested by the docker-compose setup and references in the README.

e. Infrastructure and Deployment:
- Docker & docker-compose: The docker files (docker/Dockerfile and docker-compose.yml) indicate containerized deployment.
- Configuration files (.env.example, tsconfig.json, package.json, etc.) set up the environment for running TypeScript and Docker.
- CI/CD: The GitHub workflows (under .github/workflows) for unit tests indicate automated testing integration.

##### Relationships and Interactions
- How the Agent Module interacts with each “Node” in sequence:
- generateQuery → webResearch → summarizeSources → reflectSummary → finalizeSummary.
- “Agent Module” to external systems:
- How the output from nodes gets accumulated and stored in the “Graph State”, which is then visualized in LangGraph Studio.
- Use of Docker containers (deployment boundaries) via a container for the LangGraph server and possibly separate containers for the assistant.

##### Architectural Patterns and Design Principles
- The design resembles a pipeline or workflow orchestration where each node performs an independent step in the research process.
- There is a clear separation of concerns:
- Agent manages the overall workflow.
- Nodes perform specific, testable functions.
- Routing isolates the API layer from business logic.
- Containerization with Docker is used to ensure a reproducible environment across development and deployment.

##### Technologies, Frameworks, and Libraries
- TypeScript serves as the main programming language.
- Docker and docker-compose for container orchestration.
- LangGraph framework for visualizing and running the graph-based research workflow.
- ESLint, Jest (jest.config.js), and configuration files to enforce code standards and enable testing.
- External APIs – Ollama (for LLM processing) and Tavily (for web search).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    User("User Input"):::external
    API("API/Route (research.ts)"):::internal

    %% API Layer
    User -->|"triggers"| API

    %% Agent Module Subgraph
    subgraph "Agent Module"
        AgentConfig("Configuration"):::internal
        AgentGraph("Graph State"):::internal
        AgentPrompts("Prompts"):::internal
        AgentState("State"):::internal
    end

    %% Connection from API to Agent Module (using Configuration as entry point)
    API -->|"initiates"| AgentConfig

    %% Agent Module to Processing Nodes connection (using State as representative)
    AgentState -->|"orchestrates"| N1

    %% Processing Nodes Subgraph
    subgraph "Processing Nodes"
        N1("generateQuery"):::processing
        N2("webResearch"):::processing
        N3("summarizeSources"):::processing
        N4("reflectSummary"):::processing
        N5("finalizeSummary"):::processing
    end

    %% Processing flow
    N1 -->|"next"| N2
    N2 -->|"next"| N3
    N3 -->|"next"| N4
    N4 -->|"next"| N5
    N4 -- "iterate" --> N1

    %% External Integrations
    LLM("LLM Service (Ollama)"):::external
    WebAPI("Web Search API (Tavily)"):::external
    LangGraph("LangGraph Studio Visualization"):::external

    %% Connections to External Services
    N1 -->|"calls"| LLM
    N2 -->|"calls"| WebAPI
    N5 -->|"outputs"| LangGraph
    AgentGraph -->|"updates"| LangGraph

    %% Infrastructure & Deployment Subgraph
    subgraph "Infrastructure & Deployment"
        Dockerfile("Dockerfile"):::infra
        DockerCompose("docker-compose"):::infra
        EnvConfig(".env, tsconfig, package.json"):::infra
        LangGraphIntegration("LangGraph Integration"):::infra
    end

    %% Infrastructure supporting connections (dashed arrows)
    Dockerfile -.->|"builds"| AgentState
    DockerCompose -.->|"orchestrates"| AgentState
    EnvConfig -.->|"configures"| AgentState
    LangGraphIntegration -.->|"integrates"| LangGraph

    %% Styles
    classDef internal fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef processing fill:#98fb98,stroke:#000,stroke-width:2px;
    classDef external fill:#ffcccb,stroke:#000,stroke-width:2px;
    classDef infra fill:#fcebcc,stroke:#000,stroke-width:2px;

    %% Click Events
    click AgentConfig "https://github.com/pacovk/ollama-deep-researcher-ts/blob/main/src/agent/configuration.ts"
    click AgentGraph "https://github.com/pacovk/ollama-deep-researcher-ts/blob/main/src/agent/graph.ts"
    click AgentPrompts "https://github.com/pacovk/ollama-deep-researcher-ts/blob/main/src/agent/prompts.ts"
    click AgentState "https://github.com/pacovk/ollama-deep-researcher-ts/blob/main/src/agent/state.ts"
    click N1 "https://github.com/pacovk/ollama-deep-researcher-ts/blob/main/src/nodes/generateQuery.ts"
    click N2 "https://github.com/pacovk/ollama-deep-researcher-ts/blob/main/src/nodes/webResearch.ts"
    click N3 "https://github.com/pacovk/ollama-deep-researcher-ts/blob/main/src/nodes/summarizeSources.ts"
    click N4 "https://github.com/pacovk/ollama-deep-researcher-ts/blob/main/src/nodes/reflectSummary.ts"
    click N5 "https://github.com/pacovk/ollama-deep-researcher-ts/blob/main/src/nodes/finalizeSummary.ts"
    click API "https://github.com/pacovk/ollama-deep-researcher-ts/blob/main/src/route/research.ts"
    click Dockerfile "https://github.com/pacovk/ollama-deep-researcher-ts/tree/main/docker/Dockerfile"
    click DockerCompose "https://github.com/pacovk/ollama-deep-researcher-ts/blob/main/docker-compose.yml"
    click EnvConfig "https://github.com/pacovk/ollama-deep-researcher-ts/blob/main/.env.example"
    click LangGraphIntegration "https://github.com/pacovk/ollama-deep-researcher-ts/blob/main/langgraph.json"
```
