friuns2/codex-mobile

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.