# amir89hamzah/s22-web-agent architecture

> Architecture diagram of the GitHub repository amir89hamzah/s22-web-agent, 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/amir89hamzah/s22-web-agent
- Repository: https://github.com/amir89hamzah/s22-web-agent

## Overview

S22 Web Agent is a phone-hosted MCP and browser-automation node with two principal workflows: webpage scanning and persistent browser tasks, including human-assisted login and later authenticated scans. The graph also preserves the documented MCP exposure modes, local persistence, and diagnostics. Some subsystem links use enclosing paths because their implementation was not sampled; those links are limited to documented capabilities and sampled call boundaries.

Main entry points: [`src/scanner.js`](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/scanner.js) (Page scanner), [`src/mcp-core.mjs`](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/mcp-core.mjs) (MCP tool registry), [`src/index.js`](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/index.js) (CLI commands), [`src/server.js`](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/server.js) (Local HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[index.js]"]
  node_http_api["Local HTTP API<br/>[server.js]"]
end

subgraph group_scanning["Scanning and reports"]
  node_scan_engine["Page scanner<br/>[scanner.js]"]
  node_classifier["Page classifier<br/>[classifier.js]"]
  node_scan_store[("Scan history<br/>[db.js]")]
  node_reports["Markdown reports<br/>[report.js]"]
end

subgraph group_browser["Browser and sessions"]
  node_browser_tools["Browser MCP tools"]
  node_browser_orch["Browser task control"]
  node_worker_api["Playwright worker API<br/>[server.mjs]"]
  node_browser_engine["Persistent browser"]
  node_manual_login["Manual login worker"]
  node_profile_state[("Session profiles")]
  node_auth_tools["Authenticated task tools"]
  node_auth_orch["Auth task lifecycle"]
  node_gateway_tools["Login gateway tools"]
  node_gateway_orch["Login gateway control"]
  node_novnc_gateway["Temporary noVNC gateway"]
end

subgraph group_connectivity["MCP and connectivity"]
  node_mcp_stdio["MCP stdio<br/>[mcp-server.mjs]"]
  node_mcp_http["MCP HTTP"]
  node_mcp_tools["MCP tool registry<br/>[mcp-core.mjs]"]
  node_route_a["Route A tunnel<br/>[start-route-a.sh]"]
  node_openai_tunnel["Secure MCP tunnel"]
end

subgraph group_runtime["Device runtime"]
  node_device_health["Device health<br/>[device-health.mjs]"]
end

node_operator(("Operator"))
node_mcp_client(("MCP client"))
node_web_target(("Websites"))
node_human(("Human login"))
node_cloudflare(("Cloudflare"))

node_operator -->|"runs commands"| node_cli
node_operator -->|"requests scans"| node_http_api
node_mcp_client -->|"sends tools"| node_mcp_stdio
node_mcp_client -->|"sends tools"| node_mcp_http
node_mcp_stdio -->|"dispatches"| node_mcp_tools
node_mcp_http -->|"dispatches"| node_mcp_tools
node_cli -->|"calls scan"| node_scan_engine
node_http_api -->|"calls scan"| node_scan_engine
node_scan_engine -->|"fetches page"| node_web_target
node_scan_engine -->|"classifies content"| node_classifier
node_scan_engine -->|"stores scan"| node_scan_store
node_cli -->|"reads history"| node_scan_store
node_http_api -->|"reads history"| node_scan_store
node_cli -->|"generates report"| node_reports
node_http_api -->|"generates report"| node_reports
node_mcp_tools -->|"registers tools"| node_browser_tools
node_browser_tools -->|"invokes lifecycle"| node_browser_orch
node_browser_orch -->|"calls worker"| node_worker_api
node_worker_api -->|"delegates tasks"| node_browser_engine
node_browser_engine -->|"navigates"| node_web_target
node_browser_engine -->|"uses profile"| node_profile_state
node_human -->|"completes login"| node_manual_login
node_manual_login -->|"saves session"| node_profile_state
node_mcp_tools -->|"registers tools"| node_auth_tools
node_auth_tools -->|"runs task actions"| node_auth_orch
node_auth_orch -->|"probes profile"| node_profile_state
node_auth_orch -->|"checks target"| node_web_target
node_mcp_tools -->|"registers tools"| node_gateway_tools
node_gateway_tools -->|"runs gateway actions"| node_gateway_orch
node_gateway_orch -->|"controls gateway"| node_novnc_gateway
node_novnc_gateway -->|"provides login access"| node_human
node_browser_orch -->|"collects health"| node_device_health
node_cloudflare -.->|"tunnels traffic"| node_route_a
node_route_a -.->|"forwards MCP"| node_mcp_http
node_cloudflare -.->|"supports tunnel"| node_openai_tunnel
node_openai_tunnel -.->|"connects client"| node_mcp_http
node_cloudflare -.->|"protects access"| node_novnc_gateway

click node_cli "https://github.com/amir89hamzah/s22-web-agent/blob/main/src/index.js"
click node_http_api "https://github.com/amir89hamzah/s22-web-agent/blob/main/src/server.js"
click node_mcp_stdio "https://github.com/amir89hamzah/s22-web-agent/blob/main/src/mcp-server.mjs"
click node_mcp_http "https://github.com/amir89hamzah/s22-web-agent/blob/main/src/mcp-http-server.mjs"
click node_mcp_tools "https://github.com/amir89hamzah/s22-web-agent/blob/main/src/mcp-core.mjs"
click node_scan_engine "https://github.com/amir89hamzah/s22-web-agent/blob/main/src/scanner.js"
click node_classifier "https://github.com/amir89hamzah/s22-web-agent/blob/main/src/classifier.js"
click node_scan_store "https://github.com/amir89hamzah/s22-web-agent/blob/main/src/db.js"
click node_reports "https://github.com/amir89hamzah/s22-web-agent/blob/main/src/report.js"
click node_browser_tools "https://github.com/amir89hamzah/s22-web-agent/blob/main/src/mcp-browser-task-tools.mjs"
click node_browser_orch "https://github.com/amir89hamzah/s22-web-agent/blob/main/tools/browser-task-orchestrator.mjs"
click node_worker_api "https://github.com/amir89hamzah/s22-web-agent/blob/main/tools/proot-playwright-worker/server.mjs"
click node_browser_engine "https://github.com/amir89hamzah/s22-web-agent/blob/main/tools/proot-playwright-worker/persistent-browser-engine.mjs"
click node_manual_login "https://github.com/amir89hamzah/s22-web-agent/blob/main/tools/proot-playwright-worker/session-manual-login-worker.mjs"
click node_profile_state "https://github.com/amir89hamzah/s22-web-agent/blob/main/tools/session-profile-common.mjs"
click node_auth_tools "https://github.com/amir89hamzah/s22-web-agent/blob/main/src/mcp-auth-task-tools.mjs"
click node_auth_orch "https://github.com/amir89hamzah/s22-web-agent/blob/main/tools/authenticated-task-orchestrator.mjs"
click node_gateway_tools "https://github.com/amir89hamzah/s22-web-agent/blob/main/src/mcp-auth-login-gateway-tools.mjs"
click node_gateway_orch "https://github.com/amir89hamzah/s22-web-agent/blob/main/tools/auth-login-gateway-orchestrator.mjs"
click node_device_health "https://github.com/amir89hamzah/s22-web-agent/blob/main/src/device-health.mjs"
click node_route_a "https://github.com/amir89hamzah/s22-web-agent/blob/main/scripts/start-route-a.sh"
click node_openai_tunnel "https://github.com/amir89hamzah/s22-web-agent/blob/main/scripts/start-openai-tunnel-mode.sh"
click node_novnc_gateway "https://github.com/amir89hamzah/s22-web-agent/blob/main/scripts/session-novnc-public-temp-tunnel-start.sh"

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_cli,node_http_api,node_mcp_client toneBlue
class node_scan_engine,node_classifier,node_scan_store,node_reports toneAmber
class node_browser_tools,node_browser_orch,node_worker_api,node_browser_engine,node_manual_login,node_profile_state,node_auth_tools,node_auth_orch,node_gateway_tools,node_gateway_orch,node_novnc_gateway toneMint
class node_mcp_stdio,node_mcp_http,node_mcp_tools,node_route_a,node_openai_tunnel toneRose
class node_device_health,node_operator,node_web_target,node_human,node_cloudflare toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/index.js): `src/index.js`
- [Local HTTP API](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/server.js): `src/server.js`

