# demigodmode/pi-web-agent architecture

> Architecture diagram of the GitHub repository demigodmode/pi-web-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/demigodmode/pi-web-agent
- Repository: https://github.com/demigodmode/pi-web-agent

## Overview

pi-web-agent is a Pi extension for bounded web research, centered on the `web_explore` tool: a user asks a question or supplies a URL, research orchestration discovers and fetches sources, evaluates evidence, then returns a bounded answer with caveats. The architecture also exposes standalone search and fetch tools, configurable providers and fallback, specialized content readers, guarded network access, and configurable presentation. Connections reflect excerpted calls, indexed imports, or README-documented capabilities; several provider and reader implementations were not sampled, so their internal dispatch details are not expanded.

Main entry points: [`src/tools/web-explore.ts`](https://github.com/demigodmode/pi-web-agent/blob/develop/src/tools/web-explore.ts) (Web explore), [`src/backends/factory.ts`](https://github.com/demigodmode/pi-web-agent/blob/develop/src/backends/factory.ts) (Backend factory), [`src/fetch`](https://github.com/demigodmode/pi-web-agent/tree/develop/src/fetch) (Fetch backends), [`src/orchestration/research-orchestrator.ts`](https://github.com/demigodmode/pi-web-agent/blob/develop/src/orchestration/research-orchestrator.ts) (Research orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Pi entrypoints"]
  node_extension["Extension setup<br/>[extension.ts]"]
  node_explore_tool["Web explore<br/>[web-explore.ts]"]
  node_search_tool["Web search<br/>[web-search.ts]"]
end

subgraph group_research["Research workflow"]
  node_orchestration_api["Research API<br/>[index.ts]"]
  node_orchestrator["Research orchestrator"]
  node_worker["Research worker<br/>[research-worker.ts]"]
  node_evidence["Evidence quality"]
  node_synthesis["Answer synthesis"]
end

subgraph group_providers["Search and backends"]
  node_backend_factory["Backend factory<br/>[factory.ts]"]
  node_search_providers["Search providers"]
  node_fanout["Search fanout<br/>[fanout.ts]"]
  node_fallback["Fallback policy<br/>[fallback-policy.ts]"]
end

subgraph group_content["Fetch and content"]
  node_fetchers["Fetch backends"]
  node_readers["Content readers"]
  node_extract["Content extraction<br/>[readability.ts]"]
  node_section_selector["Section selection"]
end

subgraph group_policy["Safety and settings"]
  node_network_guard["Network guard<br/>[network-guard.ts]"]
  node_guard_proxy["Guard proxy<br/>[guard-proxy.ts]"]
  node_config["Backend settings<br/>[config.ts]"]
  node_presentation["Result presentation"]
  node_config_command["Settings command"]
end

node_user(("Pi user"))

node_user -->|"asks research"| node_explore_tool
node_extension -->|"registers tool"| node_explore_tool
node_explore_tool -->|"starts research"| node_orchestration_api
node_explore_tool -->|"synthesizes answer"| node_synthesis
node_explore_tool -->|"checks evidence"| node_evidence
node_explore_tool -->|"formats result"| node_presentation
node_orchestration_api -->|"runs research"| node_orchestrator
node_orchestration_api -->|"builds backends"| node_backend_factory
node_orchestrator -.->|"coordinates passes"| node_worker
node_orchestrator -->|"assesses evidence"| node_evidence
node_orchestrator -->|"selects excerpts"| node_section_selector
node_worker -->|"selects excerpts"| node_section_selector
node_backend_factory -->|"builds providers"| node_search_providers
node_backend_factory -->|"builds fetchers"| node_fetchers
node_backend_factory -->|"configures guard"| node_network_guard
node_backend_factory -->|"configures fanout"| node_fanout
node_search_tool -->|"queries DuckDuckGo"| node_search_providers
node_search_tool -->|"formats results"| node_presentation
node_search_providers -.->|"uses fallback"| node_fallback
node_fanout -->|"applies policy"| node_fallback
node_fetchers -.->|"reads source formats"| node_readers
node_fetchers -.->|"checks destinations"| node_network_guard
node_fetchers -.->|"uses guarded proxy"| node_guard_proxy
node_fetchers -.->|"extracts page text"| node_extract
node_extract -->|"narrows content"| node_section_selector
node_extension -->|"registers settings"| node_config_command
node_config_command -->|"reads settings"| node_config
node_config -->|"sets allow ranges"| node_network_guard

click node_extension "https://github.com/demigodmode/pi-web-agent/blob/develop/src/extension.ts"
click node_explore_tool "https://github.com/demigodmode/pi-web-agent/blob/develop/src/tools/web-explore.ts"
click node_search_tool "https://github.com/demigodmode/pi-web-agent/blob/develop/src/tools/web-search.ts"
click node_orchestration_api "https://github.com/demigodmode/pi-web-agent/blob/develop/src/orchestration/index.ts"
click node_orchestrator "https://github.com/demigodmode/pi-web-agent/blob/develop/src/orchestration/research-orchestrator.ts"
click node_worker "https://github.com/demigodmode/pi-web-agent/blob/develop/src/orchestration/research-worker.ts"
click node_evidence "https://github.com/demigodmode/pi-web-agent/blob/develop/src/orchestration/evidence-quality.ts"
click node_synthesis "https://github.com/demigodmode/pi-web-agent/blob/develop/src/orchestration/answer-synthesizer.ts"
click node_backend_factory "https://github.com/demigodmode/pi-web-agent/blob/develop/src/backends/factory.ts"
click node_search_providers "https://github.com/demigodmode/pi-web-agent/tree/develop/src/search"
click node_fanout "https://github.com/demigodmode/pi-web-agent/blob/develop/src/search/fanout.ts"
click node_fallback "https://github.com/demigodmode/pi-web-agent/blob/develop/src/backends/fallback-policy.ts"
click node_fetchers "https://github.com/demigodmode/pi-web-agent/tree/develop/src/fetch"
click node_readers "https://github.com/demigodmode/pi-web-agent/tree/develop/src/readers"
click node_extract "https://github.com/demigodmode/pi-web-agent/blob/develop/src/extract/readability.ts"
click node_section_selector "https://github.com/demigodmode/pi-web-agent/blob/develop/src/extract/section-selector.ts"
click node_network_guard "https://github.com/demigodmode/pi-web-agent/blob/develop/src/fetch/network-guard.ts"
click node_guard_proxy "https://github.com/demigodmode/pi-web-agent/blob/develop/src/fetch/guard-proxy.ts"
click node_config "https://github.com/demigodmode/pi-web-agent/blob/develop/src/backends/config.ts"
click node_presentation "https://github.com/demigodmode/pi-web-agent/blob/develop/src/presentation/explore-presentation.ts"
click node_config_command "https://github.com/demigodmode/pi-web-agent/blob/develop/src/commands/web-agent-config.ts"

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_extension,node_explore_tool,node_search_tool,node_user toneBlue
class node_orchestration_api,node_orchestrator,node_worker,node_evidence,node_synthesis toneAmber
class node_backend_factory,node_search_providers,node_fanout,node_fallback toneMint
class node_fetchers,node_readers,node_extract,node_section_selector toneRose
class node_network_guard,node_guard_proxy,node_config,node_presentation,node_config_command toneIndigo
```

## Components

### Pi entrypoints

- [Extension setup](https://github.com/demigodmode/pi-web-agent/blob/develop/src/extension.ts): `src/extension.ts`
- [Web explore](https://github.com/demigodmode/pi-web-agent/blob/develop/src/tools/web-explore.ts): `src/tools/web-explore.ts`
- [Web search](https://github.com/demigodmode/pi-web-agent/blob/develop/src/tools/web-search.ts): `src/tools/web-search.ts`

### Research workflow

- [Research API](https://github.com/demigodmode/pi-web-agent/blob/develop/src/orchestration/index.ts): `src/orchestration/index.ts`
- [Research orchestrator](https://github.com/demigodmode/pi-web-agent/blob/develop/src/orchestration/research-orchestrator.ts): `src/orchestration/research-orchestrator.ts`
- [Research worker](https://github.com/demigodmode/pi-web-agent/blob/develop/src/orchestration/research-worker.ts): `src/orchestration/research-worker.ts`
- [Evidence quality](https://github.com/demigodmode/pi-web-agent/blob/develop/src/orchestration/evidence-quality.ts): `src/orchestration/evidence-quality.ts`
- [Answer synthesis](https://github.com/demigodmode/pi-web-agent/blob/develop/src/orchestration/answer-synthesizer.ts): `src/orchestration/answer-synthesizer.ts`

### Search and backends

- [Backend factory](https://github.com/demigodmode/pi-web-agent/blob/develop/src/backends/factory.ts): `src/backends/factory.ts`
- [Search providers](https://github.com/demigodmode/pi-web-agent/tree/develop/src/search): `src/search`
- [Search fanout](https://github.com/demigodmode/pi-web-agent/blob/develop/src/search/fanout.ts): `src/search/fanout.ts`
- [Fallback policy](https://github.com/demigodmode/pi-web-agent/blob/develop/src/backends/fallback-policy.ts): `src/backends/fallback-policy.ts`

### Fetch and content

- [Fetch backends](https://github.com/demigodmode/pi-web-agent/tree/develop/src/fetch): `src/fetch`
- [Content readers](https://github.com/demigodmode/pi-web-agent/tree/develop/src/readers): `src/readers`
- [Content extraction](https://github.com/demigodmode/pi-web-agent/blob/develop/src/extract/readability.ts): `src/extract/readability.ts`
- [Section selection](https://github.com/demigodmode/pi-web-agent/blob/develop/src/extract/section-selector.ts): `src/extract/section-selector.ts`

### Safety and settings

- [Network guard](https://github.com/demigodmode/pi-web-agent/blob/develop/src/fetch/network-guard.ts): `src/fetch/network-guard.ts`
- [Guard proxy](https://github.com/demigodmode/pi-web-agent/blob/develop/src/fetch/guard-proxy.ts): `src/fetch/guard-proxy.ts`
- [Backend settings](https://github.com/demigodmode/pi-web-agent/blob/develop/src/backends/config.ts): `src/backends/config.ts`
- [Result presentation](https://github.com/demigodmode/pi-web-agent/blob/develop/src/presentation/explore-presentation.ts): `src/presentation/explore-presentation.ts`
- [Settings command](https://github.com/demigodmode/pi-web-agent/blob/develop/src/commands/web-agent-config.ts): `src/commands/web-agent-config.ts`

### Other components

- **Pi user**

## Connections

- Pi user → Web explore: asks research
- Extension setup → Web explore: registers tool (evidence: `src/extension.ts`)
- Web explore → Research API: starts research (evidence: `src/tools/web-explore.ts`)
- Web explore → Answer synthesis: synthesizes answer (evidence: `src/tools/web-explore.ts`)
- Web explore → Evidence quality: checks evidence (evidence: `src/tools/web-explore.ts`)
- Web explore → Result presentation: formats result (evidence: `src/tools/web-explore.ts`)
- Research API → Research orchestrator: runs research (evidence: `src/orchestration/index.ts`)
- Research API → Backend factory: builds backends (evidence: `src/orchestration/index.ts`)
- Research orchestrator → Research worker: coordinates passes
- Research orchestrator → Evidence quality: assesses evidence (evidence: `src/orchestration/research-orchestrator.ts`)
- Research orchestrator → Section selection: selects excerpts (evidence: `src/orchestration/research-orchestrator.ts`)
- Research worker → Section selection: selects excerpts (evidence: `src/orchestration/research-worker.ts`)
- Backend factory → Search providers: builds providers (evidence: `src/backends/factory.ts`)
- Backend factory → Fetch backends: builds fetchers (evidence: `src/backends/factory.ts`)
- Backend factory → Network guard: configures guard (evidence: `src/backends/factory.ts`)
- Backend factory → Search fanout: configures fanout (evidence: `src/backends/factory.ts`)
- Web search → Search providers: queries DuckDuckGo (evidence: `src/tools/web-search.ts`)
- Web search → Result presentation: formats results (evidence: `src/tools/web-search.ts`)
- Search providers → Fallback policy: uses fallback (evidence: `src/search/fanout.ts`)
- Search fanout → Fallback policy: applies policy (evidence: `src/search/fanout.ts`)
- Fetch backends → Content readers: reads source formats
- Fetch backends → Network guard: checks destinations (evidence: `src/fetch/guard-proxy.ts`)
- Fetch backends → Guard proxy: uses guarded proxy (evidence: `src/fetch/headless-fetch.ts`)
- Fetch backends → Content extraction: extracts page text (evidence: `src/fetch/headless-fetch.ts`)
- Content extraction → Section selection: narrows content (evidence: `src/extract/readability.ts`)
- Extension setup → Settings command: registers settings (evidence: `src/extension.ts`)
- Settings command → Backend settings: reads settings (evidence: `src/commands/web-agent-config.ts`)
- Backend settings → Network guard: sets allow ranges (evidence: `src/backends/config.ts`)
