# friuns2/codex-mobile architecture

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

- Interactive diagram: https://gitdiagram.com/friuns2/codex-mobile
- Repository: https://github.com/friuns2/codex-mobile

## Overview

1. **Overall shape**
   - `codexapp` is a **Node.js 18+ local bridge** that exposes a **Vue browser UI** for Codex app-server workflows.
   - The main architecture is three-tier: **browser client** → **local HTTP server** → **Codex app-server / provider proxies / local OS services**.

2. **Frontend application**
   - The UI lives under `src/` and is a **Vue 3 single-page app** with `main.ts`, `App.vue`, `router/`, layouts, sidebar, and content panels.
   - Major surface areas are chat/thread handling, skills, review panes, account/config panels, terminal panels, and project/worktree controls.
   - Mobile behavior is treated as a first-class concern via dedicated composables and responsive layout components.

3. **Backend entry and HTTP surface**
   - The server side is centered on `src/server/httpServer.ts`, which wires the local web server and mounts feature routes.
   - Important route modules include `accountRoutes.ts`, `skillsRoutes.ts`, `localBrowseUi.ts`, `customEndpointProxy.ts`, `openRouterProxy.ts`, `unifiedResponsesProxy.ts`, `zenProxy.ts`, and `telegramThreadBridge.ts`.
   - `authMiddleware.ts`, `password.ts`, and runtime config logic enforce access control and environment-specific startup behavior.

4. **Codex app-server bridge**
   - `src/api/codexGateway.ts`, `codexRpcClient.ts`, and `src/server/codexAppServerBridge.ts` form the core integration layer to the upstream Codex app-server.
   - This bridge translates UI actions into app-server requests and turns app-server events/notifications back into UI state updates.
   - The repository includes a large contract surface for this integration under `documentation/app-server-schemas/`, which acts as the canonical protocol boundary.

5. **Protocol typing and normalization**
   - `src/api/appServerDtos.ts` and `src/api/normalizers/v2.ts` adapt app-server payloads into UI-friendly shapes.
   - The repo carries extensive generated or schema-derived types in `documentation/app-server-schemas/typescript/` and JSON schemas in `documentation/app-server-schemas/json/`.
   - This implies a strong contract-driven architecture: UI logic depends on normalized domain objects rather than raw wire payloads.

6. **Provider/model routing**
   - The server includes explicit proxy/broker layers for multiple upstream model formats: `openRouterProxy.ts`, `zenProxy.ts`, `unifiedResponsesProxy.ts`, and `customEndpointProxy.ts`.
   - `freeMode.ts`, `rateLimitDecodeRecovery.ts`, and provider/model-related tests indicate that model selection, auth state, and request format translation are separate concerns from the chat UI itself.
   - The UI therefore sits above a provider abstraction layer, not directly on one backend API.

7. **Conversation, thread, and project state**
   - Thread lifecycle and persistence are a major subsystem: list, load, resume, fork, archive, rollback, and diff behavior are represented throughout the UI and server.
   - Git-aware project behavior is built in via `reviewGit.ts`, `commandResolution.ts`, and worktree/rollback features in the UI and tests.
   - This repo treats “thread” and “project/worktree” as coupled domains, with the server responsible for canonical file-system and git operations.

8. **Terminal and command execution**
   - `src/server/terminalManager.ts` and the terminal panels in the UI provide an integrated shell experience inside the app.
   - Command execution is mediated through approval-oriented request/response flows in the app-server protocol rather than being a raw shell passthrough.
   - The architecture separates terminal orchestration from UI rendering, which matters for approvals, streaming output, and cancellation/interruption.

9. **Skills and plugin discovery**
   - Skills are handled as a dedicated subsystem with `skillsRoutes.ts`, the `SkillsHub` UI, composer skill picker, and GitHub sync composables.
   - The repo supports both local and remote skill sources, plus startup sync and live refresh behavior.
   - The architecture distinguishes “skill metadata/discovery” from “skill execution”, with the former surfaced in the UI and the latter mediated by the app-server bridge.