### Scanning and reports

- [Page scanner](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/scanner.js): `src/scanner.js`
- [Page classifier](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/classifier.js): `src/classifier.js`
- [Scan history](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/db.js): `src/db.js`
- [Markdown reports](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/report.js): `src/report.js`

### Browser and sessions

- [Browser MCP tools](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/mcp-browser-task-tools.mjs): `src/mcp-browser-task-tools.mjs`
- [Browser task control](https://github.com/amir89hamzah/s22-web-agent/blob/main/tools/browser-task-orchestrator.mjs): `tools/browser-task-orchestrator.mjs`
- [Playwright worker API](https://github.com/amir89hamzah/s22-web-agent/blob/main/tools/proot-playwright-worker/server.mjs): `tools/proot-playwright-worker/server.mjs`
- [Persistent browser](https://github.com/amir89hamzah/s22-web-agent/blob/main/tools/proot-playwright-worker/persistent-browser-engine.mjs): `tools/proot-playwright-worker/persistent-browser-engine.mjs`
- [Manual login worker](https://github.com/amir89hamzah/s22-web-agent/blob/main/tools/proot-playwright-worker/session-manual-login-worker.mjs): `tools/proot-playwright-worker/session-manual-login-worker.mjs`
- [Session profiles](https://github.com/amir89hamzah/s22-web-agent/blob/main/tools/session-profile-common.mjs): `tools/session-profile-common.mjs`
- [Authenticated task tools](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/mcp-auth-task-tools.mjs): `src/mcp-auth-task-tools.mjs`
- [Auth task lifecycle](https://github.com/amir89hamzah/s22-web-agent/blob/main/tools/authenticated-task-orchestrator.mjs): `tools/authenticated-task-orchestrator.mjs`
- [Login gateway tools](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/mcp-auth-login-gateway-tools.mjs): `src/mcp-auth-login-gateway-tools.mjs`
- [Login gateway control](https://github.com/amir89hamzah/s22-web-agent/blob/main/tools/auth-login-gateway-orchestrator.mjs): `tools/auth-login-gateway-orchestrator.mjs`
- [Temporary noVNC gateway](https://github.com/amir89hamzah/s22-web-agent/blob/main/scripts/session-novnc-public-temp-tunnel-start.sh): `scripts/session-novnc-public-temp-tunnel-start.sh`

### MCP and connectivity

- [MCP stdio](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/mcp-server.mjs): `src/mcp-server.mjs`
- [MCP HTTP](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/mcp-http-server.mjs): `src/mcp-http-server.mjs`
- [MCP tool registry](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/mcp-core.mjs): `src/mcp-core.mjs`
- [Route A tunnel](https://github.com/amir89hamzah/s22-web-agent/blob/main/scripts/start-route-a.sh): `scripts/start-route-a.sh`
- [Secure MCP tunnel](https://github.com/amir89hamzah/s22-web-agent/blob/main/scripts/start-openai-tunnel-mode.sh): `scripts/start-openai-tunnel-mode.sh`

### Device runtime

- [Device health](https://github.com/amir89hamzah/s22-web-agent/blob/main/src/device-health.mjs): `src/device-health.mjs`

### Other components

- **Operator**
- **MCP client**
- **Websites**
- **Human login**
- **Cloudflare**

## Connections

- Operator → CLI commands: runs commands
- Operator → Local HTTP API: requests scans
- MCP client → MCP stdio: sends tools
- MCP client → MCP HTTP: sends tools
- MCP stdio → MCP tool registry: dispatches
- MCP HTTP → MCP tool registry: dispatches
- CLI commands → Page scanner: calls scan
- Local HTTP API → Page scanner: calls scan
- Page scanner → Websites: fetches page
- Page scanner → Page classifier: classifies content
- Page scanner → Scan history: stores scan
- CLI commands → Scan history: reads history
- Local HTTP API → Scan history: reads history
- CLI commands → Markdown reports: generates report
- Local HTTP API → Markdown reports: generates report
- MCP tool registry → Browser MCP tools: registers tools
- Browser MCP tools → Browser task control: invokes lifecycle
- Browser task control → Playwright worker API: calls worker
- Playwright worker API → Persistent browser: delegates tasks
- Persistent browser → Websites: navigates
- Persistent browser → Session profiles: uses profile
- Human login → Manual login worker: completes login
- Manual login worker → Session profiles: saves session
- MCP tool registry → Authenticated task tools: registers tools
- Authenticated task tools → Auth task lifecycle: runs task actions
- Auth task lifecycle → Session profiles: probes profile
- Auth task lifecycle → Websites: checks target
- MCP tool registry → Login gateway tools: registers tools
- Login gateway tools → Login gateway control: runs gateway actions
- Login gateway control → Temporary noVNC gateway: controls gateway
- Temporary noVNC gateway → Human login: provides login access
- Browser task control → Device health: collects health
- Cloudflare → Route A tunnel: tunnels traffic
- Route A tunnel → MCP HTTP: forwards MCP
- Cloudflare → Secure MCP tunnel: supports tunnel
- Secure MCP tunnel → MCP HTTP: connects client
- Cloudflare → Temporary noVNC gateway: protects access