# blocknotes-4515/deepscope architecture

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

- Interactive diagram: https://gitdiagram.com/blocknotes-4515/deepscope
- Repository: https://github.com/blocknotes-4515/deepscope

## Overview

DEEPSCOPE turns a research topic into web findings, extracted page content, a structured report, and a critique. The command-line pipeline and Streamlit app are separate entry points; the pipeline explicitly owns the sequential calls and shared state. Search and scraping are implemented as tools, while agent/model setup and the writer and critic chains live in agents.py. The README documents the major stages; the app.py excerpt is partial, so its later-stage wiring is not mapped.

Main entry points: [`pipeline.py`](https://github.com/blocknotes-4515/deepscope/blob/main/pipeline.py) (Pipeline runner), [`app.py`](https://github.com/blocknotes-4515/deepscope/blob/main/app.py) (Research UI), [`agents.py`](https://github.com/blocknotes-4515/deepscope/blob/main/agents.py) (Search agent), [`tools.py`](https://github.com/blocknotes-4515/deepscope/blob/main/tools.py) (Web search tool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_streamlit["Research UI<br/>[app.py]"]
  node_pipeline["Pipeline runner<br/>[pipeline.py]"]
end

subgraph group_workflow["Research workflow"]
  node_state[("Research state<br/>[pipeline.py]")]
  node_search_agent["Search agent<br/>[agents.py]"]
  node_reader_agent["Reader agent<br/>[agents.py]"]
end

subgraph group_retrieval["Web retrieval"]
  node_web_search["Web search tool<br/>[tools.py]"]
  node_tavily{{"Tavily Search"}}
  node_scrape_url["Page scraper<br/>[tools.py]"]
  node_web_pages["Web pages"]
end

subgraph group_generation["Report generation"]
  node_writer["Writer chain<br/>[agents.py]"]
  node_critic["Critic chain<br/>[agents.py]"]
  node_llm{{"LLM providers"}}
end

node_researcher(("Researcher"))

node_researcher -->|"enters topic"| node_pipeline
node_researcher -.->|"submits topic"| node_streamlit
node_pipeline -->|"records findings"| node_state
node_pipeline -->|"invokes search"| node_search_agent
node_pipeline -->|"invokes reading"| node_reader_agent
node_pipeline -->|"invokes writing"| node_writer
node_pipeline -->|"invokes critique"| node_critic
node_search_agent -->|"uses tool"| node_web_search
node_web_search -->|"searches web"| node_tavily
node_reader_agent -->|"uses tool"| node_scrape_url
node_scrape_url -->|"fetches content"| node_web_pages
node_writer -->|"generates report"| node_llm
node_critic -->|"evaluates report"| node_llm
node_streamlit -->|"invokes search"| node_search_agent
node_streamlit -->|"invokes reading"| node_reader_agent

click node_streamlit "https://github.com/blocknotes-4515/deepscope/blob/main/app.py"
click node_pipeline "https://github.com/blocknotes-4515/deepscope/blob/main/pipeline.py"
click node_state "https://github.com/blocknotes-4515/deepscope/blob/main/pipeline.py"
click node_search_agent "https://github.com/blocknotes-4515/deepscope/blob/main/agents.py"
click node_reader_agent "https://github.com/blocknotes-4515/deepscope/blob/main/agents.py"
click node_web_search "https://github.com/blocknotes-4515/deepscope/blob/main/tools.py"
click node_scrape_url "https://github.com/blocknotes-4515/deepscope/blob/main/tools.py"
click node_writer "https://github.com/blocknotes-4515/deepscope/blob/main/agents.py"
click node_critic "https://github.com/blocknotes-4515/deepscope/blob/main/agents.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_streamlit,node_pipeline toneBlue
class node_state,node_search_agent,node_reader_agent toneAmber
class node_web_search,node_tavily,node_scrape_url,node_web_pages toneMint
class node_writer,node_critic,node_llm toneRose
class node_researcher toneIndigo
```

## Components

### Entry points

- [Research UI](https://github.com/blocknotes-4515/deepscope/blob/main/app.py): `app.py`
- [Pipeline runner](https://github.com/blocknotes-4515/deepscope/blob/main/pipeline.py): `pipeline.py`

### Research workflow

- [Research state](https://github.com/blocknotes-4515/deepscope/blob/main/pipeline.py): `pipeline.py`
- [Search agent](https://github.com/blocknotes-4515/deepscope/blob/main/agents.py): `agents.py`
- [Reader agent](https://github.com/blocknotes-4515/deepscope/blob/main/agents.py): `agents.py`

### Web retrieval

- [Web search tool](https://github.com/blocknotes-4515/deepscope/blob/main/tools.py): `tools.py`
- **Tavily Search**
- [Page scraper](https://github.com/blocknotes-4515/deepscope/blob/main/tools.py): `tools.py`
- **Web pages**

### Report generation

- [Writer chain](https://github.com/blocknotes-4515/deepscope/blob/main/agents.py): `agents.py`
- [Critic chain](https://github.com/blocknotes-4515/deepscope/blob/main/agents.py): `agents.py`
- **LLM providers**

### Other components

- **Researcher**

## Connections

- Researcher → Pipeline runner: enters topic (evidence: `pipeline.py`)
- Researcher → Research UI: submits topic (evidence: `README.md`)
- Pipeline runner → Research state: records findings (evidence: `pipeline.py`)
- Pipeline runner → Search agent: invokes search (evidence: `pipeline.py`)
- Pipeline runner → Reader agent: invokes reading (evidence: `pipeline.py`)
- Pipeline runner → Writer chain: invokes writing (evidence: `pipeline.py`)
- Pipeline runner → Critic chain: invokes critique (evidence: `pipeline.py`)
- Search agent → Web search tool: uses tool (evidence: `agents.py`)
- Web search tool → Tavily Search: searches web (evidence: `tools.py`)
- Reader agent → Page scraper: uses tool (evidence: `agents.py`)
- Page scraper → Web pages: fetches content (evidence: `tools.py`)
- Writer chain → LLM providers: generates report (evidence: `agents.py`)
- Critic chain → LLM providers: evaluates report (evidence: `agents.py`)
- Research UI → Search agent: invokes search (evidence: `app.py`)
- Research UI → Reader agent: invokes reading (evidence: `app.py`)
