# littleorgans/transport-matters architecture

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

- Interactive diagram: https://gitdiagram.com/littleorgans/transport-matters
- Repository: https://github.com/littleorgans/transport-matters

## Overview

1. **What this repo is**
   Transport Matters is a local control plane for agent traffic. It sits between a coding agent and its upstream provider, captures each turn, lets you inspect/edit the next outbound request, and persists artifacts for later replay and debugging.

2. **Top-level shape**
   This is a three-part monorepo:
   - **`api/`**: the Python backend, CLI, proxy orchestration, capture pipeline, and FastAPI control API
   - **`www/`**: the React/Vite web UI that renders exchanges, session timelines, editors, and the canvas experience
   - **`desktop/`**: an Electron shell that launches the backend and opens the UI as a desktop app
   There is also a small **`shared/`** folder for cross-cutting schema data.

3. **Primary runtime path**
   The main operational flow is:
   - user runs `transport-matters claude`, `codex`, or `desktop`
   - the CLI starts a local backend and a proxy
   - the managed agent process is configured to talk through that proxy
   - upstream provider traffic is intercepted, parsed, optionally paused, edited, then forwarded
   - captured results are stored locally and surfaced in the UI

4. **Provider-specific transport boundary**
   The backend has distinct paths for:
   - **Claude Code**: reverse proxy in front of `api.anthropic.com`, with `ANTHROPIC_BASE_URL`
   - **Codex**: explicit HTTPS proxy for ChatGPT/Codex websocket traffic, with managed `HTTPS_PROXY`, `HTTP_PROXY`, and `CODEX_CA_CERTIFICATE`
   These provider paths are not just config variants; they drive different parsing, serialization, and diagnostics logic under `api/src/transport_matters/codex/` and `api/src/transport_matters/adapters/`.

5. **Transport capture and curation pipeline**
   The transport layer converts raw provider requests into an internal request representation, applies deterministic curation rules, can stop at a breakpoint for manual editing, then serializes back to provider wire format. This is the architectural core of the repo: raw network traffic in, curated request back out, with both forms preserved.

6. **Session, run, and artifact storage**
   Captures are organized per workspace and per run. The backend writes run-scoped artifacts under `~/.transport-matters/workspaces/{slug}/{hash}/{run_id}/...`, including lock files, manifests, `index.jsonl`, exchange records, and proxy logs. This run isolation is important: multiple launches from the same working directory are intentionally supported without collisions.

7. **Database-backed session state**
   The backend also uses a Postgres-backed session store, managed through `api/migrations/` and the `session/` package. Disk storage holds artifacts and logs; the database stores the structured session/index metadata used by the API and UI. The two storage layers are complementary rather than redundant.

8. **FastAPI control plane**
   The `api/src/transport_matters/api/v1/` package exposes the control API:
   - session and run listing
   - exchange retrieval and filtering
   - breakpoint control
   - runtime template and override management
   - local file/resource content access
   - streaming endpoints for live updates
   The API is the read/write control surface for the UI and for CLI-driven orchestration.

9. **Backend orchestration and process supervision**
   The backend has explicit process-management subsystems:
   - `run_manager`, `supervisor`, `shared_proxy`, and `pty_session` manage child processes and attached terminals
   - `launch_*` and `runtime_*` modules shape how a run is started and tracked
   - `shared_proxy/` coordinates detached backend instances and their process lifecycle
   This is why the system can support detached desktop backends, live tails, and multiple concurrent runs in one workspace.

10. **CLI as the operator entrypoint**
    The CLI package is a real subsystem, not a thin wrapper. It handles command dispatch, launch profiles, path resolution, port selection, health checks, trust setup, Codex/Claude-specific bootstrapping, and “doctor”/“tail”/“list”/“paths” operational commands. The CLI is the first boundary that decides whether the repo behaves like a proxy runner, a backend service, or a desktop launcher.

11. **Web UI architecture**
    The `www/` app is a client-side UI for inspecting and controlling captures. It is organized around:
    - a **session canvas** with panes, docking, drag/drop, route switching, and persistence
    - an **exchange inspector** for turn details and transport timelines
    - **breakpoint and override editors**
    - **resource viewers** for text, JSON, images, markdown, binary, and provider artifacts
    The UI consumes backend APIs and live event streams; it does not own the authoritative session state.

