# gwerr1002/deepsearch architecture

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

- Interactive diagram: https://gitdiagram.com/gwerr1002/deepsearch
- Repository: https://github.com/gwerr1002/deepsearch

## Overview

Deep Search is a local, iterative research assistant: it analyzes a research task, generates and runs successive web queries, assesses candidate sources and evidence, then synthesizes a cited answer. The main orchestration and several stages are visible in partial excerpts; other stage boundaries are inferred from the documented prompt roles and workflow method names. Source opening is represented through the available web-fetch tool, though its exact invocation is not visible in the excerpt.

Main entry points: [`app/agent/agent.py`](https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py) (Workflow orchestrator), [`app/llm/ollama.py`](https://github.com/gwerr1002/deepsearch/blob/main/app/llm/ollama.py) (Ollama client), [`app/config/syspromt.py`](https://github.com/gwerr1002/deepsearch/blob/main/app/config/syspromt.py) (Research prompts), [`app/agent/tools.py`](https://github.com/gwerr1002/deepsearch/blob/main/app/agent/tools.py) (Web tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Research workflow"]
  node_entry["CLI entry<br/>[main.py]"]
  node_orchestrator["Workflow orchestrator<br/>[agent.py]"]
  node_analyze["Task analysis<br/>[agent.py]"]
  node_query["Query generation<br/>[agent.py]"]
  node_searchstage["Search iteration<br/>[agent.py]"]
  node_select["Source selection<br/>[agent.py]"]
  node_evidence["Evidence evaluation<br/>[agent.py]"]
  node_open["Source opening<br/>[agent.py]"]
  node_summary["Answer synthesis<br/>[agent.py]"]
end

subgraph group_retrieval["Web retrieval"]
  node_tools["Web tools<br/>[tools.py]"]
  node_searchadapter["Search adapter<br/>[searxng.py]"]
  node_fetch["Page and PDF fetch<br/>[web.py]"]
end

subgraph group_model["Model and configuration"]
  node_llmclient["Ollama client<br/>[ollama.py]"]
  node_prompts["Research prompts<br/>[syspromt.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

subgraph group_support["Internal support"]
  node_scoring["Keyword scoring<br/>[scoring.py]"]
  node_tokens["Token utilities<br/>[tokens.py]"]
end

node_user(("Research task"))
node_ollama(("Ollama service"))
node_searx(("SearXNG service"))
node_web(("Web sources"))

node_user -->|"provides task"| node_entry
node_entry -->|"starts"| node_orchestrator
node_orchestrator -->|"dispatches"| node_analyze
node_orchestrator -->|"dispatches"| node_query
node_orchestrator -->|"dispatches"| node_searchstage
node_orchestrator -->|"dispatches"| node_select
node_orchestrator -->|"dispatches"| node_evidence
node_orchestrator -->|"dispatches"| node_open
node_orchestrator -->|"dispatches"| node_summary
node_analyze -->|"requests analysis"| node_llmclient
node_query -->|"requests query"| node_llmclient
node_select -->|"evaluates results"| node_llmclient
node_evidence -->|"evaluates evidence"| node_llmclient
node_summary -->|"requests synthesis"| node_llmclient
node_searchstage -->|"searches query"| node_tools
node_tools -->|"calls search"| node_searchadapter
node_searchadapter -->|"requests results"| node_searx
node_searx -->|"returns results"| node_searchadapter
node_searchstage -->|"scores results"| node_scoring
node_open -->|"opens sources"| node_tools
node_tools -->|"fetches page"| node_fetch
node_fetch -->|"requests content"| node_web
node_llmclient -->|"sends chat"| node_ollama
node_ollama -->|"returns response"| node_llmclient
node_analyze -->|"reads task settings"| node_settings
node_query -->|"uses query prompt"| node_prompts
node_analyze -->|"uses analysis prompt"| node_prompts
node_select -->|"uses evaluator prompt"| node_prompts
node_evidence -->|"uses evidence prompt"| node_prompts
node_summary -->|"uses answer prompt"| node_prompts
node_orchestrator -->|"counts tokens"| node_tokens

click node_entry "https://github.com/gwerr1002/deepsearch/blob/main/app/main.py"
click node_orchestrator "https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py"
click node_analyze "https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py"
click node_query "https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py"
click node_searchstage "https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py"
click node_select "https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py"
click node_evidence "https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py"
click node_open "https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py"
click node_summary "https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py"
click node_tools "https://github.com/gwerr1002/deepsearch/blob/main/app/agent/tools.py"
click node_searchadapter "https://github.com/gwerr1002/deepsearch/blob/main/app/search/searxng.py"
click node_fetch "https://github.com/gwerr1002/deepsearch/blob/main/app/search/web.py"
click node_scoring "https://github.com/gwerr1002/deepsearch/blob/main/app/search/scoring.py"
click node_llmclient "https://github.com/gwerr1002/deepsearch/blob/main/app/llm/ollama.py"
click node_prompts "https://github.com/gwerr1002/deepsearch/blob/main/app/config/syspromt.py"
click node_settings "https://github.com/gwerr1002/deepsearch/blob/main/app/config/config.py"
click node_tokens "https://github.com/gwerr1002/deepsearch/blob/main/app/llm/tokens.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_entry,node_orchestrator,node_analyze,node_query,node_searchstage,node_select,node_evidence,node_open,node_summary toneBlue
class node_tools,node_searchadapter,node_fetch toneAmber
class node_llmclient,node_prompts,node_settings toneMint
class node_scoring,node_tokens,node_user toneRose
class node_ollama,node_searx,node_web toneIndigo
```

## Components

### Research workflow

- [CLI entry](https://github.com/gwerr1002/deepsearch/blob/main/app/main.py): `app/main.py`
- [Workflow orchestrator](https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py): `app/agent/agent.py`
- [Task analysis](https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py): `app/agent/agent.py`
- [Query generation](https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py): `app/agent/agent.py`
- [Search iteration](https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py): `app/agent/agent.py`
- [Source selection](https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py): `app/agent/agent.py`
- [Evidence evaluation](https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py): `app/agent/agent.py`
- [Source opening](https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py): `app/agent/agent.py`
- [Answer synthesis](https://github.com/gwerr1002/deepsearch/blob/main/app/agent/agent.py): `app/agent/agent.py`

### Web retrieval

- [Web tools](https://github.com/gwerr1002/deepsearch/blob/main/app/agent/tools.py): `app/agent/tools.py`
- [Search adapter](https://github.com/gwerr1002/deepsearch/blob/main/app/search/searxng.py): `app/search/searxng.py`
- [Page and PDF fetch](https://github.com/gwerr1002/deepsearch/blob/main/app/search/web.py): `app/search/web.py`

### Model and configuration

- [Ollama client](https://github.com/gwerr1002/deepsearch/blob/main/app/llm/ollama.py): `app/llm/ollama.py`
- [Research prompts](https://github.com/gwerr1002/deepsearch/blob/main/app/config/syspromt.py): `app/config/syspromt.py`
- [Runtime settings](https://github.com/gwerr1002/deepsearch/blob/main/app/config/config.py): `app/config/config.py`

### Internal support

- [Keyword scoring](https://github.com/gwerr1002/deepsearch/blob/main/app/search/scoring.py): `app/search/scoring.py`
- [Token utilities](https://github.com/gwerr1002/deepsearch/blob/main/app/llm/tokens.py): `app/llm/tokens.py`

### Other components

- **Research task**
- **Ollama service**
- **SearXNG service**
- **Web sources**

## Connections

- Research task → CLI entry: provides task
- CLI entry → Workflow orchestrator: starts
- Workflow orchestrator → Task analysis: dispatches
- Workflow orchestrator → Query generation: dispatches
- Workflow orchestrator → Search iteration: dispatches
- Workflow orchestrator → Source selection: dispatches
- Workflow orchestrator → Evidence evaluation: dispatches
- Workflow orchestrator → Source opening: dispatches
- Workflow orchestrator → Answer synthesis: dispatches
- Task analysis → Ollama client: requests analysis
- Query generation → Ollama client: requests query
- Source selection → Ollama client: evaluates results
- Evidence evaluation → Ollama client: evaluates evidence
- Answer synthesis → Ollama client: requests synthesis
- Search iteration → Web tools: searches query
- Web tools → Search adapter: calls search
- Search adapter → SearXNG service: requests results
- SearXNG service → Search adapter: returns results
- Search iteration → Keyword scoring: scores results
- Source opening → Web tools: opens sources
- Web tools → Page and PDF fetch: fetches page
- Page and PDF fetch → Web sources: requests content
- Ollama client → Ollama service: sends chat
- Ollama service → Ollama client: returns response
- Task analysis → Runtime settings: reads task settings
- Query generation → Research prompts: uses query prompt
- Task analysis → Research prompts: uses analysis prompt
- Source selection → Research prompts: uses evaluator prompt
- Evidence evaluation → Research prompts: uses evidence prompt
- Answer synthesis → Research prompts: uses answer prompt
- Workflow orchestrator → Token utilities: counts tokens