# egouilliard/pinchtab-webgraph architecture

> Architecture diagram of the GitHub repository egouilliard/pinchtab-webgraph, 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/egouilliard/pinchtab-webgraph
- Repository: https://github.com/egouilliard/pinchtab-webgraph

## Overview

pinchtab-webgraph crawls JavaScript-rendered sites into navigation and content graphs, then answers navigation and content questions from those graphs. Its main workflow is browser discovery → graph/cache → offline query or runnable action; declarative flows and the optional web workspace add automation and interactive access. The README documents several subsystems whose implementation was not sampled, so their nodes use only paths present in the tree and uncertain internal links are omitted.

Main entry points: [`pinchtab_webgraph/ui/server.py`](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/server.py) (Web app server), [`pinchtab_webgraph/interaction_crawl.py`](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/interaction_crawl.py) (Interaction crawler), [`pinchtab_webgraph/api.py`](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/api.py) (Query API), [`pinchtab_webgraph/cli.py`](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/cli.py) (Command line)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Site discovery"]
  node_crawl["Navigation crawler<br/>[crawl.py]"]
  node_interaction_crawl["Interaction crawler"]
  node_login["Authenticated access<br/>[login.py]"]
  node_graph_cache[("Per-host graph cache<br/>[cache_store.py]")]
end

subgraph group_query["Graph queries"]
  node_api["Query API<br/>[api.py]"]
  node_ask["Cache-first answers<br/>[ask.py]"]
  node_howto["How-to discovery<br/>[howto.py]"]
  node_query_cmd["Structured queries<br/>[query_cmd.py]"]
  node_recipe["Live recipe discovery<br/>[recipe.py]"]
end

subgraph group_automation["Automation"]
  node_perform["One-shot execution<br/>[perform.py]"]
  node_flow["Flow step VM<br/>[flow.py]"]
  node_flow_store[("Saved flows<br/>[flow_store.py]")]
end

subgraph group_access["Access surfaces"]
  node_cli["Command line<br/>[cli.py]"]
  node_mcp["MCP tools<br/>[mcp_server.py]"]
  node_utcp["UTCP manual<br/>[utcp_manual.py]"]
end

subgraph group_workspace["Web workspace"]
  node_ui_server["Web app server<br/>[server.py]"]
  node_ui["Workspace interface<br/>[app.js]"]
  node_chat["Chat agent<br/>[chat.py]"]
  node_claude_code["Claude Code backend"]
  node_chat_store[("Chat sessions<br/>[chat_store.py]")]
  node_screencast["Live browser pane<br/>[screencast.py]"]
  node_flow_ui["Flow editor<br/>[flows.js]"]
  node_flow_runner["Flow runner<br/>[flow_runner.py]"]
end

node_user(("User or agent"))
node_pinchtab["PinchTab browser"]
node_claude_api["Anthropic service"]

node_user -->|"runs commands"| node_cli
node_user -->|"uses workspace"| node_ui
node_user -->|"invokes tools"| node_mcp
node_cli -->|"starts crawl"| node_crawl
node_cli -->|"starts crawl"| node_interaction_crawl
node_crawl -->|"drives browser"| node_pinchtab
node_interaction_crawl -->|"drives browser"| node_pinchtab
node_interaction_crawl -.->|"uses login"| node_login
node_interaction_crawl -->|"writes graph"| node_graph_cache
node_crawl -->|"saves graph"| node_graph_cache
node_ask -->|"checks cache"| node_graph_cache
node_ask -->|"discovers on miss"| node_interaction_crawl
node_ask -->|"queries graph"| node_api
node_howto -->|"queries graph"| node_api
node_query_cmd -->|"calls queries"| node_api
node_mcp -->|"calls queries"| node_api
node_utcp -->|"runs commands"| node_query_cmd
node_cli -->|"dispatches queries"| node_query_cmd
node_recipe -->|"probes live UI"| node_pinchtab
node_perform -->|"executes actions"| node_pinchtab
node_ui -->|"requests services"| node_ui_server
node_ui_server -->|"serves queries"| node_api
node_ui_server -->|"dispatches chat"| node_chat
node_ui_server -->|"stores sessions"| node_chat_store
node_chat -->|"uses tools"| node_mcp
node_chat -.->|"requests responses"| node_claude_api
node_ui_server -.->|"dispatches backend"| node_claude_code
node_claude_code -.->|"uses tools"| node_mcp
node_ui_server -->|"streams browser"| node_screencast
node_screencast -->|"opens browser"| node_pinchtab
node_ui -->|"opens editor"| node_flow_ui
node_flow_ui -->|"loads and saves"| node_ui_server
node_ui_server -->|"persists flows"| node_flow_store
node_ui_server -->|"runs flows"| node_flow_runner
node_flow_runner -->|"executes steps"| node_flow
node_flow_runner -->|"drives browser"| node_pinchtab