12. **Live data flow into the UI**
    The UI has a stream-oriented path from backend to frontend:
    - session events and exchange updates are received via streaming hooks
    - reducers/store modules normalize those events into UI state
    - panes render from that state, while persistence modules remember layout and user choices
    This streaming model is central for “live run” inspection and for the canvas/terminal views.

13. **Desktop shell boundary**
    `desktop/` packages the experience as Electron:
    - main process launches or connects to the backend
    - preload bridges expose a controlled API to the renderer
    - renderer hosts the web app surface
    The desktop shell is mostly about process lifecycle, backend health detection, and window management; the actual product logic still lives in `api/` and `www/`.

14. **Shared contracts and test fixtures**
    The repo relies heavily on explicit contracts and fixtures:
    - JSON spec files in `shared/`
    - provider transcripts and rollout fixtures in `api/tests/fixtures/`
    - extensive tests for transport parsing, storage, UI reducers, and desktop integration
    These fixtures are part of the architecture because they encode provider wire formats and replay scenarios the system must preserve exactly.

15. **External dependencies that matter**
    The important external systems are:
    - **Anthropic API** for Claude Code traffic
    - **ChatGPT/Codex websocket backend** for Codex traffic
    - **Postgres** for the session store
    - **mitmproxy** for interception and explicit proxying
    - **Electron** for the desktop wrapper
    The design deliberately avoids system-wide proxy or certificate installation by keeping trust and proxy scope process-local.