10. **Authentication, account, and runtime config**
   - Account/session state is handled server-side and reflected in the UI through account menus, rate-limit panels, and login flows.
   - The app supports multiple auth modes and dynamic runtime/provider configuration, which is why there are dedicated routes and DTOs for auth status, token refresh, and model lists.
   - This is not a stateless browser app: the server maintains operational context and forwards account state into the UI.

11. **Optional external bridges**
   - `telegramThreadBridge.ts` adds an alternate entry point where Telegram messages map to Codex threads, including allowlist-based authorization.
   - The README’s tunnel and Tailscale guidance show that the server is designed to be reachable through local, LAN, or private remote exposure patterns.
   - These integrations sit outside the core chat UI but share the same thread/control plane.

12. **Packaging and runtime delivery**
   - The repo uses Vite for the browser app, tsup for Node-side bundling, and a PWA layer (`public/sw.js`, manifest, icons) for installable browser use.
   - The workflows and scripts support cross-platform launch, Android/Termux usage, APK-related publishing, and test/debug helpers.
   - Architecture-wise, the same codebase ships both a browser SPA and a local Node server, with the server acting as the boundary to the filesystem, terminal, git, and upstream Codex services.

Main entry points: [`src/server/httpServer.ts`](https://github.com/friuns2/codex-mobile/blob/main/src/server/httpServer.ts) (HTTP server), [`src/App.vue`](https://github.com/friuns2/codex-mobile/blob/main/src/App.vue) (Browser UI), [`src/server/codexAppServerBridge.ts`](https://github.com/friuns2/codex-mobile/blob/main/src/server/codexAppServerBridge.ts) (App-server bridge), [`src/components/content/ThreadConversation.vue`](https://github.com/friuns2/codex-mobile/blob/main/src/components/content/ThreadConversation.vue) (Thread workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Vue UI"]
  node_browser_ui["Browser UI<br/>Vue 3 SPA<br/>[App.vue]"]
  node_app_boot["App boot<br/>Vue entry<br/>[main.ts]"]
  node_desktop_layout["Desktop layout<br/>[DesktopLayout.vue]"]
  node_thread_workspace["Thread workspace<br/>conversation UI"]
  node_sidebar_nav["Sidebar nav<br/>navigation UI"]
  node_accounts_panel["Accounts panel<br/>account UI<br/>[AccountMenu.vue]"]
  node_skills_hub["Skills hub<br/>skills UI<br/>[SkillsHub.vue]"]
  node_review_pane["Review pane<br/>review UI<br/>[ReviewPane.vue]"]
  node_mobile_state["Mobile state<br/>composables<br/>[useMobile.ts]"]
end

subgraph group_backend["Local Server"]
  node_http_server["HTTP server<br/>local server<br/>[httpServer.ts]"]
  node_server_bridge["App-server bridge"]
  node_gateway_client["Gateway client<br/>rpc client<br/>[codexGateway.ts]"]
  node_auth_config["Auth config<br/>server config<br/>[authMiddleware.ts]"]
  node_account_routes["Account routes<br/>route module<br/>[accountRoutes.ts]"]
  node_skills_routes["Skills routes<br/>route module<br/>[skillsRoutes.ts]"]
  node_provider_proxies["Provider proxies<br/>proxy layer<br/>[openRouterProxy.ts]"]
  node_terminal_mgr["Terminal mgr<br/>terminal orchestration<br/>[terminalManager.ts]"]
  node_git_worktree["Git worktrees<br/>git ops<br/>[reviewGit.ts]"]
  node_telegram_bridge["Telegram bridge<br/>external bridge"]
end

subgraph group_contracts["Protocol"]
  node_dto_normalization["DTO normalize<br/>adapter<br/>[appServerDtos.ts]"]
  node_protocol_schemas["Protocol schemas<br/>contract docs"]
end

subgraph group_runtime["Runtime"]
  node_cli_entry["CLI entry<br/>node cli<br/>[index.ts]"]
end

node_app_boot -->|"mounts"| node_browser_ui
node_browser_ui -->|"uses"| node_desktop_layout
node_desktop_layout -->|"contains"| node_thread_workspace
node_desktop_layout -->|"contains"| node_sidebar_nav
node_thread_workspace -->|"opens"| node_review_pane
node_thread_workspace -.->|"drives"| node_terminal_mgr
node_browser_ui -->|"shows"| node_accounts_panel
node_browser_ui -->|"shows"| node_skills_hub
node_browser_ui -.->|"adapts with"| node_mobile_state
node_http_server -->|"wires"| node_server_bridge
node_http_server -->|"mounts"| node_account_routes
node_http_server -->|"mounts"| node_skills_routes
node_http_server -->|"mounts"| node_provider_proxies
node_http_server -->|"mounts"| node_telegram_bridge
node_server_bridge -->|"calls"| node_gateway_client
node_gateway_client -->|"maps to"| node_dto_normalization
node_dto_normalization -.->|"follows"| node_protocol_schemas
node_server_bridge -.->|"speaks"| node_protocol_schemas
node_account_routes -->|"depends on"| node_auth_config
node_skills_routes -->|"queries"| node_server_bridge
node_provider_proxies -->|"feeds"| node_gateway_client
node_thread_workspace -->|"syncs with"| node_server_bridge
node_sidebar_nav -->|"uses"| node_git_worktree
node_cli_entry -->|"starts"| node_http_server

click node_browser_ui "https://github.com/friuns2/codex-mobile/blob/main/src/App.vue"
click node_app_boot "https://github.com/friuns2/codex-mobile/blob/main/src/main.ts"
click node_desktop_layout "https://github.com/friuns2/codex-mobile/blob/main/src/components/layout/DesktopLayout.vue"
click node_thread_workspace "https://github.com/friuns2/codex-mobile/blob/main/src/components/content/ThreadConversation.vue"
click node_sidebar_nav "https://github.com/friuns2/codex-mobile/blob/main/src/components/sidebar/SidebarPrimaryNav.vue"
click node_accounts_panel "https://github.com/friuns2/codex-mobile/blob/main/src/components/content/AccountMenu.vue"
click node_skills_hub "https://github.com/friuns2/codex-mobile/blob/main/src/components/content/SkillsHub.vue"
click node_review_pane "https://github.com/friuns2/codex-mobile/blob/main/src/components/content/ReviewPane.vue"
click node_mobile_state "https://github.com/friuns2/codex-mobile/blob/main/src/composables/useMobile.ts"
click node_http_server "https://github.com/friuns2/codex-mobile/blob/main/src/server/httpServer.ts"
click node_server_bridge "https://github.com/friuns2/codex-mobile/blob/main/src/server/codexAppServerBridge.ts"
click node_gateway_client "https://github.com/friuns2/codex-mobile/blob/main/src/api/codexGateway.ts"
click node_dto_normalization "https://github.com/friuns2/codex-mobile/blob/main/src/api/appServerDtos.ts"
click node_protocol_schemas "https://github.com/friuns2/codex-mobile/blob/main/documentation/app-server-schemas/json/codex_app_server_protocol.schemas.json"
click node_auth_config "https://github.com/friuns2/codex-mobile/blob/main/src/server/authMiddleware.ts"
click node_account_routes "https://github.com/friuns2/codex-mobile/blob/main/src/server/accountRoutes.ts"
click node_skills_routes "https://github.com/friuns2/codex-mobile/blob/main/src/server/skillsRoutes.ts"
click node_provider_proxies "https://github.com/friuns2/codex-mobile/blob/main/src/server/openRouterProxy.ts"
click node_terminal_mgr "https://github.com/friuns2/codex-mobile/blob/main/src/server/terminalManager.ts"
click node_git_worktree "https://github.com/friuns2/codex-mobile/blob/main/src/server/reviewGit.ts"
click node_telegram_bridge "https://github.com/friuns2/codex-mobile/blob/main/src/server/telegramThreadBridge.ts"
click node_cli_entry "https://github.com/friuns2/codex-mobile/blob/main/src/cli/index.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_browser_ui,node_app_boot,node_desktop_layout,node_thread_workspace,node_sidebar_nav,node_accounts_panel,node_skills_hub,node_review_pane,node_mobile_state toneBlue
class node_http_server,node_server_bridge,node_gateway_client,node_auth_config,node_account_routes,node_skills_routes,node_provider_proxies,node_terminal_mgr,node_git_worktree,node_telegram_bridge toneAmber
class node_dto_normalization,node_protocol_schemas toneMint
class node_cli_entry toneRose
```

## Components

### Vue UI

Browser SPA and presentation layer

- [Browser UI](https://github.com/friuns2/codex-mobile/blob/main/src/App.vue): Vue 3 SPA · Main browser application shell and navigation. · `src/App.vue`
- [App boot](https://github.com/friuns2/codex-mobile/blob/main/src/main.ts): Vue entry · Bootstraps the client app and router. · `src/main.ts`
- [Desktop layout](https://github.com/friuns2/codex-mobile/blob/main/src/components/layout/DesktopLayout.vue): layout · Primary responsive shell for desktop and mobile surfaces. · `src/components/layout/DesktopLayout.vue`
- [Thread workspace](https://github.com/friuns2/codex-mobile/blob/main/src/components/content/ThreadConversation.vue): conversation UI · Core chat, composer, pending actions, and terminal panels. · `src/components/content/ThreadConversation.vue`
- [Sidebar nav](https://github.com/friuns2/codex-mobile/blob/main/src/components/sidebar/SidebarPrimaryNav.vue): navigation UI · Thread tree, project controls, and primary navigation. · `src/components/sidebar/SidebarPrimaryNav.vue`
- [Accounts panel](https://github.com/friuns2/codex-mobile/blob/main/src/components/content/AccountMenu.vue): account UI · Login, auth state, and rate-limit/account views. · `src/components/content/AccountMenu.vue`
- [Skills hub](https://github.com/friuns2/codex-mobile/blob/main/src/components/content/SkillsHub.vue): skills UI · Skill discovery, selection, detail, and sync surfaces. · `src/components/content/SkillsHub.vue`
- [Review pane](https://github.com/friuns2/codex-mobile/blob/main/src/components/content/ReviewPane.vue): review UI · Git-aware review, diff, and rollback-oriented UI. · `src/components/content/ReviewPane.vue`
- [Mobile state](https://github.com/friuns2/codex-mobile/blob/main/src/composables/useMobile.ts): composables · Responsive/mobile behavior and UI state helpers. · `src/composables/useMobile.ts`

### Local Server

Node.js HTTP surface and bridge logic

- [HTTP server](https://github.com/friuns2/codex-mobile/blob/main/src/server/httpServer.ts): local server · Local web server that mounts the app and feature routes. · `src/server/httpServer.ts`
- [App-server bridge](https://github.com/friuns2/codex-mobile/blob/main/src/server/codexAppServerBridge.ts): bridge · Translates UI intents into Codex app-server requests and events. · `src/server/codexAppServerBridge.ts`
- [Gateway client](https://github.com/friuns2/codex-mobile/blob/main/src/api/codexGateway.ts): rpc client · Client-side gateway and RPC wiring to the upstream app-server. · `src/api/codexGateway.ts`
- [Auth config](https://github.com/friuns2/codex-mobile/blob/main/src/server/authMiddleware.ts): server config · Access control, password checks, and runtime-specific startup rules. · `src/server/authMiddleware.ts`
- [Account routes](https://github.com/friuns2/codex-mobile/blob/main/src/server/accountRoutes.ts): route module · Account/session endpoints and related state propagation. · `src/server/accountRoutes.ts`
- [Skills routes](https://github.com/friuns2/codex-mobile/blob/main/src/server/skillsRoutes.ts): route module · Routes for listing, syncing, and updating skills metadata. · `src/server/skillsRoutes.ts`
- [Provider proxies](https://github.com/friuns2/codex-mobile/blob/main/src/server/openRouterProxy.ts): proxy layer · Model/provider translation and passthrough layers for multiple upstream formats. · `src/server/openRouterProxy.ts`
- [Terminal mgr](https://github.com/friuns2/codex-mobile/blob/main/src/server/terminalManager.ts): terminal orchestration · Integrated shell/session orchestration and streaming output handling. · `src/server/terminalManager.ts`
- [Git worktrees](https://github.com/friuns2/codex-mobile/blob/main/src/server/reviewGit.ts): git ops · Project, rollback, diff, and worktree operations. · `src/server/reviewGit.ts`
- [Telegram bridge](https://github.com/friuns2/codex-mobile/blob/main/src/server/telegramThreadBridge.ts): external bridge · Alternate message ingress that maps Telegram messages to threads. · `src/server/telegramThreadBridge.ts`

### Protocol

Codex app-server schemas and normalized DTOs

- [DTO normalize](https://github.com/friuns2/codex-mobile/blob/main/src/api/appServerDtos.ts): adapter · Normalizes raw protocol payloads into UI-friendly shapes. · `src/api/appServerDtos.ts`
- [Protocol schemas](https://github.com/friuns2/codex-mobile/blob/main/documentation/app-server-schemas/json/codex_app_server_protocol.schemas.json): contract docs · Canonical app-server JSON and TypeScript schema boundary. · `documentation/app-server-schemas/json/codex_app_server_protocol.schemas.json`

### Runtime

Packaging, CLI, and delivery entrypoints

- [CLI entry](https://github.com/friuns2/codex-mobile/blob/main/src/cli/index.ts): node cli · Command-line bootstrap for local runtime and launch modes. · `src/cli/index.ts`

## Connections

- App boot → Browser UI: mounts · Bootstraps the Vue application shell.
- Browser UI → Desktop layout: uses · Main app renders through the responsive layout shell.
- Desktop layout → Thread workspace: contains · Primary content area for threads and composer flows.
- Desktop layout → Sidebar nav: contains · Sidebar provides thread and project navigation.
- Thread workspace → Review pane: opens · Conversation views can surface review and diff context.
- Thread workspace → Terminal mgr: drives · Terminal panel mirrors server-managed terminal sessions.
- Browser UI → Accounts panel: shows · Account state is surfaced in the client UI.
- Browser UI → Skills hub: shows · Skill discovery and sync are part of the main UI.
- Browser UI → Mobile state: adapts with · Responsive and mobile-first behavior influences layout and controls.
- HTTP server → App-server bridge: wires · Server mounts the Codex app-server integration boundary.
- HTTP server → Account routes: mounts · Exposes account/session HTTP endpoints.
- HTTP server → Skills routes: mounts · Exposes skills discovery and sync HTTP endpoints.
- HTTP server → Provider proxies: mounts · Hosts upstream provider/model proxy endpoints.
- HTTP server → Telegram bridge: mounts · Optional alternate ingress for Telegram thread control.
- App-server bridge → Gateway client: calls · Bridge delegates protocol traffic through the gateway client.
- Gateway client → DTO normalize: maps to · Raw responses are normalized before reaching the UI.
- DTO normalize → Protocol schemas: follows · Normalization is defined against the contract schemas.
- App-server bridge → Protocol schemas: speaks · Bridge behavior is constrained by the app-server contract.
- Account routes → Auth config: depends on · Account handling is gated by auth and runtime config.
- Skills routes → App-server bridge: queries · Skills metadata comes from the app-server bridge.
- Provider proxies → Gateway client: feeds · Provider/model proxies integrate with the same upstream control plane.
- Thread workspace → App-server bridge: syncs with · Thread lifecycle and turn actions flow through the bridge.
- Sidebar nav → Git worktrees: uses · Project and worktree controls depend on git-aware server operations.
- CLI entry → HTTP server: starts · CLI bootstraps the local server runtime.