# wrtide/wormstudio architecture

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

- Interactive diagram: https://gitdiagram.com/wrtide/wormstudio
- Repository: https://github.com/wrtide/wormstudio

## Overview

WormStudio is a local desktop application for tracking and measuring worms in video. The main workflow is to select a video, mark the analysis region and worm, process the video, then review annotated playback and export measurements. The graph also preserves documented batch and channel-count workflows, phenotype and quality analysis, and saved-run review. Several edges are supported by README workflow descriptions or SOURCE INDEX references; unsampled modules limit confidence about internal call order, so the graph avoids assuming a detailed pipeline.

Main entry points: [`src/analyze_phenotypes.py`](https://github.com/wrtide/wormstudio/blob/main/src/analyze_phenotypes.py) (Phenotype Analysis), [`src/manual_worm_annotation.py`](https://github.com/wrtide/wormstudio/blob/main/src/manual_worm_annotation.py) (Worm Annotation), [`web/review_result.js`](https://github.com/wrtide/wormstudio/blob/main/web/review_result.js) (Result Review), [`web/studio.js`](https://github.com/wrtide/wormstudio/blob/main/web/studio.js) (Studio Interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Desktop Workspace"]
  node_desktop["Desktop Shell<br/>[main.cjs]"]
  node_studio["Studio Interface<br/>[studio.js]"]
  node_workspace_sessions["Workspace Sessions"]
end

subgraph group_annotation["Annotation &amp; Inputs"]
  node_annotation_ui["Worm Annotation"]
  node_units["Measurement Units"]
  node_channel_ui["Channel Counts<br/>[channel_counts.py]"]
end

subgraph group_processing["Tracking &amp; Analysis"]
  node_pipeline_entry["Pipeline Entry<br/>[worm_pipeline.py]"]
  node_phenotype_analysis["Phenotype Analysis"]
  node_body_solver["Body Sequence Solver"]
  node_centerline_methods["Centerline Methods"]
  node_quality_schema["Quality Schema<br/>[quality_schema.py]"]
  node_quality_stage["Quality Stage<br/>[quality_stage.py]"]
  node_live_preview["Live Preview<br/>[live_preview.py]"]
  node_pipeline_progress["Pipeline Progress"]
end

subgraph group_results["Results &amp; Review"]
  node_result_metrics["Result Metrics<br/>[result_metrics.py]"]
  node_result_overlay["Result Overlay<br/>[result_overlay.py]"]
  node_result_review["Result Review<br/>[review_result.js]"]
  node_run_storage[("Run Storage<br/>[run_storage.py]")]
end

subgraph group_extensions["Additional Analysis"]
  node_phenotype_stats["Phenotype Statistics"]
  node_evaluation["Evaluation Dataset"]
  node_worm_tracker["Channel Tracker<br/>[mog2.py]"]
end

node_user(("Researcher"))

node_user -->|"launches"| node_desktop
node_desktop -->|"opens workspace"| node_studio
node_user -->|"selects video"| node_studio
node_studio -->|"starts annotation"| node_annotation_ui
node_annotation_ui -->|"configures units"| node_units
node_annotation_ui -->|"offers counting"| node_channel_ui
node_annotation_ui -->|"submits configuration"| node_pipeline_entry
node_pipeline_entry -->|"runs analysis"| node_phenotype_analysis
node_phenotype_analysis -->|"solves body sequence"| node_body_solver
node_phenotype_analysis -->|"selects method"| node_centerline_methods
node_phenotype_analysis -->|"uses quality rules"| node_quality_schema
node_phenotype_analysis -->|"runs quality stage"| node_quality_stage
node_phenotype_analysis -->|"writes previews"| node_live_preview
node_pipeline_entry -->|"reports progress"| node_pipeline_progress
node_phenotype_analysis -->|"uses metrics"| node_result_metrics
node_phenotype_analysis -->|"creates overlays"| node_result_overlay
node_phenotype_analysis -->|"computes statistics"| node_phenotype_stats
node_phenotype_analysis -.->|"stores run data"| node_run_storage
node_studio -->|"loads saved runs"| node_workspace_sessions
node_workspace_sessions -->|"preserves snapshots"| node_run_storage
node_user -->|"reviews results"| node_result_review
node_result_review -->|"shows measurements"| node_result_metrics
node_result_review -->|"plays annotations"| node_result_overlay
node_result_review -->|"opens history"| node_workspace_sessions
node_channel_ui -.->|"counts crossings"| node_worm_tracker
node_user -.->|"evaluates annotations"| node_evaluation

click node_desktop "https://github.com/wrtide/wormstudio/blob/main/tools/electron/main.cjs"
click node_studio "https://github.com/wrtide/wormstudio/blob/main/web/studio.js"
click node_workspace_sessions "https://github.com/wrtide/wormstudio/blob/main/src/workspace_sessions.py"
click node_annotation_ui "https://github.com/wrtide/wormstudio/blob/main/src/manual_worm_annotation.py"
click node_units "https://github.com/wrtide/wormstudio/blob/main/src/measurement_units.py"
click node_channel_ui "https://github.com/wrtide/wormstudio/blob/main/src/channel_counts.py"
click node_pipeline_entry "https://github.com/wrtide/wormstudio/blob/main/worm_pipeline.py"
click node_phenotype_analysis "https://github.com/wrtide/wormstudio/blob/main/src/analyze_phenotypes.py"
click node_body_solver "https://github.com/wrtide/wormstudio/blob/main/src/body_sequence_solver.py"
click node_centerline_methods "https://github.com/wrtide/wormstudio/blob/main/src/centerline_methods.py"
click node_quality_schema "https://github.com/wrtide/wormstudio/blob/main/src/quality_schema.py"
click node_quality_stage "https://github.com/wrtide/wormstudio/blob/main/src/quality_stage.py"
click node_live_preview "https://github.com/wrtide/wormstudio/blob/main/src/live_preview.py"
click node_pipeline_progress "https://github.com/wrtide/wormstudio/blob/main/src/pipeline_progress.py"
click node_result_metrics "https://github.com/wrtide/wormstudio/blob/main/src/result_metrics.py"
click node_result_overlay "https://github.com/wrtide/wormstudio/blob/main/src/result_overlay.py"
click node_result_review "https://github.com/wrtide/wormstudio/blob/main/web/review_result.js"
click node_run_storage "https://github.com/wrtide/wormstudio/blob/main/src/run_storage.py"
click node_phenotype_stats "https://github.com/wrtide/wormstudio/blob/main/src/phenotype_statistics.py"
click node_evaluation "https://github.com/wrtide/wormstudio/blob/main/src/evaluation_dataset.py"
click node_worm_tracker "https://github.com/wrtide/wormstudio/blob/main/src/wormtracker/engine/mog2.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_desktop,node_studio,node_workspace_sessions toneBlue
class node_annotation_ui,node_units,node_channel_ui toneAmber
class node_pipeline_entry,node_phenotype_analysis,node_body_solver,node_centerline_methods,node_quality_schema,node_quality_stage,node_live_preview,node_pipeline_progress toneMint
class node_result_metrics,node_result_overlay,node_result_review,node_run_storage toneRose
class node_phenotype_stats,node_evaluation,node_worm_tracker,node_user toneIndigo
```

## Components

### Desktop Workspace

- [Desktop Shell](https://github.com/wrtide/wormstudio/blob/main/tools/electron/main.cjs): `tools/electron/main.cjs`
- [Studio Interface](https://github.com/wrtide/wormstudio/blob/main/web/studio.js): `web/studio.js`
- [Workspace Sessions](https://github.com/wrtide/wormstudio/blob/main/src/workspace_sessions.py): `src/workspace_sessions.py`

### Annotation & Inputs

- [Worm Annotation](https://github.com/wrtide/wormstudio/blob/main/src/manual_worm_annotation.py): `src/manual_worm_annotation.py`
- [Measurement Units](https://github.com/wrtide/wormstudio/blob/main/src/measurement_units.py): `src/measurement_units.py`
- [Channel Counts](https://github.com/wrtide/wormstudio/blob/main/src/channel_counts.py): `src/channel_counts.py`

### Tracking & Analysis

- [Pipeline Entry](https://github.com/wrtide/wormstudio/blob/main/worm_pipeline.py): `worm_pipeline.py`
- [Phenotype Analysis](https://github.com/wrtide/wormstudio/blob/main/src/analyze_phenotypes.py): `src/analyze_phenotypes.py`
- [Body Sequence Solver](https://github.com/wrtide/wormstudio/blob/main/src/body_sequence_solver.py): `src/body_sequence_solver.py`
- [Centerline Methods](https://github.com/wrtide/wormstudio/blob/main/src/centerline_methods.py): `src/centerline_methods.py`
- [Quality Schema](https://github.com/wrtide/wormstudio/blob/main/src/quality_schema.py): `src/quality_schema.py`
- [Quality Stage](https://github.com/wrtide/wormstudio/blob/main/src/quality_stage.py): `src/quality_stage.py`
- [Live Preview](https://github.com/wrtide/wormstudio/blob/main/src/live_preview.py): `src/live_preview.py`
- [Pipeline Progress](https://github.com/wrtide/wormstudio/blob/main/src/pipeline_progress.py): `src/pipeline_progress.py`

### Results & Review

- [Result Metrics](https://github.com/wrtide/wormstudio/blob/main/src/result_metrics.py): `src/result_metrics.py`
- [Result Overlay](https://github.com/wrtide/wormstudio/blob/main/src/result_overlay.py): `src/result_overlay.py`
- [Result Review](https://github.com/wrtide/wormstudio/blob/main/web/review_result.js): `web/review_result.js`
- [Run Storage](https://github.com/wrtide/wormstudio/blob/main/src/run_storage.py): `src/run_storage.py`

### Additional Analysis

- [Phenotype Statistics](https://github.com/wrtide/wormstudio/blob/main/src/phenotype_statistics.py): `src/phenotype_statistics.py`
- [Evaluation Dataset](https://github.com/wrtide/wormstudio/blob/main/src/evaluation_dataset.py): `src/evaluation_dataset.py`
- [Channel Tracker](https://github.com/wrtide/wormstudio/blob/main/src/wormtracker/engine/mog2.py): `src/wormtracker/engine/mog2.py`

### Other components

- **Researcher**

## Connections

- Researcher → Desktop Shell: launches (evidence: `README.md`)
- Desktop Shell → Studio Interface: opens workspace (evidence: `tools/electron/main.cjs`)
- Researcher → Studio Interface: selects video (evidence: `README.md`)
- Studio Interface → Worm Annotation: starts annotation (evidence: `README.md`)
- Worm Annotation → Measurement Units: configures units (evidence: `src/manual_worm_annotation.py`)
- Worm Annotation → Channel Counts: offers counting (evidence: `src/manual_worm_annotation.py`)
- Worm Annotation → Pipeline Entry: submits configuration (evidence: `README.md`)
- Pipeline Entry → Phenotype Analysis: runs analysis (evidence: `worm_pipeline.py`)
- Phenotype Analysis → Body Sequence Solver: solves body sequence (evidence: `src/analyze_phenotypes.py`)
- Phenotype Analysis → Centerline Methods: selects method (evidence: `src/analyze_phenotypes.py`)
- Phenotype Analysis → Quality Schema: uses quality rules (evidence: `src/analyze_phenotypes.py`)
- Phenotype Analysis → Quality Stage: runs quality stage (evidence: `src/analyze_phenotypes.py`)
- Phenotype Analysis → Live Preview: writes previews (evidence: `src/analyze_phenotypes.py`)
- Pipeline Entry → Pipeline Progress: reports progress (evidence: `src/pipeline_progress.py`)
- Phenotype Analysis → Result Metrics: uses metrics (evidence: `src/analyze_phenotypes.py`)
- Phenotype Analysis → Result Overlay: creates overlays (evidence: `src/analyze_phenotypes.py`)
- Phenotype Analysis → Phenotype Statistics: computes statistics (evidence: `src/analyze_phenotypes.py`)
- Phenotype Analysis → Run Storage: stores run data (evidence: `src/analyze_phenotypes.py`)
- Studio Interface → Workspace Sessions: loads saved runs
- Workspace Sessions → Run Storage: preserves snapshots (evidence: `src/workspace_sessions.py`)
- Researcher → Result Review: reviews results (evidence: `README.md`)
- Result Review → Result Metrics: shows measurements (evidence: `README.md`)
- Result Review → Result Overlay: plays annotations (evidence: `README.md`)
- Result Review → Workspace Sessions: opens history (evidence: `src/workspace_sessions.py`)
- Channel Counts → Channel Tracker: counts crossings
- Researcher → Evaluation Dataset: evaluates annotations
