docs/Architecture.md

Ref: main worktree-web-client-spec   Size: 1.4 KiB   History

# Architecture

Mux separates terminal execution from terminal presentation. The daemon owns sessions, PTYs, and the Ghostty VT engine. Each client holds a replica of the terminal grid: it receives a cell snapshot when needed, then row deltas as the authoritative grid changes.

```mermaid
flowchart LR
  B[Browser client replica]
  W[`mux web` hub]
  S[Unix socket]
  H[SSH handoff]
  Q[QUIC]
  V[`--via` command]

  subgraph Daemon
    D[mux daemon]
    VT[Daemon-owned Ghostty VT state]
    D --> VT
  end

  B -->|local HTTP/WebSocket: input and commands| W
  W -->|input and commands| S --> D
  W -->|input and commands| H --> D
  W -->|input and commands| Q --> D
  W -->|input and commands| V --> D
  VT -->|snapshots and row deltas| S --> W
  VT -->|snapshots and row deltas| H --> W
  VT -->|snapshots and row deltas| Q --> W
  VT -->|snapshots and row deltas| V --> W
  W -->|local HTTP/WebSocket: snapshots and row deltas| B
```

The browser reaches a local `mux web` hub over HTTP and WebSocket; it does not
speak directly to a Unix socket. The hub uses the same client services to reach
daemon sessions through a local Unix socket, SSH handoff, QUIC, or `--via`.
Those transports carry bytes and do not interpret terminal frames.

The daemon owns VT parsing and terminal state. It receives client input and
commands, then sends snapshots and row deltas for each client replica to apply
before rendering.