# yyjeqhc/webcodex architecture

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

- Interactive diagram: https://gitdiagram.com/yyjeqhc/webcodex
- Repository: https://github.com/yyjeqhc/webcodex

## Overview

WebCodex lets AI clients operate on repositories and development tools on user-owned machines. The main workflow is client request → Server routing and authorization → Runner execution against a local project → observable job results for review. Desktop and CLI support setup and administration; additional capabilities include project management, browser/computer control, workflow sessions, and audit evidence. The README documents the overall flow, but the sampled source is partial, so internal Server routing links are limited to relationships explicitly supported by the available evidence.

Main entry points: [`src`](https://github.com/yyjeqhc/webcodex/tree/main/src) (WebCodex Server), [`crates/webcodex-runner/src/main.rs`](https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-runner/src/main.rs) (Runner service), [`crates/webcodex-runner/src/webcodex_runner/job_manager.rs`](https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-runner/src/webcodex_runner/job_manager.rs) (Job lifecycle), [`crates/webcodex-runner-registry/src/lib.rs`](https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-runner-registry/src/lib.rs) (Runner registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_desktop["Desktop app<br/>[App.tsx]"]
  node_cli["CLI<br/>[mod.rs]"]
  node_desktopui["Desktop workflows<br/>[ProjectsPanel.tsx]"]
end

subgraph group_control["Server and control"]
  node_server["WebCodex Server"]
  node_mcp["MCP gateway<br/>[mcp_gateway.rs]"]
  node_registry[("Runner registry<br/>[lib.rs]")]
  node_store[("Persistent records<br/>[lib.rs]")]
end

subgraph group_execution["Runner execution"]
  node_runner["Runner service<br/>[main.rs]"]
  node_jobs["Job lifecycle<br/>[job_manager.rs]"]
  node_project["Project access<br/>[projects.rs]"]
  node_tools["Local tools<br/>[dispatch.rs]"]
  node_browser["Browser control<br/>[lib.rs]"]
  node_computer["Computer control<br/>[lib.rs]"]
end

subgraph group_support["Setup and evidence"]
  node_environment["Environment setup<br/>[engine.rs]"]
  node_sessions["Workflow sessions"]
  node_audit["Audit evidence<br/>[routes.rs]"]
end

node_ai(("AI client"))

node_ai -->|"sends MCP requests"| node_mcp
node_mcp -->|"routes requests"| node_server
node_server -->|"dispatches work"| node_registry
node_server -->|"reads and writes"| node_store
node_registry -->|"coordinates runners"| node_runner
node_runner -->|"manages jobs"| node_jobs
node_jobs -->|"accesses projects"| node_project
node_jobs -->|"executes operations"| node_tools
node_runner -.->|"uses browser control"| node_browser
node_runner -.->|"uses computer control"| node_computer
node_runner -->|"reports job updates"| node_registry
node_desktop -->|"presents workflows"| node_desktopui
node_desktop -->|"configures connection"| node_server
node_cli -->|"administers services"| node_server
node_cli -->|"configures runtime"| node_environment
node_server -->|"records workflow"| node_sessions
node_server -->|"serves audit evidence"| node_audit
node_ai -->|"connects over HTTPS"| node_server

click node_desktop "https://github.com/yyjeqhc/webcodex/blob/main/apps/desktop/src/App.tsx"
click node_cli "https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-cli/src/webcodex_cli/mod.rs"
click node_server "https://github.com/yyjeqhc/webcodex/tree/main/src"
click node_mcp "https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-core/src/mcp_gateway.rs"
click node_registry "https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-runner-registry/src/lib.rs"
click node_store "https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-store/src/lib.rs"
click node_runner "https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-runner/src/main.rs"
click node_jobs "https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-runner/src/webcodex_runner/job_manager.rs"
click node_project "https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-runner/src/webcodex_runner/projects.rs"
click node_tools "https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-runner/src/webcodex_runner/dispatch.rs"
click node_browser "https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-browser/src/lib.rs"
click node_computer "https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-computer/src/lib.rs"
click node_environment "https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-environment/src/engine.rs"
click node_desktopui "https://github.com/yyjeqhc/webcodex/blob/main/apps/desktop/src/features/projects/ProjectsPanel.tsx"
click node_sessions "https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-core/src/workflow_session_contract.rs"
click node_audit "https://github.com/yyjeqhc/webcodex/blob/main/src/audit_http/routes.rs"

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_desktop,node_cli,node_desktopui,node_ai toneBlue
class node_server,node_mcp,node_registry,node_store toneAmber
class node_runner,node_jobs,node_project,node_tools,node_browser,node_computer toneMint
class node_environment,node_sessions,node_audit toneRose
```

## Components

### User interfaces

- [Desktop app](https://github.com/yyjeqhc/webcodex/blob/main/apps/desktop/src/App.tsx): `apps/desktop/src/App.tsx`
- [CLI](https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-cli/src/webcodex_cli/mod.rs): `crates/webcodex-cli/src/webcodex_cli/mod.rs`
- [Desktop workflows](https://github.com/yyjeqhc/webcodex/blob/main/apps/desktop/src/features/projects/ProjectsPanel.tsx): `apps/desktop/src/features/projects/ProjectsPanel.tsx`

### Server and control

- [WebCodex Server](https://github.com/yyjeqhc/webcodex/tree/main/src): `src`
- [MCP gateway](https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-core/src/mcp_gateway.rs): `crates/webcodex-core/src/mcp_gateway.rs`
- [Runner registry](https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-runner-registry/src/lib.rs): `crates/webcodex-runner-registry/src/lib.rs`
- [Persistent records](https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-store/src/lib.rs): `crates/webcodex-store/src/lib.rs`

### Runner execution

- [Runner service](https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-runner/src/main.rs): `crates/webcodex-runner/src/main.rs`
- [Job lifecycle](https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-runner/src/webcodex_runner/job_manager.rs): `crates/webcodex-runner/src/webcodex_runner/job_manager.rs`
- [Project access](https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-runner/src/webcodex_runner/projects.rs): `crates/webcodex-runner/src/webcodex_runner/projects.rs`
- [Local tools](https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-runner/src/webcodex_runner/dispatch.rs): `crates/webcodex-runner/src/webcodex_runner/dispatch.rs`
- [Browser control](https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-browser/src/lib.rs): `crates/webcodex-browser/src/lib.rs`
- [Computer control](https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-computer/src/lib.rs): `crates/webcodex-computer/src/lib.rs`

### Setup and evidence

- [Environment setup](https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-environment/src/engine.rs): `crates/webcodex-environment/src/engine.rs`
- [Workflow sessions](https://github.com/yyjeqhc/webcodex/blob/main/crates/webcodex-core/src/workflow_session_contract.rs): `crates/webcodex-core/src/workflow_session_contract.rs`
- [Audit evidence](https://github.com/yyjeqhc/webcodex/blob/main/src/audit_http/routes.rs): `src/audit_http/routes.rs`

### Other components

- **AI client**

## Connections

- AI client → MCP gateway: sends MCP requests
- MCP gateway → WebCodex Server: routes requests
- WebCodex Server → Runner registry: dispatches work
- WebCodex Server → Persistent records: reads and writes
- Runner registry → Runner service: coordinates runners
- Runner service → Job lifecycle: manages jobs
- Job lifecycle → Project access: accesses projects
- Job lifecycle → Local tools: executes operations
- Runner service → Browser control: uses browser control
- Runner service → Computer control: uses computer control
- Runner service → Runner registry: reports job updates
- Desktop app → Desktop workflows: presents workflows
- Desktop app → WebCodex Server: configures connection
- CLI → WebCodex Server: administers services
- CLI → Environment setup: configures runtime
- WebCodex Server → Workflow sessions: records workflow
- WebCodex Server → Audit evidence: serves audit evidence
- AI client → WebCodex Server: connects over HTTPS