Main entry points: [`www/src/session-canvas/route.ts`](https://github.com/littleorgans/transport-matters/blob/main/www/src/session-canvas/route.ts) (Session canvas), [`api/src/transport_matters/main.py`](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/main.py) (Backend app), [`api/src/transport_matters/api/v1/router.py`](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/api/v1/router.py) (Control API), [`api/src/transport_matters/session/__init__.py`](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/session/__init__.py) (Session package)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["api"]
  node_api_cli["CLI entry<br/>operator entrypoint<br/>[__main__.py]"]
  node_api_main["Backend app<br/>backend service<br/>[main.py]"]
  node_api_shared_proxy["Shared proxy<br/>process supervisor<br/>[core.py]"]
  node_api_run_manager["Run manager<br/>run orchestration<br/>[run_manager.py]"]
  node_api_request_pipeline["Request pipeline<br/>capture core"]
  node_api_captured_codex["Codex transport<br/>provider transport<br/>[transport.py]"]
  node_api_adapters["Claude adapter<br/>provider adapter<br/>[anthropic.py]"]
  node_api_exchange_recorder["Exchange recorder<br/>artifact capture"]
  node_api_storage[("Disk storage<br/>artifact store<br/>[disk.py]")]
  node_api_session_store[("Session store<br/>postgres state<br/>[dao.py]")]
  node_api_api_v1["Control API<br/>fastapi routes<br/>[router.py]"]
  node_api_session["Session package<br/>session model<br/>[__init__.py]"]
  node_api_index["Indexing<br/>session index<br/>[__init__.py]"]
  node_api_supervisor["Supervisor<br/>process control<br/>[supervisor.py]"]
end

subgraph group_web["www"]
  node_web_app["Web app<br/>react app<br/>[app.tsx]"]
  node_web_canvas["Session canvas<br/>canvas ui<br/>[route.ts]"]
  node_web_stream["Live stream<br/>state stream"]
  node_web_inspector["Exchange inspector<br/>inspection ui<br/>[ExchangeDetail.tsx]"]
  node_web_editors["Breakpoint editor<br/>override editor"]
  node_web_viewers["Resource viewers<br/>viewer suite<br/>[ResourcePane.tsx]"]
  node_web_state["UI stores<br/>client state<br/>[uiStore.ts]"]
end

subgraph group_desktop["desktop"]
  node_desktop_main["Main process<br/>electron main<br/>[main.ts]"]
  node_desktop_preload["Preload bridge<br/>electron bridge<br/>[preload.cts]"]
  node_desktop_window["Window shell<br/>window management<br/>[window.ts]"]
end

subgraph group_shared["shared"]
  node_shared_contracts["Shared specs<br/>schema contracts"]
end

node_api_cli -->|"starts"| node_api_main
node_api_cli -->|"coordinates"| node_api_shared_proxy
node_api_cli -->|"spawns"| node_api_supervisor
node_api_cli -->|"desktop cmd"| node_desktop_main
node_api_main -->|"serves"| node_api_api_v1
node_api_main -->|"reads/writes"| node_api_session_store
node_api_main -->|"persists"| node_api_storage
node_api_main -->|"orchestrates"| node_api_run_manager
node_api_run_manager -->|"attaches"| node_api_shared_proxy
node_api_run_manager -->|"supervises"| node_api_supervisor
node_api_run_manager -->|"captures"| node_api_exchange_recorder
node_api_exchange_recorder -->|"routes through"| node_api_request_pipeline
node_api_request_pipeline -->|"codex path"| node_api_captured_codex
node_api_request_pipeline -->|"claude path"| node_api_adapters
node_api_request_pipeline -->|"archives"| node_api_storage
node_api_session -->|"loads/stores"| node_api_storage
node_api_session -->|"indexes"| node_api_session_store
node_api_index -->|"builds on"| node_api_session
node_web_app -->|"hosts"| node_web_canvas
node_web_canvas -->|"subscribes"| node_web_stream
node_web_canvas -->|"renders"| node_web_inspector
node_web_canvas -->|"edits"| node_web_editors
node_web_canvas -->|"views"| node_web_viewers
node_web_stream -->|"updates"| node_web_state
node_web_app -->|"persists"| node_web_state
node_desktop_main -->|"bridges"| node_desktop_preload
node_desktop_main -->|"opens"| node_desktop_window
node_desktop_main -->|"launches/connects"| node_api_main
node_desktop_window -->|"loads"| node_web_app
node_web_canvas -->|"calls"| node_api_api_v1
node_web_stream -->|"streams"| node_api_api_v1
node_api_api_v1 -->|"queries"| node_api_session
node_api_api_v1 -->|"reads artifacts"| node_api_storage
node_shared_contracts -.->|"contracts"| node_api_session
node_shared_contracts -.->|"types"| node_web_state

click node_api_cli "https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/cli/__main__.py"
click node_api_main "https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/main.py"
click node_api_shared_proxy "https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/shared_proxy/core.py"
click node_api_run_manager "https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/run_manager.py"
click node_api_request_pipeline "https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/request_pipeline.py"
click node_api_captured_codex "https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/codex/transport.py"
click node_api_adapters "https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/adapters/anthropic.py"
click node_api_exchange_recorder "https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/exchange_recorder.py"
click node_api_storage "https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/storage/disk.py"
click node_api_session_store "https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/session/dao.py"
click node_api_api_v1 "https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/api/v1/router.py"
click node_api_session "https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/session/__init__.py"
click node_api_index "https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/index/__init__.py"
click node_api_supervisor "https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/supervisor.py"
click node_web_app "https://github.com/littleorgans/transport-matters/blob/main/www/src/app.tsx"
click node_web_canvas "https://github.com/littleorgans/transport-matters/blob/main/www/src/session-canvas/route.ts"
click node_web_stream "https://github.com/littleorgans/transport-matters/blob/main/www/src/session-canvas/stream/useSessionEventStream.ts"
click node_web_inspector "https://github.com/littleorgans/transport-matters/blob/main/www/src/components/ExchangeDetail.tsx"
click node_web_editors "https://github.com/littleorgans/transport-matters/blob/main/www/src/components/editor/BreakpointEditor.tsx"
click node_web_viewers "https://github.com/littleorgans/transport-matters/blob/main/www/src/session-canvas/viewers/resource/ResourcePane.tsx"
click node_web_state "https://github.com/littleorgans/transport-matters/blob/main/www/src/stores/uiStore.ts"
click node_desktop_main "https://github.com/littleorgans/transport-matters/blob/main/desktop/src/main.ts"
click node_desktop_preload "https://github.com/littleorgans/transport-matters/blob/main/desktop/src/preload.cts"
click node_desktop_window "https://github.com/littleorgans/transport-matters/blob/main/desktop/src/window.ts"
click node_shared_contracts "https://github.com/littleorgans/transport-matters/blob/main/shared/override_targets_v1.json"

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_api_cli,node_api_main,node_api_shared_proxy,node_api_run_manager,node_api_request_pipeline,node_api_captured_codex,node_api_adapters,node_api_exchange_recorder,node_api_storage,node_api_session_store,node_api_api_v1,node_api_session,node_api_index,node_api_supervisor toneBlue
class node_web_app,node_web_canvas,node_web_stream,node_web_inspector,node_web_editors,node_web_viewers,node_web_state toneAmber
class node_desktop_main,node_desktop_preload,node_desktop_window toneMint
class node_shared_contracts toneRose
```

## Components

### api

Python backend, CLI, proxy orchestration, capture pipeline, and control API

- [CLI entry](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/cli/__main__.py): operator entrypoint · Dispatches claude, codex, desktop, and operational commands · `api/src/transport_matters/cli/__main__.py`
- [Backend app](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/main.py): backend service · Starts the FastAPI control plane and runtime lifecycle · `api/src/transport_matters/main.py`
- [Shared proxy](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/shared_proxy/core.py): process supervisor · Manages detached backend instances and proxy process lifecycle · `api/src/transport_matters/shared_proxy/core.py`
- [Run manager](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/run_manager.py): run orchestration · Coordinates launches, supervision, and attached terminals · `api/src/transport_matters/run_manager.py`
- [Request pipeline](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/request_pipeline.py): capture core · Curates raw provider traffic into editable outbound requests and back · `api/src/transport_matters/request_pipeline.py`
- [Codex transport](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/codex/transport.py): provider transport · Codex-specific parsing, repair, serialization, and diagnostics · `api/src/transport_matters/codex/transport.py`
- [Claude adapter](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/adapters/anthropic.py): provider adapter · Claude-specific request and response adaptation boundary · `api/src/transport_matters/adapters/anthropic.py`
- [Exchange recorder](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/exchange_recorder.py): artifact capture · Records exchanges and artifacts from transport activity · `api/src/transport_matters/exchange_recorder.py`
- [Disk storage](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/storage/disk.py): artifact store · Persists run-scoped files, manifests, logs, and transcripts · `api/src/transport_matters/storage/disk.py`
- [Session store](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/session/dao.py): postgres state · Stores structured session and index metadata for API and UI · `api/src/transport_matters/session/dao.py`
- [Control API](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/api/v1/router.py): fastapi routes · Session, run, exchange, breakpoint, override, and stream endpoints · `api/src/transport_matters/api/v1/router.py`
- [Session package](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/session/__init__.py): session model · Ingests, indexes, streams, and queries session state · `api/src/transport_matters/session/__init__.py`
- [Indexing](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/index/__init__.py): session index · Builds session listings, tailing, and replay-oriented indexes · `api/src/transport_matters/index/__init__.py`
- [Supervisor](https://github.com/littleorgans/transport-matters/blob/main/api/src/transport_matters/supervisor.py): process control · Launches and monitors child processes and PTY-backed sessions · `api/src/transport_matters/supervisor.py`

### www

React/Vite UI for inspecting and controlling sessions

- [Web app](https://github.com/littleorgans/transport-matters/blob/main/www/src/app.tsx): react app · Client-side UI shell and route composition · `www/src/app.tsx`
- [Session canvas](https://github.com/littleorgans/transport-matters/blob/main/www/src/session-canvas/route.ts): canvas ui · Dockable session workspace with panes, routes, and persistence · `www/src/session-canvas/route.ts`
- [Live stream](https://github.com/littleorgans/transport-matters/blob/main/www/src/session-canvas/stream/useSessionEventStream.ts): state stream · Normalizes backend session events into frontend state · `www/src/session-canvas/stream/useSessionEventStream.ts`
- [Exchange inspector](https://github.com/littleorgans/transport-matters/blob/main/www/src/components/ExchangeDetail.tsx): inspection ui · Renders exchange lists, details, timelines, and transport views · `www/src/components/ExchangeDetail.tsx`
- [Breakpoint editor](https://github.com/littleorgans/transport-matters/blob/main/www/src/components/editor/BreakpointEditor.tsx): override editor · Edits breakpoints, overrides, sampling, and message mutations · `www/src/components/editor/BreakpointEditor.tsx`
- [Resource viewers](https://github.com/littleorgans/transport-matters/blob/main/www/src/session-canvas/viewers/resource/ResourcePane.tsx): viewer suite · Displays text, JSON, markdown, image, binary, and provider artifacts · `www/src/session-canvas/viewers/resource/ResourcePane.tsx`
- [UI stores](https://github.com/littleorgans/transport-matters/blob/main/www/src/stores/uiStore.ts): client state · Holds overlays, theme, keymaps, and persisted UI preferences · `www/src/stores/uiStore.ts`

### desktop

Electron shell around the backend and web UI

- [Main process](https://github.com/littleorgans/transport-matters/blob/main/desktop/src/main.ts): electron main · Launches or connects to the backend and manages desktop lifecycle · `desktop/src/main.ts`
- [Preload bridge](https://github.com/littleorgans/transport-matters/blob/main/desktop/src/preload.cts): electron bridge · Exposes a controlled renderer API from the Electron preload · `desktop/src/preload.cts`
- [Window shell](https://github.com/littleorgans/transport-matters/blob/main/desktop/src/window.ts): window management · Creates and manages the desktop window surface · `desktop/src/window.ts`

### shared

Cross-cutting schema and contract files

- [Shared specs](https://github.com/littleorgans/transport-matters/blob/main/shared/override_targets_v1.json): schema contracts · Cross-cutting JSON contract files shared across runtimes · `shared/override_targets_v1.json`

## Connections

- CLI entry → Backend app: starts · CLI bootstraps the backend service path
- CLI entry → Shared proxy: coordinates · CLI can launch detached/shared proxy instances
- CLI entry → Supervisor: spawns · CLI launch commands manage child processes and terminals
- CLI entry → Main process: desktop cmd · Desktop entrypoint is initiated through CLI-style orchestration
- Backend app → Control API: serves · FastAPI exposes the control plane routes
- Backend app → Session store: reads/writes · Backend consults the Postgres-backed session state
- Backend app → Disk storage: persists · Backend writes run-scoped artifacts and logs to disk
- Backend app → Run manager: orchestrates · Main runtime ties together launches, supervision, and sessions
- Run manager → Shared proxy: attaches · Run manager can bind to detached backend/proxy lifecycle
- Run manager → Supervisor: supervises · Run manager delegates process and PTY supervision
- Run manager → Exchange recorder: captures · Runs produce exchange artifacts through the recorder pipeline
- Exchange recorder → Request pipeline: routes through · Recorder feeds raw traffic into the curated request pipeline
- Request pipeline → Codex transport: codex path · Codex transport uses specialized derivation and repair logic
- Request pipeline → Claude adapter: claude path · Claude traffic is adapted through provider-specific boundary code
- Request pipeline → Disk storage: archives · Both raw and curated forms are preserved on disk
- Session package → Disk storage: loads/stores · Session package binds structured state to disk artifacts
- Session package → Session store: indexes · Session DAO populates the database-backed metadata layer
- Indexing → Session package: builds on · Indexing layer derives listings and replay views from session state
- Web app → Session canvas: hosts · Main app composes the canvas route experience
- Session canvas → Live stream: subscribes · Canvas consumes live session event streams
- Session canvas → Exchange inspector: renders · Canvas surfaces exchange inspection views
- Session canvas → Breakpoint editor: edits · Canvas exposes breakpoint and override editors
- Session canvas → Resource viewers: views · Canvas opens resource viewers for captured artifacts
- Live stream → UI stores: updates · Stream reducers feed normalized UI state
- Web app → UI stores: persists · App stores preferences, overlays, and theme state
- Main process → Preload bridge: bridges · Main process installs the preload API surface
- Main process → Window shell: opens · Main process manages the browser window shell
- Main process → Backend app: launches/connects · Desktop shell starts or attaches to the backend service
- Window shell → Web app: loads · Window hosts the React/Vite renderer
- Session canvas → Control API: calls · Frontend reads and controls backend through the control API
- Live stream → Control API: streams · Live updates arrive from backend streaming endpoints
- Control API → Session package: queries · Routes serve session and run data
- Control API → Disk storage: reads artifacts · Routes expose local file and resource content
- Shared specs → Session package: contracts · Shared schemas inform backend session and override shapes
- Shared specs → UI stores: types · Frontend state and editors consume shared schema data