click node_crawl "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/crawl.py"
click node_interaction_crawl "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/interaction_crawl.py"
click node_login "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/login.py"
click node_graph_cache "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/cache_store.py"
click node_api "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/api.py"
click node_ask "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ask.py"
click node_howto "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/howto.py"
click node_query_cmd "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/query_cmd.py"
click node_recipe "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/recipe.py"
click node_perform "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/perform.py"
click node_flow "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/flow.py"
click node_flow_store "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/flow_store.py"
click node_cli "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/cli.py"
click node_mcp "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/mcp_server.py"
click node_utcp "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/utcp_manual.py"
click node_ui_server "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/server.py"
click node_ui "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/static/app.js"
click node_chat "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/chat.py"
click node_claude_code "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/chat_claude_code.py"
click node_chat_store "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/chat_store.py"
click node_screencast "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/screencast.py"
click node_flow_ui "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/static/flows.js"
click node_flow_runner "https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/flow_runner.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_crawl,node_interaction_crawl,node_login,node_graph_cache,node_user,node_pinchtab toneBlue
class node_api,node_ask,node_howto,node_query_cmd,node_recipe toneAmber
class node_perform,node_flow,node_flow_store toneMint
class node_cli,node_mcp,node_utcp toneRose
class node_ui_server,node_ui,node_chat,node_claude_code,node_chat_store,node_screencast,node_flow_ui,node_flow_runner,node_claude_api toneIndigo
```

## Components

### Site discovery

- [Navigation crawler](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/crawl.py): `pinchtab_webgraph/crawl.py`
- [Interaction crawler](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/interaction_crawl.py): `pinchtab_webgraph/interaction_crawl.py`
- [Authenticated access](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/login.py): `pinchtab_webgraph/login.py`
- [Per-host graph cache](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/cache_store.py): `pinchtab_webgraph/cache_store.py`

### Graph queries

- [Query API](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/api.py): `pinchtab_webgraph/api.py`
- [Cache-first answers](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ask.py): `pinchtab_webgraph/ask.py`
- [How-to discovery](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/howto.py): `pinchtab_webgraph/howto.py`
- [Structured queries](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/query_cmd.py): `pinchtab_webgraph/query_cmd.py`
- [Live recipe discovery](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/recipe.py): `pinchtab_webgraph/recipe.py`

### Automation

- [One-shot execution](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/perform.py): `pinchtab_webgraph/perform.py`
- [Flow step VM](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/flow.py): `pinchtab_webgraph/flow.py`
- [Saved flows](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/flow_store.py): `pinchtab_webgraph/ui/flow_store.py`

### Access surfaces

- [Command line](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/cli.py): `pinchtab_webgraph/cli.py`
- [MCP tools](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/mcp_server.py): `pinchtab_webgraph/mcp_server.py`
- [UTCP manual](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/utcp_manual.py): `pinchtab_webgraph/utcp_manual.py`

### Web workspace

- [Web app server](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/server.py): `pinchtab_webgraph/ui/server.py`
- [Workspace interface](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/static/app.js): `pinchtab_webgraph/ui/static/app.js`
- [Chat agent](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/chat.py): `pinchtab_webgraph/ui/chat.py`
- [Claude Code backend](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/chat_claude_code.py): `pinchtab_webgraph/ui/chat_claude_code.py`
- [Chat sessions](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/chat_store.py): `pinchtab_webgraph/ui/chat_store.py`
- [Live browser pane](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/screencast.py): `pinchtab_webgraph/ui/screencast.py`
- [Flow editor](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/static/flows.js): `pinchtab_webgraph/ui/static/flows.js`
- [Flow runner](https://github.com/egouilliard/pinchtab-webgraph/blob/main/pinchtab_webgraph/ui/flow_runner.py): `pinchtab_webgraph/ui/flow_runner.py`

### Other components

- **User or agent**
- **PinchTab browser**
- **Anthropic service**

## Connections

- User or agent → Command line: runs commands
- User or agent → Workspace interface: uses workspace
- User or agent → MCP tools: invokes tools
- Command line → Navigation crawler: starts crawl
- Command line → Interaction crawler: starts crawl
- Navigation crawler → PinchTab browser: drives browser
- Interaction crawler → PinchTab browser: drives browser
- Interaction crawler → Authenticated access: uses login
- Interaction crawler → Per-host graph cache: writes graph
- Navigation crawler → Per-host graph cache: saves graph
- Cache-first answers → Per-host graph cache: checks cache
- Cache-first answers → Interaction crawler: discovers on miss
- Cache-first answers → Query API: queries graph
- How-to discovery → Query API: queries graph
- Structured queries → Query API: calls queries
- MCP tools → Query API: calls queries
- UTCP manual → Structured queries: runs commands
- Command line → Structured queries: dispatches queries
- Live recipe discovery → PinchTab browser: probes live UI
- One-shot execution → PinchTab browser: executes actions
- Workspace interface → Web app server: requests services
- Web app server → Query API: serves queries
- Web app server → Chat agent: dispatches chat
- Web app server → Chat sessions: stores sessions
- Chat agent → MCP tools: uses tools
- Chat agent → Anthropic service: requests responses
- Web app server → Claude Code backend: dispatches backend
- Claude Code backend → MCP tools: uses tools
- Web app server → Live browser pane: streams browser
- Live browser pane → PinchTab browser: opens browser
- Workspace interface → Flow editor: opens editor
- Flow editor → Web app server: loads and saves
- Web app server → Saved flows: persists flows
- Web app server → Flow runner: runs flows
- Flow runner → Flow step VM: executes steps
- Flow runner → PinchTab browser: drives browser