# langchain-ai/local-deep-researcher architecture

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

- Interactive diagram: https://gitdiagram.com/langchain-ai/local-deep-researcher
- Repository: https://github.com/langchain-ai/local-deep-researcher

## Overview

- User Interface / Client: Represent the LangGraph Studio UI and any browser-based interaction points. Include a note about browser compatibility (i.e., Firefox recommended, issues with Safari, etc.).
- Configuration & Environment:
- .env file (environment variables)
- Configuration module (configuration.py) that sets defaults supported by user overrides from the environment and LangGraph UI.
- Core Application / Orchestration:
- Graph Workflow Engine: Represent the iterative research loop (query generation, web search, summarization, reflection, and subsequent querying). List the following modules with their roles:
▪ lmstudio.py – managing interactions with the LLM (the module name indicates support for LMStudio, but configuration supports switching to Ollama).
▪ prompts.py – holds the various prompts for query generation and summarization.
▪ graph.py – orchestrates the relationship between queries, search results, and summary updates.
▪ state.py – tracks the evolving state of the research including aggregated sources and summary.
- Utility module (utils.py) – used for miscellaneous tasks that support the core functions.
- External Dependencies / Services:
- Deployment & Build Infrastructure:
- CI/CD Integration: Briefly note the GitHub workflows (.github/workflows/docker-image.yml) for automated builds and deployments.
- LangGraph Server: Show that the project can be launched via LangGraph (internal server component) with details on virtual environments and relevant commands.

##### Establish the Relationships & Data Flow
- From this core engine, illustrate:
- A flow from the engine to the “LLM Provider” (Ollama or LMStudio) for generating the web search query and summarization tasks.
- A parallel flow from the engine to the “Search Engine API” to fetch documents.

##### Architectural Patterns & Design Principles
- Layered architecture:
▪ Presentation (LangGraph Studio UI)
▪ Orchestration (Graph engine with workflow components)
▪ External Service Integration (LLM and Search APIs)
- Configuration hierarchy (Environment variables > LangGraph UI config > Default values). Use annotations next to the configuration module.
- Plugin-like nature of external services, illustrating how the system is designed for extensibility (e.g., easy swap-out of LLM providers or search tools).

##### Relevant Technologies & Frameworks
- Python-based Application: The file tree under “src/ollama_deep_researcher” establishes that this is a Python project.
- Docker: For containerized deployment.
- LangGraph Studio: For visualizing and managing the workflow.
- External APIs: For the search and LLM interactions.
- GitHub Actions: As part of the CI/CD pipeline.

##### Final Detailed Overview
- This high-fidelity visual representation helps stakeholders (including the principal software engineer) quickly understand how research topics are processed locally, how configuration and external integrations work, and the modular architecture that supports future enhancements or integration with additional services.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["LangGraph Studio UI<br/>(Browser-based; Firefox recommended)"]:::frontend
    end

    %% Configuration & Environment
    subgraph "Configuration & Environment"
        ENV[".env file"]:::config
        CONFIG["Configuration Module<br/>(configuration.py)"]:::config
    end

    %% Core Application / Orchestration
    subgraph "Graph Workflow Engine (Core Orchestration)"
        LM["LLM Interaction<br/>(lmstudio.py)"]:::orchestration
        PROMPTS["Prompt Management<br/>(prompts.py)"]:::orchestration
        GRAPH["Workflow Coordination<br/>(graph.py)"]:::orchestration
        STATE["State Tracking<br/>(state.py)"]:::orchestration
        UTILS["Utility Module<br/>(utils.py)"]:::orchestration
    end

    %% External Dependencies / Services
    subgraph "External Services"
        subgraph "Local LLM Providers"
            OLLAMA["Ollama"]:::external
            LMSTUDIO["LMStudio"]:::external
        end
        subgraph "Search Engine APIs"
            DUCK["DuckDuckGo"]:::external
            SEARXNG["SearXNG"]:::external
            TAVILY["Tavily"]:::external
            PERPLEXITY["Perplexity"]:::external
        end
    end

    %% Deployment & Build Infrastructure
    subgraph "Deployment & Build"
        DOCKER["Docker Container<br/>(Dockerfile)"]:::deployment
        CICD["CI/CD Integration<br/>(docker-image.yml)"]:::deployment
        SERVER["LangGraph Server<br/>(Internal Launch)"]:::deployment
    end

    %% Data Flow Connections
    UI -->|"submits research topic"| GRAPH
    ENV -->|"provides environment variables"| CONFIG
    CONFIG -->|"configures defaults & overrides"| GRAPH

    GRAPH -->|"invokes LLM Query"| LM
    LM -->|"communicates with"| OLLAMA
    LM -->|"or switches to"| LMSTUDIO

    GRAPH -->|"requests search results"| DUCK
    GRAPH -->|"requests search results"| SEARXNG
    GRAPH -->|"requests search results"| TAVILY
    GRAPH -->|"requests search results"| PERPLEXITY

    DUCK -->|"returns search data"| GRAPH
    SEARXNG -->|"returns search data"| GRAPH
    TAVILY -->|"returns search data"| GRAPH
    PERPLEXITY -->|"returns search data"| GRAPH

    GRAPH -->|"updates state & summarizes"| STATE
    PROMPTS -->|"supplies prompts for queries & summary"| GRAPH
    UTILS -->|"supports processing tasks"| GRAPH

    %% Iterative Loop Indicator
    GRAPH -->|"iterative processing"| GRAPH

    %% Final Output Flow
    GRAPH -->|"delivers markdown summary"| UI

    %% Deployment Flow (illustrative)
    DOCKER -->|"builds container for"| SERVER
    CICD -->|"automates build/deploy"| DOCKER

    %% Click Events
    click UI "https://github.com/langchain-ai/local-deep-researcher/blob/main/langgraph.json"
    click ENV "https://github.com/langchain-ai/local-deep-researcher/blob/main/.env.example"
    click CONFIG "https://github.com/langchain-ai/local-deep-researcher/blob/main/src/ollama_deep_researcher/configuration.py"
    click LM "https://github.com/langchain-ai/local-deep-researcher/blob/main/src/ollama_deep_researcher/lmstudio.py"
    click PROMPTS "https://github.com/langchain-ai/local-deep-researcher/blob/main/src/ollama_deep_researcher/prompts.py"
    click GRAPH "https://github.com/langchain-ai/local-deep-researcher/blob/main/src/ollama_deep_researcher/graph.py"
    click STATE "https://github.com/langchain-ai/local-deep-researcher/blob/main/src/ollama_deep_researcher/state.py"
    click UTILS "https://github.com/langchain-ai/local-deep-researcher/blob/main/src/ollama_deep_researcher/utils.py"
    click DOCKER "https://github.com/langchain-ai/local-deep-researcher/tree/main/Dockerfile"
    click CICD "https://github.com/langchain-ai/local-deep-researcher/blob/main/.github/workflows/docker-image.yml"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#007bff,stroke-width:2px,color:#000;
    classDef config fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef orchestration fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#dc3545,stroke-width:2px;
    classDef deployment fill:#d1ecf1,stroke:#17a2b8,stroke-width:2px;
```
