# internlm/mindsearch architecture

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

- Interactive diagram: https://gitdiagram.com/internlm/mindsearch
- Repository: https://github.com/internlm/mindsearch

## Overview

##### Project Type and Purpose
- MindSearch is a full-stack AI search application that exposes a FastAPI backend (“mindsearch.app”) running an LLM-based agent pipeline, offers multiple frontend interfaces (React SPA, Gradio, Streamlit), and provides a CLI Docker helper (“docker/msdl”) to scaffold and manage containerized deployments. Its core function is to accept user queries, perform concurrent sub-searches via external web-search APIs, feed results into an LLM agent, and render structured “mind-map” answers.

##### File Structure
─ Top-level files & dirs:
- mindsearch/            – Python package with agent modules, FastAPI app, terminal interface
- frontend/React         – React + Vite SPA implementing the primary GUI
- frontend/gradio_agentchatbot & mindsearch_gradio.py – Gradio interface
- frontend/mindsearch_streamlit.py – Streamlit interface
- docker/msdl            – CLI tool to generate Dockerfiles, docker‐compose templates, and manage container lifecycles
- backend_example.py     – Script showing how to call the FastAPI backend directly
- Dockerfile, .dockerignore, docker/** – Root Docker setup and advanced Docker-template engine
- requirements.txt, .env.example – Python dependencies and environment setup
─ Patterns & choices:
- “agent” subfolder implements the pipeline: graph building, prompt templates, streaming
- Separation between UI clients (HTTP/JS) and Python backend (FastAPI + Pydantic)
- Plugin-style support for different search engines and LLM formats

##### README for Additional Insights
- Backend startup flags control language, model format (internlm_server, gpt4), search‐engine plugin, and async agent deployment.
- Frontend options: React SPA via Vite proxy, Gradio server script, Streamlit script.
- Docker CLI (“msdl”) is documented under docker/README.md—for generating end‐to‐end container stacks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        ReactSPA["React SPA"]:::frontend
        GradioDir["Gradio Interface"]:::frontend
        GradioScript["mindsearch_gradio.py"]:::frontend
        Streamlit["Streamlit App"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        FastAPIApp["FastAPI Server"]:::backend
        subgraph "Agent Pipeline"
            SearchAdapter["Search Adapter"]:::agent
            LLMInterface["LLM Orchestrator"]:::agent
            PromptModule["Prompt Templates"]:::agent
            StreamingHandler["Streaming Handler"]:::agent
        end
    end

    %% External Services
    subgraph "External Services"
        WebSearchAPI["Web Search API"]:::external
        ModelServer["LLM Model Server"]:::external
    end

    %% Deployment Tooling
    subgraph "Deployment Tooling"
        MSdlMain["msdl CLI"]:::infra
        MSdlConfig["config.py"]:::infra
        MSdlManager["docker_manager.py"]:::infra
        MSdlUI["user_interaction.py"]:::infra
        MSdlUtils["utils.py"]:::infra
        MSdlTemplates["templates/"]:::infra
        Dockerfile["Dockerfile"]:::infra
        DockerIgnore[".dockerignore"]:::infra
        DockerReadme["docker/README.md"]:::infra
    end

    %% Example and Config
    BackendExample["backend_example.py"]:::infra
    Requirements["requirements.txt"]:::infra
    EnvExample[".env.example"]:::infra

    %% Data Flows
    ReactSPA -->|"POST /query"| FastAPIApp
    GradioDir -->|"POST /query"| FastAPIApp
    GradioScript -->|"POST /query"| FastAPIApp
    Streamlit -->|"POST /query"| FastAPIApp

    FastAPIApp -->|"dispatch to pipeline"| SearchAdapter
    FastAPIApp -->|"dispatch to pipeline"| LLMInterface

    SearchAdapter -->|"search_request"| WebSearchAPI
    WebSearchAPI -->|"results"| SearchAdapter

    PromptModule -->|"assemble prompt"| LLMInterface
    LLMInterface -->|"LLM_stream"| StreamingHandler
    StreamingHandler -->|"streamed response"| FastAPIApp

    FastAPIApp -->|"response JSON/stream"| ReactSPA
    FastAPIApp -->|"response JSON/stream"| GradioDir
    FastAPIApp -->|"response JSON/stream"| Streamlit

    MSdlMain --> MSdlConfig
    MSdlMain --> MSdlManager
    MSdlMain --> MSdlUI
    MSdlMain --> MSdlUtils
    MSdlMain --> MSdlTemplates
    MSdlMain --> Dockerfile
    MSdlMain --> DockerIgnore
    MSdlMain --> DockerReadme

    MSdlMain -.->|"generates containers"| ReactSPA
    MSdlMain -.-> ReactSPA
    MSdlMain -.-> FastAPIApp
    MSdlMain -.-> ModelServer

    %% Additional
    BackendExample --> FastAPIApp

    %% Click Events
    click ReactSPA "https://github.com/internlm/mindsearch/tree/main/frontend/React"
    click GradioDir "https://github.com/internlm/mindsearch/tree/main/frontend/gradio_agentchatbot"
    click GradioScript "https://github.com/internlm/mindsearch/blob/main/frontend/mindsearch_gradio.py"
    click Streamlit "https://github.com/internlm/mindsearch/blob/main/frontend/mindsearch_streamlit.py"
    click FastAPIApp "https://github.com/internlm/mindsearch/blob/main/mindsearch/app.py"
    click FastAPIApp "https://github.com/internlm/mindsearch/blob/main/mindsearch/__init__.py"
    click SearchAdapter "https://github.com/internlm/mindsearch/blob/main/mindsearch/agent/graph.py"
    click Agent "https://github.com/internlm/mindsearch/blob/main/mindsearch/agent/mindsearch_agent.py"
    click PromptModule "https://github.com/internlm/mindsearch/blob/main/mindsearch/agent/mindsearch_prompt.py"
    click Models "https://github.com/internlm/mindsearch/blob/main/mindsearch/agent/models.py"
    click StreamingHandler "https://github.com/internlm/mindsearch/blob/main/mindsearch/agent/streaming.py"
    click MSdlMain "https://github.com/internlm/mindsearch/blob/main/docker/msdl/__main__.py"
    click MSdlConfig "https://github.com/internlm/mindsearch/blob/main/docker/msdl/config.py"
    click MSdlManager "https://github.com/internlm/mindsearch/blob/main/docker/msdl/docker_manager.py"
    click MSdlUI "https://github.com/internlm/mindsearch/blob/main/docker/msdl/user_interaction.py"
    click MSdlUtils "https://github.com/internlm/mindsearch/blob/main/docker/msdl/utils.py"
    click MSdlTemplates "https://github.com/internlm/mindsearch/tree/main/docker/msdl/templates/"
    click Dockerfile "https://github.com/internlm/mindsearch/tree/main/Dockerfile"
    click DockerIgnore "https://github.com/internlm/mindsearch/blob/main/.dockerignore"
    click DockerReadme "https://github.com/internlm/mindsearch/blob/main/docker/README.md"
    click BackendExample "https://github.com/internlm/mindsearch/blob/main/backend_example.py"
    click Requirements "https://github.com/internlm/mindsearch/blob/main/requirements.txt"
    click EnvExample "https://github.com/internlm/mindsearch/blob/main/.env.example"

    %% Class Definitions
    classDef frontend fill:#D6EAF8,stroke:#1B4F72,color:#1B4F72
    classDef backend fill:#D5F5E3,stroke:#196F3D,color:#196F3D
    classDef agent fill:#FCF3CF,stroke:#B7950B,color:#7D6608
    classDef external fill:#FDEDEC,stroke:#C0392B,color:#641E16
    classDef infra fill:#E5E8E8,stroke:#566573,color:#17202A
```
