> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pingdotgg/t3code/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Deep Dive

> Understand the technical architecture and design decisions behind T3 Code

## Overview

T3 Code is a minimal web GUI for code agents, built with a focus on performance, reliability, and maintainability. The system is designed around a WebSocket-based client-server architecture with provider abstraction.

## Core Principles

<CardGroup cols={2}>
  <Card title="Performance First" icon="gauge-high">
    Optimized for low latency and high throughput in event streaming
  </Card>

  <Card title="Reliability First" icon="shield-check">
    Predictable behavior under load, failures, and reconnections
  </Card>

  <Card title="Maintainability" icon="code">
    Long-term code health through shared logic and clear boundaries
  </Card>

  <Card title="Correctness" icon="circle-check">
    Robust over convenient when tradeoffs are required
  </Card>
</CardGroup>

<Warning>
  This is a **very early WIP**. Sweeping changes that improve long-term maintainability are encouraged.
</Warning>

## System Architecture

```mermaid theme={null}
graph TB
    Browser[Browser/Electron] --> WebApp[React Web App]
    WebApp <-->|WebSocket| WSServer[WebSocket Server]
    WSServer --> CodexMgr[Codex Manager]
    CodexMgr -->|JSON-RPC/stdio| Codex[Codex App Server]
    WSServer --> ProviderMgr[Provider Manager]
    ProviderMgr --> Sessions[Session State]
    WSServer --> OrchEngine[Orchestration Engine]
    OrchEngine --> EventStore[Event Store]
    EventStore --> SQLite[(SQLite DB)]
```

## Package Architecture

### `/apps/server` - WebSocket Server

**Purpose:** Node.js backend that orchestrates provider sessions and streams events to clients.

**Key Responsibilities:**

* Wraps Codex app-server (JSON-RPC over stdio)
* Manages WebSocket connections and protocol
* Orchestrates provider sessions and lifecycle
* Persists events and projections in SQLite
* Serves built web app as static files (production)

**Core Modules:**

<CodeGroup>
  ```typescript main.ts theme={null}
  // CLI entrypoint
  // Parses args, loads config, starts server
  import { t3Cli } from './main';
  ```

  ```typescript wsServer.ts theme={null}
  // WebSocket server and NativeApi routing
  // Handles connection lifecycle, auth, RPC
  import { Server } from './wsServer';
  ```

  ```typescript codexAppServerManager.ts theme={null}
  // Codex app-server process management
  // Session startup, resume, turn lifecycle
  import { CodexAppServerManager } from './codexAppServerManager';
  ```

  ```typescript providerManager.ts theme={null}
  // Provider dispatch and event coordination
  // Thread logging, runtime activity projection
  import { ProviderManager } from './providerManager';
  ```
</CodeGroup>

**Effect-TS Integration:**

The server uses Effect-TS for dependency injection and error handling:

```typescript theme={null}
// Service layers provide implementations
const ServerLive = Layer.mergeAll(
  ProviderServiceLive,
  OrchestrationEngineLive,
  GitServiceLive,
  TerminalManagerLive,
);

// Effects compose with type-safe dependencies
const program = Effect.gen(function* () {
  const provider = yield* ProviderService;
  const session = yield* provider.createSession(config);
  return session;
});
```

### `/apps/web` - React UI

**Purpose:** React + Vite frontend for session control, conversation, and event rendering.

**Key Responsibilities:**

* Session UX and conversation rendering
* WebSocket client and transport layer
* Client-side state management (Zustand)
* Terminal emulation (xterm.js)
* Real-time diff visualization

**State Management:**

```typescript theme={null}
// Global app state
import { useStore } from './store';

// Terminal state per session
import { useTerminalStore } from './terminalStateStore';

// Composer draft state
import { useComposerDraftStore } from './composerDraftStore';
```

**WebSocket Integration:**

```typescript wsTransport.ts theme={null}
// WebSocket client with reconnection logic
export class WsTransport {
  connect(url: string): Promise<void>;
  send(message: Protocol.ClientMessage): void;
  on(event: string, handler: Function): void;
}
```

**React Query:**

API calls use TanStack Query for caching and synchronization:

```typescript theme={null}
// Provider queries
import { useProviderQuery } from './lib/providerReactQuery';

// Git queries  
import { useGitQuery } from './lib/gitReactQuery';
```

### `/apps/desktop` - Electron Shell

**Purpose:** Native desktop wrapper with auto-updates and system integration.

**Key Responsibilities:**

* Spawns desktop-scoped `t3` backend process
* Loads shared web app in Electron renderer
* Auto-update support (electron-updater)
* Native system integration (menus, dialogs)

**Process Model:**

```typescript theme={null}
// Main process spawns backend
const backend = spawn('t3', ['--auth-token', token]);

// Renderer connects via WebSocket
const wsUrl = `ws://127.0.0.1:${port}?token=${token}`;
```

### `/packages/contracts` - Shared Schemas

**Purpose:** Effect/Schema definitions and TypeScript contracts for all protocol messages.

**Key Responsibilities:**

* Provider event schemas
* WebSocket protocol messages
* Model and session types
* Schema validation and encoding

<Note>
  Keep this package **schema-only** — no runtime logic!
</Note>

**Schema Examples:**

```typescript theme={null}
import * as S from 'effect/Schema';

