Architecture

T3 Code runs as a Node.js WebSocket server that wraps codex app-server (JSON-RPC over stdio) and serves a React web app.

Components

• Browser app: The React app renders session state, owns the client-side WebSocket transport, and treats typed push events as the boundary between server runtime details and UI state.

• Server: apps/server is the main coordinator. It serves the web app, accepts WebSocket requests, waits for startup readiness before welcoming clients, and sends all outbound pushes through a single ordered push path.

• Provider runtime: codex app-server does the actual provider/session work. The server talks to it over JSON-RPC on stdio and translates those runtime events into the app's orchestration model.

• Background workers: Long-running async flows such as runtime ingestion, command reaction, and checkpoint processing run as queue-backed workers. This keeps work ordered, reduces timing races, and gives tests a deterministic way to wait for the system to go idle.

• Runtime signals: The server emits lightweight typed receipts when important async milestones finish, such as checkpoint capture, diff finalization, or a turn becoming fully quiescent. Tests and orchestration code wait on these signals instead of polling internal state.

• Server updates: A connected environment advertises whether its server can replace itself. When client and server versions differ, the browser selects an automatic, desktop-managed, or manual update path without changing connection ownership. See Server Update Architecture.

Event Lifecycle

Startup and client connect

1. The browser boots WsTransport and registers typed listeners in wsNativeApi.
2. The server accepts the connection in wsServer and brings up the runtime graph defined in serverLayers.
3. ServerReadiness waits until the key startup barriers are complete.
4. Once the server is ready, wsServer sends server.welcome from the contracts in ws.ts through ServerPushBus.
5. The browser receives that ordered push through WsTransport, and wsNativeApi uses it to seed local client state.

User turn flow

1. A user action in the browser becomes a typed request through WsTransport and the browser API layer in nativeApi.
2. wsServer decodes that request using the shared WebSocket contracts in ws.ts and routes it to the right service.
3. ProviderService starts or resumes a session and talks to codex app-server over JSON-RPC on stdio.
4. Provider-native events are pulled back into the server by ProviderRuntimeIngestion, which converts them into orchestration events.
5. OrchestrationEngine persists those events, updates the read model, and exposes them as domain events.
6. wsServer pushes those updates to the browser through ServerPushBus on channels defined in orchestration.ts.

Async completion flow

1. Some work continues after the initial request returns, especially in ProviderRuntimeIngestion, ProviderCommandReactor, and CheckpointReactor.
2. These flows run as queue-backed workers using DrainableWorker, which helps keep side effects ordered and test synchronization deterministic.
3. When a milestone completes, the server emits a typed receipt on RuntimeReceiptBus, such as checkpoint completion or turn quiescence.
4. Tests and orchestration code wait on those receipts instead of polling git state, projections, or timers.
5. Any user-visible state changes produced by that async work still go back through wsServer and ServerPushBus.