# i-am-tonywu/codex-web architecture

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

- Interactive diagram: https://gitdiagram.com/i-am-tonywu/codex-web
- Repository: https://github.com/i-am-tonywu/codex-web

## Overview

Codex Web exposes a Windows-hosted Codex workspace through a browser. The principal flow is a remote or local user opening the web UI, selecting or creating a task, and interacting with the host’s Codex client; the UI also surfaces project files, review, skills, automations, and terminal tools. The tray monitors the desktop client and starts the local web service. The README documents the optional Cloudflare remote-access setup. Some server internals are unsampled, so uncertain runtime links are omitted or marked unverified.

Main entry points: [`web/src/api/codexGateway.ts`](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/api/codexGateway.ts) (Codex gateway), [`web/src/server/httpServer.ts`](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/server/httpServer.ts) (Web server), [`web/src/App.vue`](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/App.vue) (Workspace UI), [`tray/TrayApp.cs`](https://github.com/i-am-tonywu/codex-web/blob/main/tray/TrayApp.cs) (Tray controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Windows host"]
  node_tray["Tray controller<br/>[TrayApp.cs]"]
  node_monitor["Codex monitor<br/>[Monitor.cs]"]
  node_runtime["Web runtime<br/>[Runtime.cs]"]
  node_security["Tray security"]
  node_site["Cloudflare settings<br/>[CloudflareSite.cs]"]
  node_http["Web server<br/>[httpServer.ts]"]
end

subgraph group_ui["Browser workspace"]
  node_app["Workspace UI<br/>[App.vue]"]
  node_layout["Desktop layout<br/>[DesktopLayout.vue]"]
  node_threadtree["Task navigation"]
  node_thread["Task conversation"]
  node_composer["Task composer<br/>[ThreadComposer.vue]"]
  node_state["Workspace state<br/>[useDesktopState.ts]"]
end

subgraph group_codex["Codex integration"]
  node_gateway["Codex gateway<br/>[codexGateway.ts]"]
  node_rpc["RPC transport<br/>[codexRpcClient.ts]"]
  node_normalizer["Response normalization<br/>[v2.ts]"]
  node_types["Codex data types<br/>[codex.ts]"]
  node_bridge["Codex app bridge"]
end

subgraph group_features["Workspace features"]
  node_review["Git review<br/>[ReviewPane.vue]"]
  node_git["Review operations<br/>[reviewGit.ts]"]
  node_skills["Skills and extensions<br/>[skillsRoutes.ts]"]
  node_terminal["Terminal sessions<br/>[terminalManager.ts]"]
  node_accounts["Account management<br/>[accountRoutes.ts]"]
end

subgraph group_remote["Remote access"]
  node_cloudflare["Cloudflare Access"]
end

node_user(("Browser user"))

node_user -->|"opens workspace"| node_app
node_tray -->|"checks client"| node_monitor
node_tray -->|"starts service"| node_runtime
node_tray -->|"configures access"| node_security
node_security -->|"stores site settings"| node_site
node_runtime -->|"hosts web service"| node_http
node_app -->|"renders"| node_layout
node_app -->|"renders"| node_composer
node_app -->|"renders"| node_threadtree
node_app -->|"requests workspace data"| node_gateway
node_threadtree -->|"loads task data"| node_gateway
node_state -->|"loads and updates tasks"| node_gateway
node_gateway -->|"dispatches RPC"| node_rpc
node_gateway -->|"normalizes responses"| node_normalizer
node_normalizer -->|"uses data shapes"| node_types
node_gateway -->|"uses data shapes"| node_types
node_rpc -.->|"sends RPC"| node_bridge
node_review -->|"requests review actions"| node_gateway
node_http -.->|"routes review requests"| node_git
node_http -.->|"routes skill requests"| node_skills
node_http -.->|"routes terminal requests"| node_terminal
node_http -.->|"routes account requests"| node_accounts
node_user -->|"authenticates remotely"| node_cloudflare
node_cloudflare -->|"tunnels to host"| node_http

click node_tray "https://github.com/i-am-tonywu/codex-web/blob/main/tray/TrayApp.cs"
click node_monitor "https://github.com/i-am-tonywu/codex-web/blob/main/tray/Monitor.cs"
click node_runtime "https://github.com/i-am-tonywu/codex-web/blob/main/tray/Runtime.cs"
click node_security "https://github.com/i-am-tonywu/codex-web/blob/main/tray/SecuritySettings.cs"
click node_site "https://github.com/i-am-tonywu/codex-web/blob/main/tray/CloudflareSite.cs"
click node_app "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/App.vue"
click node_layout "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/components/layout/DesktopLayout.vue"
click node_threadtree "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/components/sidebar/SidebarThreadTree.vue"
click node_thread "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/components/content/ThreadConversation.vue"
click node_composer "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/components/content/ThreadComposer.vue"
click node_state "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/composables/useDesktopState.ts"
click node_gateway "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/api/codexGateway.ts"
click node_rpc "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/api/codexRpcClient.ts"
click node_normalizer "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/api/normalizers/v2.ts"
click node_types "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/types/codex.ts"
click node_bridge "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/server/codexAppServerBridge.ts"
click node_review "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/components/content/ReviewPane.vue"
click node_git "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/server/reviewGit.ts"
click node_skills "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/server/skillsRoutes.ts"
click node_terminal "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/server/terminalManager.ts"
click node_accounts "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/server/accountRoutes.ts"
click node_http "https://github.com/i-am-tonywu/codex-web/blob/main/web/src/server/httpServer.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_tray,node_monitor,node_runtime,node_security,node_site,node_http,node_user toneBlue
class node_app,node_layout,node_threadtree,node_thread,node_composer,node_state toneAmber
class node_gateway,node_rpc,node_normalizer,node_types,node_bridge toneMint
class node_review,node_git,node_skills,node_terminal,node_accounts toneRose
class node_cloudflare toneIndigo
```

## Components

### Windows host

- [Tray controller](https://github.com/i-am-tonywu/codex-web/blob/main/tray/TrayApp.cs): `tray/TrayApp.cs`
- [Codex monitor](https://github.com/i-am-tonywu/codex-web/blob/main/tray/Monitor.cs): `tray/Monitor.cs`
- [Web runtime](https://github.com/i-am-tonywu/codex-web/blob/main/tray/Runtime.cs): `tray/Runtime.cs`
- [Tray security](https://github.com/i-am-tonywu/codex-web/blob/main/tray/SecuritySettings.cs): `tray/SecuritySettings.cs`
- [Cloudflare settings](https://github.com/i-am-tonywu/codex-web/blob/main/tray/CloudflareSite.cs): `tray/CloudflareSite.cs`
- [Web server](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/server/httpServer.ts): `web/src/server/httpServer.ts`

### Browser workspace

- [Workspace UI](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/App.vue): `web/src/App.vue`
- [Desktop layout](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/components/layout/DesktopLayout.vue): `web/src/components/layout/DesktopLayout.vue`
- [Task navigation](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/components/sidebar/SidebarThreadTree.vue): `web/src/components/sidebar/SidebarThreadTree.vue`
- [Task conversation](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/components/content/ThreadConversation.vue): `web/src/components/content/ThreadConversation.vue`
- [Task composer](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/components/content/ThreadComposer.vue): `web/src/components/content/ThreadComposer.vue`
- [Workspace state](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/composables/useDesktopState.ts): `web/src/composables/useDesktopState.ts`

### Codex integration

- [Codex gateway](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/api/codexGateway.ts): `web/src/api/codexGateway.ts`
- [RPC transport](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/api/codexRpcClient.ts): `web/src/api/codexRpcClient.ts`
- [Response normalization](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/api/normalizers/v2.ts): `web/src/api/normalizers/v2.ts`
- [Codex data types](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/types/codex.ts): `web/src/types/codex.ts`
- [Codex app bridge](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/server/codexAppServerBridge.ts): `web/src/server/codexAppServerBridge.ts`

### Workspace features

- [Git review](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/components/content/ReviewPane.vue): `web/src/components/content/ReviewPane.vue`
- [Review operations](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/server/reviewGit.ts): `web/src/server/reviewGit.ts`
- [Skills and extensions](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/server/skillsRoutes.ts): `web/src/server/skillsRoutes.ts`
- [Terminal sessions](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/server/terminalManager.ts): `web/src/server/terminalManager.ts`
- [Account management](https://github.com/i-am-tonywu/codex-web/blob/main/web/src/server/accountRoutes.ts): `web/src/server/accountRoutes.ts`

### Remote access

- **Cloudflare Access**

### Other components

- **Browser user**

## Connections

- Browser user → Workspace UI: opens workspace (evidence: `README.md`)
- Tray controller → Codex monitor: checks client (evidence: `tray/TrayApp.cs`)
- Tray controller → Web runtime: starts service (evidence: `tray/TrayApp.cs`)
- Tray controller → Tray security: configures access (evidence: `README.md`)
- Tray security → Cloudflare settings: stores site settings (evidence: `tray/SecuritySettings.cs`)
- Web runtime → Web server: hosts web service (evidence: `README.md`)
- Workspace UI → Desktop layout: renders (evidence: `web/src/App.vue`)
- Workspace UI → Task composer: renders (evidence: `web/src/App.vue`)
- Workspace UI → Task navigation: renders (evidence: `web/src/App.vue`)
- Workspace UI → Codex gateway: requests workspace data (evidence: `web/src/App.vue`)
- Task navigation → Codex gateway: loads task data (evidence: `web/src/components/sidebar/SidebarThreadTree.vue`)
- Workspace state → Codex gateway: loads and updates tasks (evidence: `web/src/composables/useDesktopState.ts`)
- Codex gateway → RPC transport: dispatches RPC (evidence: `web/src/api/codexGateway.ts`)
- Codex gateway → Response normalization: normalizes responses (evidence: `web/src/api/codexGateway.ts`)
- Response normalization → Codex data types: uses data shapes (evidence: `web/src/api/normalizers/v2.ts`)
- Codex gateway → Codex data types: uses data shapes (evidence: `web/src/api/codexGateway.ts`)
- RPC transport → Codex app bridge: sends RPC
- Git review → Codex gateway: requests review actions (evidence: `web/src/components/content/ReviewPane.vue`)
- Web server → Review operations: routes review requests
- Web server → Skills and extensions: routes skill requests
- Web server → Terminal sessions: routes terminal requests
- Web server → Account management: routes account requests
- Browser user → Cloudflare Access: authenticates remotely (evidence: `README.md`)
- Cloudflare Access → Web server: tunnels to host (evidence: `README.md`)