// Provider runtime events
export const ProviderRuntimeEvent = S.Union(
  ProviderStarted,
  ToolInvoked,
  StreamChunk,
  TurnCompleted,
);

// WebSocket protocol
export const ClientMessage = S.Union(
  SendUserMessage,
  CancelTurn,
  ResumeSession,
);
```

### `/packages/shared` - Runtime Utilities

**Purpose:** Shared runtime utilities for both server and web.

**Key Responsibilities:**

* Model parsing and validation
* Network utilities
* Git helpers
* Shared business logic

**Subpath Exports:**

```typescript theme={null}
// Import from specific paths, not barrel index
import { parseModel } from '@t3tools/shared/model';
import { NetService } from '@t3tools/shared/Net';
import { GitUtils } from '@t3tools/shared/git';
```

## Data Flow

### User Message Flow

<Steps>
  <Step title="User Input">
    User types message in React composer component
  </Step>

  <Step title="WebSocket Send">
    Web app sends `SendUserMessage` via WebSocket
  </Step>

  <Step title="Provider Dispatch">
    Server dispatches to Codex app-server via JSON-RPC
  </Step>

  <Step title="Event Stream">
    Codex streams provider events back over stdio
  </Step>

  <Step title="Event Projection">
    Server projects events into orchestration domain events
  </Step>

  <Step title="WebSocket Push">
    Server pushes orchestration events to web via WebSocket
  </Step>

  <Step title="UI Update">
    React components render streaming response
  </Step>
</Steps>

### Event Sourcing

The server uses event sourcing for session state:

```typescript theme={null}
// Events are stored in SQLite
const event: OrchestrationEvent = {
  type: 'TurnStarted',
  sessionId,
  turnId,
  timestamp,
};

await eventStore.append(sessionId, event);

// Projections build read models
const readModel = await projectionQuery.getSession(sessionId);
```

**Benefits:**

* Full audit trail
* Session replay capability
* Temporal debugging
* Eventual consistency

## Codex App Server Integration

T3 Code is **Codex-first** and wraps the Codex app-server:

### JSON-RPC Protocol

Communication happens over stdio using JSON-RPC:

```typescript theme={null}
// Start session
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session.start",
  "params": { "workspaceRoot": "/path/to/project" }
}

// Provider events stream back
{
  "jsonrpc": "2.0",
  "method": "provider.event",
  "params": { "type": "tool_invoked", ... }
}
```

### Key Integration Points

| Module            | Responsibility                  | Location                       |
| ----------------- | ------------------------------- | ------------------------------ |
| Session lifecycle | Start, resume, stop sessions    | `codexAppServerManager.ts:39`  |
| Turn management   | Send messages, handle turns     | `codexAppServerManager.ts:156` |
| Event ingestion   | Stream provider events          | `providerManager.ts:84`        |
| NativeApi routing | Route NativeApi calls           | `wsServer.ts:203`              |
| Domain projection | Project to orchestration events | Server-side                    |

<Note>
  Read the [Codex App Server docs](https://developers.openai.com/codex/sdk/#app-server) for protocol details.
</Note>

## Performance Considerations

### WebSocket Optimization

* **Binary Protocol:** Consider MessagePack for reduced overhead
* **Backpressure:** Handle slow clients with buffering
* **Batching:** Batch rapid events for UI efficiency

### State Management

* **Selective Subscriptions:** Only subscribe to needed data
* **Memoization:** Use React.memo and useMemo aggressively
* **Virtual Scrolling:** Render large lists efficiently (@tanstack/react-virtual)

### Build Optimization

* **Code Splitting:** Vite automatically splits routes
* **Tree Shaking:** Import only what you need
* **Effect Optimization:** Effect-TS enables zero-cost abstractions

## Reliability Patterns

### Session Recovery

Sessions survive disconnections and restarts:

```typescript theme={null}
// Server persists session state
await sessionStore.save(session);

// Client reconnects and resumes
await transport.send({
  type: 'ResumeSession',
  sessionId,
});

// Server replays missed events
const events = await eventStore.getEvents(sessionId, fromSeq);
```

### Error Handling

Robust error boundaries at each layer:

```typescript theme={null}
// Effect error channels
const program = Effect.gen(function* () {
  return yield* operation;
}).pipe(
  Effect.catchTag('NetworkError', handleNetwork),
  Effect.catchTag('ProviderError', handleProvider),
  Effect.catchAll(handleUnknown),
);
```

### Graceful Degradation

* **Offline Mode:** Queue messages when disconnected
* **Partial Renders:** Show what's available during streams
* **Fallback UI:** Graceful error states

## Reference Implementations

For implementation guidance, reference:

<CardGroup cols={2}>
  <Card title="Codex (Official)" icon="github" href="https://github.com/openai/codex">
    Open-source Codex repository
  </Card>

  <Card title="Codex Monitor" icon="github" href="https://github.com/Dimillian/CodexMonitor">
    Tauri-based reference implementation
  </Card>
</CardGroup>

Use these for protocol handling, UX flows, and operational safeguards.

## Next Steps

<CardGroup cols={2}>
  <Card title="Monorepo Structure" icon="folder-tree" href="/development/monorepo-structure">
    Explore the workspace layout
  </Card>

  <Card title="Testing" icon="flask" href="/development/testing">
    Learn testing patterns
  </Card>
</CardGroup>