# gx-capture/capture-workbench architecture

> Architecture diagram of the GitHub repository gx-capture/capture-workbench, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gx-capture/capture-workbench
- Repository: https://github.com/gx-capture/capture-workbench

## Overview

Capture Workbench is a local-first platform that turns PDF, image, and audio inputs into validated structured documents. In the desktop workflow, a user imports a source through the Angular UI; the native host manages the local runtime and credentials, the runtime ingests and extracts content, then structures and validates the result before the host persists it for review or export. The README also documents embeddable UI and TypeScript, Python, and Java SDK integrations. Runtime internals and several README-described subsystems are unsampled, so their links below are limited to documented relationships.

Main entry points: [`packages/capture-runtime/src/capture_runtime/routes/runtime.py`](https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/routes/runtime.py) (Runtime API), [`packages/capture-runtime/src/capture_runtime/services/streaming_capture_service.py`](https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/services/streaming_capture_service.py) (Capture service), [`apps/capture-workbench/src/app/app.ts`](https://github.com/gx-capture/capture-workbench/blob/main/apps/capture-workbench/src/app/app.ts) (Desktop UI), [`apps/capture-workbench/src/app/services/desktop-workspace-capture.service.ts`](https://github.com/gx-capture/capture-workbench/blob/main/apps/capture-workbench/src/app/services/desktop-workspace-capture.service.ts) (Capture workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_desktop_ui["Desktop UI<br/>[app.ts]"]
  node_workspace_capture["Capture workflow"]
  node_embedded_ui["Embeddable UI<br/>[capture-angular.ts]"]
end

subgraph group_desktop["Desktop host"]
  node_desktop_workspace["Workspace state"]
  node_native_commands["Native commands<br/>[commands.rs]"]
  node_desktop_runtime_client["Desktop runtime client<br/>[runtime_client.rs]"]
  node_local_library[("Local library<br/>[library.rs]")]
  node_sidecar["Sidecar lifecycle<br/>[launcher.rs]"]
end

subgraph group_runtime["Capture runtime"]
  node_runtime_api["Runtime API<br/>[runtime.py]"]
  node_streaming_api["Streaming API<br/>[streaming.py]"]
  node_capture_service["Capture service"]
  node_extraction["Extraction engines<br/>[engine_adapters.py]"]
  node_engine_setup["Engine setup"]
  node_structuring["Structuring<br/>[structuring.py]"]
  node_structuring_sessions["Structuring sessions"]
  node_contract_discovery["Contract discovery<br/>[contract_set.py]"]
  node_runtime_contracts["Runtime contracts<br/>[__init__.py]"]
end

subgraph group_integrations["Host integrations"]
  node_typescript_sdk["TypeScript SDK<br/>[client.ts]"]
  node_python_sdk["Python SDK<br/>[client.py]"]
  node_java_sdk["Java SDK"]
end

node_user(("User"))
node_host_provider(("Host provider"))
node_ollama["Ollama process"]

node_user -->|"imports sources"| node_desktop_ui
node_desktop_ui -->|"starts capture"| node_workspace_capture
node_workspace_capture -->|"requests runtime"| node_desktop_runtime_client
node_workspace_capture -->|"persists results"| node_local_library
node_desktop_ui -->|"initializes state"| node_desktop_workspace
node_native_commands -.->|"manages lifecycle"| node_sidecar
node_desktop_runtime_client -->|"calls over loopback"| node_runtime_api
node_runtime_api -.->|"dispatches capture"| node_capture_service
node_streaming_api -.->|"dispatches streaming"| node_capture_service
node_capture_service -->|"extracts content"| node_extraction
node_engine_setup -->|"activates engines"| node_extraction
node_capture_service -->|"structures content"| node_structuring
node_capture_service -.->|"supports sessions"| node_structuring_sessions
node_structuring -->|"validates result"| node_runtime_contracts
node_runtime_api -->|"serves discovery"| node_contract_discovery
node_desktop_runtime_client -->|"copies host data"| node_local_library
node_embedded_ui -->|"accepts provider"| node_host_provider
node_typescript_sdk -->|"calls runtime"| node_runtime_api
node_python_sdk -->|"calls runtime"| node_runtime_api
node_java_sdk -->|"calls runtime"| node_runtime_api
node_host_provider -.->|"may structure"| node_runtime_api
node_structuring -.->|"may use"| node_ollama

click node_desktop_ui "https://github.com/gx-capture/capture-workbench/blob/main/apps/capture-workbench/src/app/app.ts"
click node_workspace_capture "https://github.com/gx-capture/capture-workbench/blob/main/apps/capture-workbench/src/app/services/desktop-workspace-capture.service.ts"
click node_embedded_ui "https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-workbench-ui/src/lib/capture-angular/components/capture-angular/capture-angular.ts"
click node_desktop_workspace "https://github.com/gx-capture/capture-workbench/blob/main/apps/capture-workbench/src/app/services/desktop-workspace.store.ts"
click node_native_commands "https://github.com/gx-capture/capture-workbench/blob/main/apps/capture-workbench-desktop/src-tauri/src/commands.rs"
click node_desktop_runtime_client "https://github.com/gx-capture/capture-workbench/blob/main/apps/capture-workbench-desktop/src-tauri/src/runtime_client.rs"
click node_local_library "https://github.com/gx-capture/capture-workbench/blob/main/apps/capture-workbench-desktop/src-tauri/src/library.rs"
click node_sidecar "https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-sidecar-launcher/src/launcher.rs"
click node_runtime_api "https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/routes/runtime.py"
click node_streaming_api "https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/routes/streaming.py"
click node_capture_service "https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/services/streaming_capture_service.py"
click node_extraction "https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/engine_adapters.py"
click node_engine_setup "https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/engine_installation.py"
click node_structuring "https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/structuring/structuring.py"
click node_structuring_sessions "https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/services/structuring_session_service.py"
click node_contract_discovery "https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/contract_set.py"
click node_runtime_contracts "https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/contracts/__init__.py"
click node_typescript_sdk "https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime-client/src/client.ts"
click node_python_sdk "https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime-client-python/src/capture_runtime_client/client.py"
click node_java_sdk "https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime-client-java/src/main/java/com/gx/capture/runtime/client/CaptureRuntimeClient.java"

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_desktop_ui,node_workspace_capture,node_embedded_ui,node_user toneBlue
class node_desktop_workspace,node_native_commands,node_desktop_runtime_client,node_local_library,node_sidecar toneAmber
class node_runtime_api,node_streaming_api,node_capture_service,node_extraction,node_engine_setup,node_structuring,node_structuring_sessions,node_contract_discovery,node_runtime_contracts toneMint
class node_typescript_sdk,node_python_sdk,node_java_sdk toneRose
class node_host_provider,node_ollama toneIndigo
```

## Components

### User experience

- [Desktop UI](https://github.com/gx-capture/capture-workbench/blob/main/apps/capture-workbench/src/app/app.ts): `apps/capture-workbench/src/app/app.ts`
- [Capture workflow](https://github.com/gx-capture/capture-workbench/blob/main/apps/capture-workbench/src/app/services/desktop-workspace-capture.service.ts): `apps/capture-workbench/src/app/services/desktop-workspace-capture.service.ts`
- [Embeddable UI](https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-workbench-ui/src/lib/capture-angular/components/capture-angular/capture-angular.ts): `packages/capture-workbench-ui/src/lib/capture-angular/components/capture-angular/capture-angular.ts`

### Desktop host

- [Workspace state](https://github.com/gx-capture/capture-workbench/blob/main/apps/capture-workbench/src/app/services/desktop-workspace.store.ts): `apps/capture-workbench/src/app/services/desktop-workspace.store.ts`
- [Native commands](https://github.com/gx-capture/capture-workbench/blob/main/apps/capture-workbench-desktop/src-tauri/src/commands.rs): `apps/capture-workbench-desktop/src-tauri/src/commands.rs`
- [Desktop runtime client](https://github.com/gx-capture/capture-workbench/blob/main/apps/capture-workbench-desktop/src-tauri/src/runtime_client.rs): `apps/capture-workbench-desktop/src-tauri/src/runtime_client.rs`
- [Local library](https://github.com/gx-capture/capture-workbench/blob/main/apps/capture-workbench-desktop/src-tauri/src/library.rs): `apps/capture-workbench-desktop/src-tauri/src/library.rs`
- [Sidecar lifecycle](https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-sidecar-launcher/src/launcher.rs): `packages/capture-sidecar-launcher/src/launcher.rs`

### Capture runtime

- [Runtime API](https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/routes/runtime.py): `packages/capture-runtime/src/capture_runtime/routes/runtime.py`
- [Streaming API](https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/routes/streaming.py): `packages/capture-runtime/src/capture_runtime/routes/streaming.py`
- [Capture service](https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/services/streaming_capture_service.py): `packages/capture-runtime/src/capture_runtime/services/streaming_capture_service.py`
- [Extraction engines](https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/engine_adapters.py): `packages/capture-runtime/src/capture_runtime/engine_adapters.py`
- [Engine setup](https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/engine_installation.py): `packages/capture-runtime/src/capture_runtime/engine_installation.py`
- [Structuring](https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/structuring/structuring.py): `packages/capture-runtime/src/capture_runtime/structuring/structuring.py`
- [Structuring sessions](https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/services/structuring_session_service.py): `packages/capture-runtime/src/capture_runtime/services/structuring_session_service.py`
- [Contract discovery](https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/contract_set.py): `packages/capture-runtime/src/capture_runtime/contract_set.py`
- [Runtime contracts](https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime/src/capture_runtime/contracts/__init__.py): `packages/capture-runtime/src/capture_runtime/contracts/__init__.py`

### Host integrations

- [TypeScript SDK](https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime-client/src/client.ts): `packages/capture-runtime-client/src/client.ts`
- [Python SDK](https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime-client-python/src/capture_runtime_client/client.py): `packages/capture-runtime-client-python/src/capture_runtime_client/client.py`
- [Java SDK](https://github.com/gx-capture/capture-workbench/blob/main/packages/capture-runtime-client-java/src/main/java/com/gx/capture/runtime/client/CaptureRuntimeClient.java): `packages/capture-runtime-client-java/src/main/java/com/gx/capture/runtime/client/CaptureRuntimeClient.java`

### Other components

- **User**
- **Host provider**
- **Ollama process**

## Connections

- User → Desktop UI: imports sources (evidence: `README.md`)
- Desktop UI → Capture workflow: starts capture (evidence: `apps/capture-workbench/src/app/app.ts`)
- Capture workflow → Desktop runtime client: requests runtime (evidence: `README.md`)
- Capture workflow → Local library: persists results (evidence: `README.md`)
- Desktop UI → Workspace state: initializes state (evidence: `apps/capture-workbench/src/app/app.ts`)
- Native commands → Sidecar lifecycle: manages lifecycle
- Desktop runtime client → Runtime API: calls over loopback (evidence: `README.md`)
- Runtime API → Capture service: dispatches capture
- Streaming API → Capture service: dispatches streaming
- Capture service → Extraction engines: extracts content (evidence: `README.md`)
- Engine setup → Extraction engines: activates engines (evidence: `packages/capture-runtime/src/capture_runtime/engine_installation.py`)
- Capture service → Structuring: structures content (evidence: `README.md`)
- Capture service → Structuring sessions: supports sessions
- Structuring → Runtime contracts: validates result (evidence: `README.md`)
- Runtime API → Contract discovery: serves discovery (evidence: `README.md`)
- Desktop runtime client → Local library: copies host data (evidence: `README.md`)
- Embeddable UI → Host provider: accepts provider (evidence: `README.md`)
- TypeScript SDK → Runtime API: calls runtime (evidence: `README.md`)
- Python SDK → Runtime API: calls runtime (evidence: `README.md`)
- Java SDK → Runtime API: calls runtime (evidence: `README.md`)
- Host provider → Runtime API: may structure (evidence: `README.md`)
- Structuring → Ollama process: may use (evidence: `README.md`)
