# limlll/codex-webui architecture

> Architecture diagram of the GitHub repository limlll/codex-webui, 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/limlll/codex-webui
- Repository: https://github.com/limlll/codex-webui

## Overview

Codex WebUI is a browser interface for OpenAI Codex CLI: users authenticate, open or create threads, submit turns, and follow live results, approvals, and conversation history. Separate product workflows cover message-level branching, workspace file operations and previews, terminal sessions, and integrations such as plugins and MCP servers. The backend exposes REST and Socket.IO, delegates Codex operations to its app-server child, and uses SQLite for persistent application state. README documents these capabilities; sampled excerpts confirm only selected controller, service, and process-manager links, so other subsystem wiring is kept conservative.

Main entry points: [`web/src/api-client.ts`](https://github.com/limlll/codex-webui/blob/main/web/src/api-client.ts) (REST client), [`web/src/routes/thread-view.tsx`](https://github.com/limlll/codex-webui/blob/main/web/src/routes/thread-view.tsx) (Thread interface), [`src/threads/threads.service.ts`](https://github.com/limlll/codex-webui/blob/main/src/threads/threads.service.ts) (Thread operations), [`src/files/files.controller.ts`](https://github.com/limlll/codex-webui/blob/main/src/files/files.controller.ts) (File endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser client"]
  node_web["Web application<br/>[App.tsx]"]
  node_thread_ui["Thread interface<br/>[thread-view.tsx]"]
  node_web_api["REST client<br/>[api-client.ts]"]
  node_socket["Live socket<br/>[socket.ts]"]
end

subgraph group_conversation["Conversation runtime"]
  node_thread_api["Thread endpoints"]
  node_thread_service["Thread operations<br/>[threads.service.ts]"]
  node_branching["Conversation branches"]
  node_approvals["Approval handling"]
  node_codex["Codex facade<br/>[codex.service.ts]"]
  node_process["Codex process manager"]
end

subgraph group_workspace["Workspace tools"]
  node_file_ui["File workspace UI<br/>[files-panel.tsx]"]
  node_file_api["File endpoints"]
  node_file_service["File operations<br/>[files.service.ts]"]
  node_archive["Archive browsing<br/>[archive.service.ts]"]
  node_terminal_ui["Terminal UI"]
  node_terminal_gateway["Terminal gateway"]
  node_terminal_service["Terminal sessions"]
end

subgraph group_integrations["Configuration integrations"]
  node_plugins["Plugin marketplace"]
  node_mcp["MCP management"]
  node_apps["Apps connectors<br/>[apps.controller.ts]"]
  node_apps_service["Apps service<br/>[apps.service.ts]"]
  node_onlyoffice["Office editor bridge"]
end

subgraph group_platform["Service platform"]
  node_settings["Runtime settings"]
  node_auth["Authentication<br/>[auth.module.ts]"]
  node_database[("SQLite state")]
end

node_user(("User"))
node_codex_server["Codex app-server"]

node_user -->|"uses"| node_web
node_web -->|"opens"| node_thread_ui
node_thread_ui -->|"requests"| node_web_api
node_thread_ui -->|"subscribes"| node_socket
node_web_api -->|"REST calls"| node_thread_api
node_thread_api -->|"delegates"| node_thread_service
node_thread_service -->|"Codex operations"| node_codex
node_codex -->|"requests"| node_process
node_process -->|"JSON-RPC"| node_codex_server
node_thread_service -->|"branch operations"| node_branching
node_thread_ui -->|"approval actions"| node_approvals
node_web_api -->|"REST calls"| node_file_api
node_file_ui -->|"file requests"| node_web_api
node_file_api -->|"delegates"| node_file_service
node_file_api -->|"archive operations"| node_archive
node_terminal_ui -->|"connects"| node_socket
node_socket -->|"Socket.IO"| node_terminal_gateway
node_terminal_gateway -->|"session operations"| node_terminal_service
node_web_api -->|"REST calls"| node_plugins
node_web_api -->|"REST calls"| node_mcp
node_web_api -->|"REST calls"| node_apps
node_apps -->|"delegates"| node_apps_service
node_apps_service -->|"JSON-RPC methods"| node_codex
node_web_api -.->|"editor requests"| node_onlyoffice
node_onlyoffice -.->|"validates paths"| node_file_service
node_onlyoffice -.->|"reads settings"| node_settings
node_thread_service -->|"persists state"| node_database
node_auth -->|"guards API"| node_web_api

click node_web "https://github.com/limlll/codex-webui/blob/main/web/src/App.tsx"
click node_thread_ui "https://github.com/limlll/codex-webui/blob/main/web/src/routes/thread-view.tsx"
click node_web_api "https://github.com/limlll/codex-webui/blob/main/web/src/api-client.ts"
click node_socket "https://github.com/limlll/codex-webui/blob/main/web/src/socket.ts"
click node_thread_api "https://github.com/limlll/codex-webui/blob/main/src/threads/threads.controller.ts"
click node_thread_service "https://github.com/limlll/codex-webui/blob/main/src/threads/threads.service.ts"
click node_branching "https://github.com/limlll/codex-webui/blob/main/src/conversation-branches/conversation-branches.service.ts"
click node_approvals "https://github.com/limlll/codex-webui/blob/main/src/pending-approvals/pending-approvals.service.ts"
click node_codex "https://github.com/limlll/codex-webui/blob/main/src/codex/codex.service.ts"
click node_process "https://github.com/limlll/codex-webui/blob/main/src/codex/codex-process-manager.service.ts"
click node_file_ui "https://github.com/limlll/codex-webui/blob/main/web/src/components/files/files-panel.tsx"
click node_file_api "https://github.com/limlll/codex-webui/blob/main/src/files/files.controller.ts"
click node_file_service "https://github.com/limlll/codex-webui/blob/main/src/files/files.service.ts"
click node_archive "https://github.com/limlll/codex-webui/blob/main/src/archive/archive.service.ts"
click node_terminal_ui "https://github.com/limlll/codex-webui/blob/main/web/src/components/terminal/terminal-workspace.tsx"
click node_terminal_gateway "https://github.com/limlll/codex-webui/blob/main/src/terminal/terminal.gateway.ts"
click node_terminal_service "https://github.com/limlll/codex-webui/blob/main/src/terminal/terminal.service.ts"
click node_plugins "https://github.com/limlll/codex-webui/blob/main/src/plugins/plugins.controller.ts"
click node_mcp "https://github.com/limlll/codex-webui/blob/main/src/mcp-servers/mcp-servers.controller.ts"
click node_apps "https://github.com/limlll/codex-webui/blob/main/src/apps/apps.controller.ts"
click node_apps_service "https://github.com/limlll/codex-webui/blob/main/src/apps/apps.service.ts"
click node_onlyoffice "https://github.com/limlll/codex-webui/blob/main/src/onlyoffice/onlyoffice.controller.ts"
click node_settings "https://github.com/limlll/codex-webui/blob/main/src/settings/settings.service.ts"
click node_auth "https://github.com/limlll/codex-webui/blob/main/src/auth/auth.module.ts"
click node_database "https://github.com/limlll/codex-webui/blob/main/src/database/database.service.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_web,node_thread_ui,node_web_api,node_socket,node_user toneBlue
class node_thread_api,node_thread_service,node_branching,node_approvals,node_codex,node_process toneAmber
class node_file_ui,node_file_api,node_file_service,node_archive,node_terminal_ui,node_terminal_gateway,node_terminal_service,node_codex_server toneMint
class node_plugins,node_mcp,node_apps,node_apps_service,node_onlyoffice toneRose
class node_settings,node_auth,node_database toneIndigo
```

## Components

### Browser client

- [Web application](https://github.com/limlll/codex-webui/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Thread interface](https://github.com/limlll/codex-webui/blob/main/web/src/routes/thread-view.tsx): `web/src/routes/thread-view.tsx`
- [REST client](https://github.com/limlll/codex-webui/blob/main/web/src/api-client.ts): `web/src/api-client.ts`
- [Live socket](https://github.com/limlll/codex-webui/blob/main/web/src/socket.ts): `web/src/socket.ts`

### Conversation runtime

- [Thread endpoints](https://github.com/limlll/codex-webui/blob/main/src/threads/threads.controller.ts): `src/threads/threads.controller.ts`
- [Thread operations](https://github.com/limlll/codex-webui/blob/main/src/threads/threads.service.ts): `src/threads/threads.service.ts`
- [Conversation branches](https://github.com/limlll/codex-webui/blob/main/src/conversation-branches/conversation-branches.service.ts): `src/conversation-branches/conversation-branches.service.ts`
- [Approval handling](https://github.com/limlll/codex-webui/blob/main/src/pending-approvals/pending-approvals.service.ts): `src/pending-approvals/pending-approvals.service.ts`
- [Codex facade](https://github.com/limlll/codex-webui/blob/main/src/codex/codex.service.ts): `src/codex/codex.service.ts`
- [Codex process manager](https://github.com/limlll/codex-webui/blob/main/src/codex/codex-process-manager.service.ts): `src/codex/codex-process-manager.service.ts`

### Workspace tools

- [File workspace UI](https://github.com/limlll/codex-webui/blob/main/web/src/components/files/files-panel.tsx): `web/src/components/files/files-panel.tsx`
- [File endpoints](https://github.com/limlll/codex-webui/blob/main/src/files/files.controller.ts): `src/files/files.controller.ts`
- [File operations](https://github.com/limlll/codex-webui/blob/main/src/files/files.service.ts): `src/files/files.service.ts`
- [Archive browsing](https://github.com/limlll/codex-webui/blob/main/src/archive/archive.service.ts): `src/archive/archive.service.ts`
- [Terminal UI](https://github.com/limlll/codex-webui/blob/main/web/src/components/terminal/terminal-workspace.tsx): `web/src/components/terminal/terminal-workspace.tsx`
- [Terminal gateway](https://github.com/limlll/codex-webui/blob/main/src/terminal/terminal.gateway.ts): `src/terminal/terminal.gateway.ts`
- [Terminal sessions](https://github.com/limlll/codex-webui/blob/main/src/terminal/terminal.service.ts): `src/terminal/terminal.service.ts`

### Configuration integrations

- [Plugin marketplace](https://github.com/limlll/codex-webui/blob/main/src/plugins/plugins.controller.ts): `src/plugins/plugins.controller.ts`
- [MCP management](https://github.com/limlll/codex-webui/blob/main/src/mcp-servers/mcp-servers.controller.ts): `src/mcp-servers/mcp-servers.controller.ts`
- [Apps connectors](https://github.com/limlll/codex-webui/blob/main/src/apps/apps.controller.ts): `src/apps/apps.controller.ts`
- [Apps service](https://github.com/limlll/codex-webui/blob/main/src/apps/apps.service.ts): `src/apps/apps.service.ts`
- [Office editor bridge](https://github.com/limlll/codex-webui/blob/main/src/onlyoffice/onlyoffice.controller.ts): `src/onlyoffice/onlyoffice.controller.ts`

### Service platform

- [Runtime settings](https://github.com/limlll/codex-webui/blob/main/src/settings/settings.service.ts): `src/settings/settings.service.ts`
- [Authentication](https://github.com/limlll/codex-webui/blob/main/src/auth/auth.module.ts): `src/auth/auth.module.ts`
- [SQLite state](https://github.com/limlll/codex-webui/blob/main/src/database/database.service.ts): `src/database/database.service.ts`

### Other components

- **User**
- **Codex app-server**

## Connections

- User → Web application: uses
- Web application → Thread interface: opens
- Thread interface → REST client: requests
- Thread interface → Live socket: subscribes
- REST client → Thread endpoints: REST calls
- Thread endpoints → Thread operations: delegates
- Thread operations → Codex facade: Codex operations
- Codex facade → Codex process manager: requests
- Codex process manager → Codex app-server: JSON-RPC
- Thread operations → Conversation branches: branch operations
- Thread interface → Approval handling: approval actions
- REST client → File endpoints: REST calls
- File workspace UI → REST client: file requests
- File endpoints → File operations: delegates
- File endpoints → Archive browsing: archive operations
- Terminal UI → Live socket: connects
- Live socket → Terminal gateway: Socket.IO
- Terminal gateway → Terminal sessions: session operations
- REST client → Plugin marketplace: REST calls
- REST client → MCP management: REST calls
- REST client → Apps connectors: REST calls
- Apps connectors → Apps service: delegates
- Apps service → Codex facade: JSON-RPC methods
- REST client → Office editor bridge: editor requests
- Office editor bridge → File operations: validates paths
- Office editor bridge → Runtime settings: reads settings
- Thread operations → SQLite state: persists state
- Authentication → REST client: guards API