# vivarium-collective/vivarium-workbench architecture

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

- Interactive diagram: https://gitdiagram.com/vivarium-collective/vivarium-workbench
- Repository: https://github.com/vivarium-collective/vivarium-workbench

## Overview

Vivarium Workbench is a web workbench for Process-Bigraph workspaces: users author and browse workspace assets, run studies, inspect results, and render visualizations. The main compute path resolves a study’s declared producer inputs, reuses matching artifacts or executes a run, then exposes study runs and reports for inspection. It also supports investigations, composite/state-tree exploration, Git-backed workstreams, remote viva-api compute, and read-only published snapshots. The graph reflects README capabilities; unsampled route wiring is kept conservative.

Main entry points: [`vivarium_workbench/api/app.py`](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/api/app.py) (HTTP API), [`vivarium_workbench/lib/artifacts/pipeline.py`](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/artifacts/pipeline.py) (Pull-or-compute resolver), [`vivarium_workbench/loom/src/App.tsx`](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/loom/src/App.tsx) (State-tree explorer), [`vivarium_workbench/loom/src/api.ts`](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/loom/src/api.ts) (Explorer API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Workbench interface"]
  node_http["HTTP API<br/>[app.py]"]
  node_loom["State-tree explorer<br/>[App.tsx]"]
  node_loomapi["Explorer API client<br/>[api.ts]"]
end

subgraph group_workspace["Workspace authoring"]
  node_workspacefiles["Workspace assets"]
  node_registry["Process registry<br/>[registry.py]"]
  node_composites["Composite discovery"]
  node_git["Git workstream<br/>[work_mutations.py]"]
end

subgraph group_compute["Study compute"]
  node_study["Study definitions<br/>[study_spec.py]"]
  node_pipeline["Pull-or-compute resolver<br/>[pipeline.py]"]
  node_artifactstore[("Artifact store<br/>[store.py]")]
  node_runner["Run executor<br/>[run_runner.py]"]
  node_worker["Environment worker<br/>[env_worker.py]"]
end

subgraph group_research["Research outputs"]
  node_investigations["Investigation workflows<br/>[investigations.py]"]
  node_runs[("Run records<br/>[run_store.py]")]
  node_reports["Study reports<br/>[report.py]"]
  node_visualizations["Visualization rendering<br/>[viz_render.py]"]
end

subgraph group_deployment["Deployment modes"]
  node_remote["Remote compute client<br/>[sms_api_client.py]"]
  node_publisher["Published snapshot<br/>[publish.py]"]
end

node_user(("Workbench user"))
node_viva{{"viva-api service"}}

node_user -->|"uses"| node_http
node_http -->|"reads and updates"| node_workspacefiles
node_http -->|"serves registry"| node_registry
node_http -->|"requests composites"| node_composites
node_http -->|"records workstream actions"| node_git
node_http -->|"serves investigations"| node_investigations
node_http -->|"serves study data"| node_study
node_http -->|"starts study runs"| node_pipeline
node_pipeline -->|"resolves producer inputs"| node_study
node_pipeline -->|"checks and stores artifacts"| node_artifactstore
node_pipeline -->|"executes cache misses"| node_runner
node_runner -->|"dispatches workspace work"| node_worker
node_pipeline -->|"writes run request data"| node_runs
node_http -->|"serves run status"| node_runs
node_http -->|"serves reports"| node_reports
node_http -->|"serves visualization features"| node_visualizations
node_user -->|"explores composites"| node_loom
node_loom -->|"requests composite state"| node_loomapi
node_loomapi -->|"calls explorer endpoints"| node_http
node_http -.->|"routes remote runs"| node_remote
node_remote -.->|"builds and submits runs"| node_viva
node_user -->|"publishes workspace"| node_publisher
node_publisher -->|"packages committed snapshot"| node_workspacefiles

click node_http "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/api/app.py"
click node_loom "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/loom/src/App.tsx"
click node_loomapi "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/loom/src/api.ts"
click node_registry "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/registry.py"
click node_composites "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/composites_query.py"
click node_git "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/work_mutations.py"
click node_investigations "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/investigations.py"
click node_study "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/study_spec.py"
click node_pipeline "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/artifacts/pipeline.py"
click node_artifactstore "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/artifacts/store.py"
click node_runner "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/run_runner.py"
click node_worker "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/env_worker.py"
click node_runs "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/run_store.py"
click node_reports "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/report.py"
click node_visualizations "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/viz_render.py"
click node_remote "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/sms_api_client.py"
click node_publisher "https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/publish.py"

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_http,node_loom,node_loomapi,node_user toneBlue
class node_workspacefiles,node_registry,node_composites,node_git toneAmber
class node_study,node_pipeline,node_artifactstore,node_runner,node_worker,node_viva toneMint
class node_investigations,node_runs,node_reports,node_visualizations toneRose
class node_remote,node_publisher toneIndigo
```

## Components

### Workbench interface

- [HTTP API](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/api/app.py): `vivarium_workbench/api/app.py`
- [State-tree explorer](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/loom/src/App.tsx): `vivarium_workbench/loom/src/App.tsx`
- [Explorer API client](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/loom/src/api.ts): `vivarium_workbench/loom/src/api.ts`

### Workspace authoring

- **Workspace assets**
- [Process registry](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/registry.py): `vivarium_workbench/lib/registry.py`
- [Composite discovery](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/composites_query.py): `vivarium_workbench/lib/composites_query.py`
- [Git workstream](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/work_mutations.py): `vivarium_workbench/lib/work_mutations.py`

### Study compute

- [Study definitions](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/study_spec.py): `vivarium_workbench/lib/study_spec.py`
- [Pull-or-compute resolver](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/artifacts/pipeline.py): `vivarium_workbench/lib/artifacts/pipeline.py`
- [Artifact store](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/artifacts/store.py): `vivarium_workbench/lib/artifacts/store.py`
- [Run executor](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/run_runner.py): `vivarium_workbench/lib/run_runner.py`
- [Environment worker](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/env_worker.py): `vivarium_workbench/env_worker.py`

### Research outputs

- [Investigation workflows](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/investigations.py): `vivarium_workbench/lib/investigations.py`
- [Run records](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/run_store.py): `vivarium_workbench/lib/run_store.py`
- [Study reports](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/report.py): `vivarium_workbench/lib/report.py`
- [Visualization rendering](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/viz_render.py): `vivarium_workbench/lib/viz_render.py`

### Deployment modes

- [Remote compute client](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/lib/sms_api_client.py): `vivarium_workbench/lib/sms_api_client.py`
- [Published snapshot](https://github.com/vivarium-collective/vivarium-workbench/blob/main/vivarium_workbench/publish.py): `vivarium_workbench/publish.py`

### Other components

- **Workbench user**
- **viva-api service**

## Connections

- Workbench user → HTTP API: uses
- HTTP API → Workspace assets: reads and updates
- HTTP API → Process registry: serves registry
- HTTP API → Composite discovery: requests composites
- HTTP API → Git workstream: records workstream actions
- HTTP API → Investigation workflows: serves investigations
- HTTP API → Study definitions: serves study data
- HTTP API → Pull-or-compute resolver: starts study runs
- Pull-or-compute resolver → Study definitions: resolves producer inputs
- Pull-or-compute resolver → Artifact store: checks and stores artifacts
- Pull-or-compute resolver → Run executor: executes cache misses
- Run executor → Environment worker: dispatches workspace work
- Pull-or-compute resolver → Run records: writes run request data
- HTTP API → Run records: serves run status
- HTTP API → Study reports: serves reports
- HTTP API → Visualization rendering: serves visualization features
- Workbench user → State-tree explorer: explores composites
- State-tree explorer → Explorer API client: requests composite state
- Explorer API client → HTTP API: calls explorer endpoints
- HTTP API → Remote compute client: routes remote runs
- Remote compute client → viva-api service: builds and submits runs
- Workbench user → Published snapshot: publishes workspace
- Published snapshot → Workspace assets: packages committed snapshot