# waseens/deep-search-pro architecture

> Architecture diagram of the GitHub repository waseens/deep-search-pro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/waseens/deep-search-pro
- Repository: https://github.com/waseens/deep-search-pro

## Overview

Deep Search Pro is a multi-agent research assistant with a browser chat console and a run-trace diagnostics page. Users can upload reference files, submit a query, and receive a Markdown report or generated files; the main agent coordinates network search, database, and knowledge-base agents. FastAPI starts runs and serves live and recoverable trace events, which the frontend renders. The README documents optional database and RAGFlow capabilities; sampled code confirms several agent/tool and trace-store relationships, while some frontend wiring is supported only by the README.

Main entry points: [`agent/main_agent.py`](https://github.com/waseens/deep-search-pro/blob/master/agent/main_agent.py) (Main agent), [`api/server.py`](https://github.com/waseens/deep-search-pro/blob/master/api/server.py) (FastAPI server), [`web/run-client.js`](https://github.com/waseens/deep-search-pro/blob/master/web/run-client.js) (Run lifecycle), [`api/monitor.py`](https://github.com/waseens/deep-search-pro/blob/master/api/monitor.py) (Trace monitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web console"]
  node_chat["Chat console<br/>[chat.js]"]
  node_traceui["Trace console<br/>[app.js]"]
  node_runclient["Run lifecycle<br/>[run-client.js]"]
  node_session["Session recovery<br/>[session.js]"]
  node_visualizer["Trace visualizer<br/>[visualizer.js]"]
end

subgraph group_api["API and tracing"]
  node_server["FastAPI server<br/>[server.py]"]
  node_router["Trace query API<br/>[trace_router.py]"]
  node_monitor["Trace monitor<br/>[monitor.py]"]
  node_store[("Run trace store<br/>[trace_store.py]")]
  node_models["Trace models<br/>[trace_models.py]"]
end

subgraph group_agents["Agent orchestration"]
  node_main["Main agent<br/>[main_agent.py]"]
  node_llm["LLM setup<br/>[llm.py]"]
  node_prompts["Prompt loading<br/>[prompts.py]"]
  node_network["Network agent"]
  node_databaseagent["Database agent"]
  node_knowledge["Knowledge agent"]
end

subgraph group_tools["Research and output tools"]
  node_searchtool["Web search<br/>[tavily_tool.py]"]
  node_dbtools["SQL tools<br/>[db_tools.py]"]
  node_ragtool["RAGFlow retrieval<br/>[ragflow_tools.py]"]
  node_uploadtool["Upload reader"]
  node_markdown["Markdown report<br/>[markdown_tools.py]"]
  node_pdf["PDF conversion<br/>[pdf_tools.py]"]
end

subgraph group_support["Runtime support"]
  node_context["Run context<br/>[context.py]"]
  node_ragconfig["RAGFlow settings<br/>[rag_config.py]"]
  node_pathutils["Path safety<br/>[path_utils.py]"]
  node_word["Word conversion<br/>[word_converter.py]"]
end

node_user(("User"))
node_external_llm{{"LLM service"}}
node_tavily{{"Tavily service"}}
node_mysql[("MySQL")]
node_ragflow{{"RAGFlow service"}}

node_user -->|"submits query"| node_chat
node_user -->|"submits query"| node_traceui
node_chat -->|"starts run"| node_runclient
node_traceui -->|"starts run"| node_runclient
node_runclient -->|"uploads and starts"| node_server
node_server -->|"runs agent"| node_main
node_main -->|"dispatches"| node_network
node_main -->|"dispatches"| node_databaseagent
node_main -->|"dispatches"| node_knowledge
node_network -->|"uses"| node_searchtool
node_databaseagent -->|"uses"| node_dbtools
node_knowledge -->|"uses"| node_ragtool
node_main -->|"generates report"| node_markdown
node_main -->|"converts report"| node_pdf
node_main -->|"reads uploads"| node_uploadtool
node_main -->|"initializes"| node_llm
node_main -->|"loads prompts"| node_prompts
node_main -->|"emits events"| node_monitor
node_server -->|"reserves run"| node_store
node_server -->|"mounts routes"| node_router
node_router -->|"queries runs"| node_store
node_monitor -->|"persists events"| node_store
node_monitor -->|"broadcasts WebSocket"| node_server
node_monitor -->|"reads run context"| node_context
node_store -->|"stores events"| node_models
node_router -->|"returns responses"| node_models
node_server -->|"connects WebSocket"| node_monitor
node_runclient -->|"recovers session"| node_session
node_traceui -->|"renders trace"| node_visualizer
node_runclient -->|"recovers events"| node_server
node_llm -.->|"calls"| node_external_llm
node_searchtool -.->|"searches"| node_tavily
node_dbtools -.->|"queries"| node_mysql
node_ragtool -->|"retrieves"| node_ragflow
node_ragtool -->|"loads settings"| node_ragconfig
node_uploadtool -->|"resolves paths"| node_pathutils
node_markdown -->|"resolves paths"| node_pathutils
node_pdf -->|"resolves paths"| node_pathutils
node_pdf -->|"converts documents"| node_word

click node_chat "https://github.com/waseens/deep-search-pro/blob/master/web/chat.js"
click node_traceui "https://github.com/waseens/deep-search-pro/blob/master/web/app.js"
click node_runclient "https://github.com/waseens/deep-search-pro/blob/master/web/run-client.js"
click node_session "https://github.com/waseens/deep-search-pro/blob/master/web/session.js"
click node_visualizer "https://github.com/waseens/deep-search-pro/blob/master/web/visualizer.js"
click node_server "https://github.com/waseens/deep-search-pro/blob/master/api/server.py"
click node_router "https://github.com/waseens/deep-search-pro/blob/master/api/trace_router.py"
click node_monitor "https://github.com/waseens/deep-search-pro/blob/master/api/monitor.py"
click node_store "https://github.com/waseens/deep-search-pro/blob/master/api/trace_store.py"
click node_models "https://github.com/waseens/deep-search-pro/blob/master/api/trace_models.py"
click node_context "https://github.com/waseens/deep-search-pro/blob/master/api/context.py"
click node_main "https://github.com/waseens/deep-search-pro/blob/master/agent/main_agent.py"
click node_llm "https://github.com/waseens/deep-search-pro/blob/master/agent/llm.py"
click node_prompts "https://github.com/waseens/deep-search-pro/blob/master/agent/prompts.py"
click node_network "https://github.com/waseens/deep-search-pro/blob/master/agent/subagents/network_search_agent.py"
click node_databaseagent "https://github.com/waseens/deep-search-pro/blob/master/agent/subagents/database_query_agent.py"
click node_knowledge "https://github.com/waseens/deep-search-pro/blob/master/agent/subagents/knowledge_base_agent.py"
click node_searchtool "https://github.com/waseens/deep-search-pro/blob/master/tools/tavily_tool.py"
click node_dbtools "https://github.com/waseens/deep-search-pro/blob/master/tools/db_tools.py"
click node_ragtool "https://github.com/waseens/deep-search-pro/blob/master/tools/ragflow_tools.py"
click node_ragconfig "https://github.com/waseens/deep-search-pro/blob/master/rawflow/rag_config.py"
click node_uploadtool "https://github.com/waseens/deep-search-pro/blob/master/tools/upload_file_read_tool.py"
click node_markdown "https://github.com/waseens/deep-search-pro/blob/master/tools/markdown_tools.py"
click node_pdf "https://github.com/waseens/deep-search-pro/blob/master/tools/pdf_tools.py"
click node_pathutils "https://github.com/waseens/deep-search-pro/blob/master/utils/path_utils.py"
click node_word "https://github.com/waseens/deep-search-pro/blob/master/utils/word_converter.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_chat,node_traceui,node_runclient,node_session,node_visualizer,node_user toneBlue
class node_server,node_router,node_monitor,node_store,node_models,node_mysql toneAmber
class node_main,node_llm,node_prompts,node_network,node_databaseagent,node_knowledge toneMint
class node_searchtool,node_dbtools,node_ragtool,node_uploadtool,node_markdown,node_pdf toneRose
class node_context,node_ragconfig,node_pathutils,node_word,node_external_llm,node_tavily,node_ragflow toneIndigo
```

## Components

### Web console

- [Chat console](https://github.com/waseens/deep-search-pro/blob/master/web/chat.js): `web/chat.js`
- [Trace console](https://github.com/waseens/deep-search-pro/blob/master/web/app.js): `web/app.js`
- [Run lifecycle](https://github.com/waseens/deep-search-pro/blob/master/web/run-client.js): `web/run-client.js`
- [Session recovery](https://github.com/waseens/deep-search-pro/blob/master/web/session.js): `web/session.js`
- [Trace visualizer](https://github.com/waseens/deep-search-pro/blob/master/web/visualizer.js): `web/visualizer.js`

### API and tracing

- [FastAPI server](https://github.com/waseens/deep-search-pro/blob/master/api/server.py): `api/server.py`
- [Trace query API](https://github.com/waseens/deep-search-pro/blob/master/api/trace_router.py): `api/trace_router.py`
- [Trace monitor](https://github.com/waseens/deep-search-pro/blob/master/api/monitor.py): `api/monitor.py`
- [Run trace store](https://github.com/waseens/deep-search-pro/blob/master/api/trace_store.py): `api/trace_store.py`
- [Trace models](https://github.com/waseens/deep-search-pro/blob/master/api/trace_models.py): `api/trace_models.py`

### Agent orchestration

- [Main agent](https://github.com/waseens/deep-search-pro/blob/master/agent/main_agent.py): `agent/main_agent.py`
- [LLM setup](https://github.com/waseens/deep-search-pro/blob/master/agent/llm.py): `agent/llm.py`
- [Prompt loading](https://github.com/waseens/deep-search-pro/blob/master/agent/prompts.py): `agent/prompts.py`
- [Network agent](https://github.com/waseens/deep-search-pro/blob/master/agent/subagents/network_search_agent.py): `agent/subagents/network_search_agent.py`
- [Database agent](https://github.com/waseens/deep-search-pro/blob/master/agent/subagents/database_query_agent.py): `agent/subagents/database_query_agent.py`
- [Knowledge agent](https://github.com/waseens/deep-search-pro/blob/master/agent/subagents/knowledge_base_agent.py): `agent/subagents/knowledge_base_agent.py`

### Research and output tools

- [Web search](https://github.com/waseens/deep-search-pro/blob/master/tools/tavily_tool.py): `tools/tavily_tool.py`
- [SQL tools](https://github.com/waseens/deep-search-pro/blob/master/tools/db_tools.py): `tools/db_tools.py`
- [RAGFlow retrieval](https://github.com/waseens/deep-search-pro/blob/master/tools/ragflow_tools.py): `tools/ragflow_tools.py`
- [Upload reader](https://github.com/waseens/deep-search-pro/blob/master/tools/upload_file_read_tool.py): `tools/upload_file_read_tool.py`
- [Markdown report](https://github.com/waseens/deep-search-pro/blob/master/tools/markdown_tools.py): `tools/markdown_tools.py`
- [PDF conversion](https://github.com/waseens/deep-search-pro/blob/master/tools/pdf_tools.py): `tools/pdf_tools.py`

### Runtime support

- [Run context](https://github.com/waseens/deep-search-pro/blob/master/api/context.py): `api/context.py`
- [RAGFlow settings](https://github.com/waseens/deep-search-pro/blob/master/rawflow/rag_config.py): `rawflow/rag_config.py`
- [Path safety](https://github.com/waseens/deep-search-pro/blob/master/utils/path_utils.py): `utils/path_utils.py`
- [Word conversion](https://github.com/waseens/deep-search-pro/blob/master/utils/word_converter.py): `utils/word_converter.py`

### Other components

- **User**
- **LLM service**
- **Tavily service**
- **MySQL**
- **RAGFlow service**

## Connections

- User → Chat console: submits query (evidence: `README.md`)
- User → Trace console: submits query (evidence: `README.md`)
- Chat console → Run lifecycle: starts run (evidence: `README.md`)
- Trace console → Run lifecycle: starts run (evidence: `README.md`)
- Run lifecycle → FastAPI server: uploads and starts (evidence: `README.md`)
- FastAPI server → Main agent: runs agent (evidence: `api/server.py`)
- Main agent → Network agent: dispatches (evidence: `agent/main_agent.py`)
- Main agent → Database agent: dispatches (evidence: `agent/main_agent.py`)
- Main agent → Knowledge agent: dispatches (evidence: `agent/main_agent.py`)
- Network agent → Web search: uses (evidence: `agent/subagents/network_search_agent.py`)
- Database agent → SQL tools: uses (evidence: `agent/subagents/database_query_agent.py`)
- Knowledge agent → RAGFlow retrieval: uses (evidence: `agent/subagents/knowledge_base_agent.py`)
- Main agent → Markdown report: generates report (evidence: `agent/main_agent.py`)
- Main agent → PDF conversion: converts report (evidence: `agent/main_agent.py`)
- Main agent → Upload reader: reads uploads (evidence: `README.md`)
- Main agent → LLM setup: initializes (evidence: `agent/main_agent.py`)
- Main agent → Prompt loading: loads prompts (evidence: `agent/main_agent.py`)
- Main agent → Trace monitor: emits events (evidence: `agent/main_agent.py`)
- FastAPI server → Run trace store: reserves run (evidence: `api/server.py`)
- FastAPI server → Trace query API: mounts routes (evidence: `api/server.py`)
- Trace query API → Run trace store: queries runs (evidence: `api/trace_router.py`)
- Trace monitor → Run trace store: persists events (evidence: `api/monitor.py`)
- Trace monitor → FastAPI server: broadcasts WebSocket (evidence: `README.md`)
- Trace monitor → Run context: reads run context (evidence: `api/monitor.py`)
- Run trace store → Trace models: stores events (evidence: `api/trace_store.py`)
- Trace query API → Trace models: returns responses (evidence: `api/trace_router.py`)
- FastAPI server → Trace monitor: connects WebSocket (evidence: `api/server.py`)
- Run lifecycle → Session recovery: recovers session (evidence: `README.md`)
- Trace console → Trace visualizer: renders trace (evidence: `README.md`)
- Run lifecycle → FastAPI server: recovers events (evidence: `README.md`)
- LLM setup → LLM service: calls
- Web search → Tavily service: searches
- SQL tools → MySQL: queries
- RAGFlow retrieval → RAGFlow service: retrieves (evidence: `tools/ragflow_tools.py`)
- RAGFlow retrieval → RAGFlow settings: loads settings (evidence: `tools/ragflow_tools.py`)
- Upload reader → Path safety: resolves paths (evidence: `tools/upload_file_read_tool.py`)
- Markdown report → Path safety: resolves paths (evidence: `tools/markdown_tools.py`)
- PDF conversion → Path safety: resolves paths (evidence: `tools/pdf_tools.py`)
- PDF conversion → Word conversion: converts documents (evidence: `tools/pdf_tools.py`)