# ros-claw/simscene architecture

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

- Interactive diagram: https://gitdiagram.com/ros-claw/simscene
- Repository: https://github.com/ros-claw/simscene

## Overview

SimScene is an agent-facing Isaac Sim scene-building and simulation product: users discover and inspect online assets, acquire and prepare selected models, compose editable USD scenes, run physical cases, assess observations, and deliver traceable films. The graph preserves the documented catalog, preparation, optional generation, recipe, robotics, simulation, verification, and video capabilities. Source excerpts are selective; edges use README workflow statements or indexed references, so unsampled implementation details are not expanded into speculative call chains.

Main entry points: [`src/simscene/worker/isaac_run.py`](https://github.com/ros-claw/simscene/blob/main/src/simscene/worker/isaac_run.py) (Isaac execution), [`src/simscene/catalog/search.py`](https://github.com/ros-claw/simscene/blob/main/src/simscene/catalog/search.py) (Asset catalog), [`src/simscene/preparation/worker.py`](https://github.com/ros-claw/simscene/blob/main/src/simscene/preparation/worker.py) (Preparation worker), [`src/simscene/acquisition/dispatch.py`](https://github.com/ros-claw/simscene/blob/main/src/simscene/acquisition/dispatch.py) (Asset acquisition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_asset_flow["Asset discovery and preparation"]
  node_catalog["Asset catalog<br/>[search.py]"]
  node_catalog_service["Catalog facade<br/>[service.py]"]
  node_catalog_models["Catalog metadata<br/>[models.py]"]
  node_asset_providers["Catalog providers"]
  node_acquisition["Asset acquisition<br/>[dispatch.py]"]
  node_asset_cache[("Asset cache<br/>[cache.py]")]
  node_prep_jobs["Preparation jobs<br/>[jobs.py]"]
  node_prep_worker["Preparation worker<br/>[worker.py]"]
  node_generation["Sand3D generation<br/>[backend_worker.py]"]
end

subgraph group_scene_build["Scene authoring"]
  node_recipes["Scene recipes"]
  node_scene[("Editable scene<br/>[scene.py]")]
  node_robotics["Robotics profiles<br/>[profiles.py]"]
  node_physics_binding["Asset physics binding<br/>[physics_binding.py]"]
end

subgraph group_simulation["Simulation runtime"]
  node_isaac_run["Isaac execution<br/>[isaac_run.py]"]
  node_worker_mechanism["Mechanism runtime<br/>[mechanism.py]"]
  node_case_runner["Case execution<br/>[case_runner.py]"]
end

subgraph group_assurance["Verification and integrity"]
  node_mechanism_verify["Mechanism checks<br/>[mechanism.py]"]
  node_mechanism_v2["D6 mechanism checks<br/>[mechanism_v2.py]"]
  node_passive_network["Passive network checks<br/>[passive_network.py]"]
  node_passive_network_v3["D6 network checks"]
  node_structural_loads["Structural load checks"]
  node_d6_admission["D6 admission<br/>[d6_admission.py]"]
  node_run_integrity["Run input integrity<br/>[run_integrity.py]"]
  node_snapshot_integrity["Asset snapshot integrity"]
  node_evidence_integrity["Output hash checks"]
end

subgraph group_delivery["Agent access and delivery"]
  node_mcp["MCP tools<br/>[mcp_server.py]"]
  node_film["Capture and video<br/>[capture.py]"]
end

node_agent(("Agent / user"))
node_external_sources["Online asset sources"]
node_isaac["Isaac Sim host"]

node_agent -->|"requests tools"| node_mcp
node_mcp -->|"exposes search"| node_catalog_service
node_catalog_service -->|"searches assets"| node_catalog
node_catalog -->|"returns metadata"| node_catalog_models
node_catalog -->|"queries providers"| node_asset_providers
node_asset_providers -->|"retrieves listings"| node_external_sources
node_agent -->|"selects assets"| node_acquisition
node_acquisition -->|"stores downloads"| node_asset_cache
node_agent -->|"prepares selection"| node_prep_jobs
node_prep_jobs -->|"runs job"| node_prep_worker
node_prep_worker -->|"acquires selection"| node_acquisition
node_prep_worker -->|"uses bindings"| node_physics_binding
node_agent -.->|"requests generation"| node_generation
node_agent -->|"reuses recipes"| node_recipes
node_agent -->|"composes scene"| node_scene
node_scene -->|"validates assets"| node_physics_binding
node_agent -.->|"configures robots"| node_robotics
node_agent -->|"runs simulation"| node_isaac_run
node_isaac_run -->|"executes physics"| node_isaac
node_isaac_run -->|"runs case"| node_case_runner
node_isaac_run -->|"observes mechanisms"| node_worker_mechanism
node_agent -->|"checks observations"| node_mechanism_verify
node_agent -->|"checks handoffs"| node_passive_network
node_agent -->|"checks loads"| node_structural_loads
node_mechanism_v2 -->|"checks admission"| node_d6_admission
node_passive_network_v3 -->|"checks admission"| node_d6_admission
node_agent -->|"checks run locks"| node_run_integrity
node_run_integrity -->|"checks snapshots"| node_snapshot_integrity
node_agent -->|"seals outputs"| node_evidence_integrity
node_agent -->|"records simulation"| node_film
node_film -->|"captures frames"| node_isaac

click node_mcp "https://github.com/ros-claw/simscene/blob/main/src/simscene/mcp_server.py"
click node_catalog "https://github.com/ros-claw/simscene/blob/main/src/simscene/catalog/search.py"
click node_catalog_service "https://github.com/ros-claw/simscene/blob/main/src/simscene/catalog/service.py"
click node_catalog_models "https://github.com/ros-claw/simscene/blob/main/src/simscene/catalog/models.py"
click node_asset_providers "https://github.com/ros-claw/simscene/tree/main/src/simscene/catalog/providers"
click node_acquisition "https://github.com/ros-claw/simscene/blob/main/src/simscene/acquisition/dispatch.py"
click node_asset_cache "https://github.com/ros-claw/simscene/blob/main/src/simscene/cache.py"
click node_prep_jobs "https://github.com/ros-claw/simscene/blob/main/src/simscene/preparation/jobs.py"
click node_prep_worker "https://github.com/ros-claw/simscene/blob/main/src/simscene/preparation/worker.py"
click node_generation "https://github.com/ros-claw/simscene/blob/main/src/simscene/generation/backend_worker.py"
click node_recipes "https://github.com/ros-claw/simscene/tree/main/src/simscene/recipes"
click node_scene "https://github.com/ros-claw/simscene/blob/main/src/simscene/scene.py"
click node_robotics "https://github.com/ros-claw/simscene/blob/main/src/simscene/robotics/profiles.py"
click node_physics_binding "https://github.com/ros-claw/simscene/blob/main/src/simscene/physics_binding.py"
click node_isaac_run "https://github.com/ros-claw/simscene/blob/main/src/simscene/worker/isaac_run.py"
click node_worker_mechanism "https://github.com/ros-claw/simscene/blob/main/src/simscene/worker/mechanism.py"
click node_case_runner "https://github.com/ros-claw/simscene/blob/main/src/simscene/verification/case_runner.py"
click node_mechanism_verify "https://github.com/ros-claw/simscene/blob/main/src/simscene/verification/mechanism.py"
click node_mechanism_v2 "https://github.com/ros-claw/simscene/blob/main/src/simscene/verification/mechanism_v2.py"
click node_passive_network "https://github.com/ros-claw/simscene/blob/main/src/simscene/verification/passive_network.py"
click node_passive_network_v3 "https://github.com/ros-claw/simscene/blob/main/src/simscene/verification/passive_network_v3.py"
click node_structural_loads "https://github.com/ros-claw/simscene/blob/main/src/simscene/verification/structural_loads.py"
click node_d6_admission "https://github.com/ros-claw/simscene/blob/main/src/simscene/verification/d6_admission.py"
click node_run_integrity "https://github.com/ros-claw/simscene/blob/main/src/simscene/run_integrity.py"
click node_snapshot_integrity "https://github.com/ros-claw/simscene/blob/main/src/simscene/snapshot_integrity.py"
click node_evidence_integrity "https://github.com/ros-claw/simscene/blob/main/src/simscene/evidence_integrity.py"
click node_film "https://github.com/ros-claw/simscene/blob/main/src/simscene/capture.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_catalog,node_catalog_service,node_catalog_models,node_asset_providers,node_acquisition,node_asset_cache,node_prep_jobs,node_prep_worker,node_generation,node_agent toneBlue
class node_recipes,node_scene,node_robotics,node_physics_binding toneAmber
class node_isaac_run,node_worker_mechanism,node_case_runner toneMint
class node_mechanism_verify,node_mechanism_v2,node_passive_network,node_passive_network_v3,node_structural_loads,node_d6_admission,node_run_integrity,node_snapshot_integrity,node_evidence_integrity toneRose
class node_mcp,node_film,node_external_sources,node_isaac toneIndigo
```

## Components

### Asset discovery and preparation

- [Asset catalog](https://github.com/ros-claw/simscene/blob/main/src/simscene/catalog/search.py): `src/simscene/catalog/search.py`
- [Catalog facade](https://github.com/ros-claw/simscene/blob/main/src/simscene/catalog/service.py): `src/simscene/catalog/service.py`
- [Catalog metadata](https://github.com/ros-claw/simscene/blob/main/src/simscene/catalog/models.py): `src/simscene/catalog/models.py`
- [Catalog providers](https://github.com/ros-claw/simscene/tree/main/src/simscene/catalog/providers): `src/simscene/catalog/providers`
- [Asset acquisition](https://github.com/ros-claw/simscene/blob/main/src/simscene/acquisition/dispatch.py): `src/simscene/acquisition/dispatch.py`
- [Asset cache](https://github.com/ros-claw/simscene/blob/main/src/simscene/cache.py): `src/simscene/cache.py`
- [Preparation jobs](https://github.com/ros-claw/simscene/blob/main/src/simscene/preparation/jobs.py): `src/simscene/preparation/jobs.py`
- [Preparation worker](https://github.com/ros-claw/simscene/blob/main/src/simscene/preparation/worker.py): `src/simscene/preparation/worker.py`
- [Sand3D generation](https://github.com/ros-claw/simscene/blob/main/src/simscene/generation/backend_worker.py): `src/simscene/generation/backend_worker.py`

### Scene authoring

- [Scene recipes](https://github.com/ros-claw/simscene/tree/main/src/simscene/recipes): `src/simscene/recipes`
- [Editable scene](https://github.com/ros-claw/simscene/blob/main/src/simscene/scene.py): `src/simscene/scene.py`
- [Robotics profiles](https://github.com/ros-claw/simscene/blob/main/src/simscene/robotics/profiles.py): `src/simscene/robotics/profiles.py`
- [Asset physics binding](https://github.com/ros-claw/simscene/blob/main/src/simscene/physics_binding.py): `src/simscene/physics_binding.py`

### Simulation runtime

- [Isaac execution](https://github.com/ros-claw/simscene/blob/main/src/simscene/worker/isaac_run.py): `src/simscene/worker/isaac_run.py`
- [Mechanism runtime](https://github.com/ros-claw/simscene/blob/main/src/simscene/worker/mechanism.py): `src/simscene/worker/mechanism.py`
- [Case execution](https://github.com/ros-claw/simscene/blob/main/src/simscene/verification/case_runner.py): `src/simscene/verification/case_runner.py`

### Verification and integrity

- [Mechanism checks](https://github.com/ros-claw/simscene/blob/main/src/simscene/verification/mechanism.py): `src/simscene/verification/mechanism.py`
- [D6 mechanism checks](https://github.com/ros-claw/simscene/blob/main/src/simscene/verification/mechanism_v2.py): `src/simscene/verification/mechanism_v2.py`
- [Passive network checks](https://github.com/ros-claw/simscene/blob/main/src/simscene/verification/passive_network.py): `src/simscene/verification/passive_network.py`
- [D6 network checks](https://github.com/ros-claw/simscene/blob/main/src/simscene/verification/passive_network_v3.py): `src/simscene/verification/passive_network_v3.py`
- [Structural load checks](https://github.com/ros-claw/simscene/blob/main/src/simscene/verification/structural_loads.py): `src/simscene/verification/structural_loads.py`
- [D6 admission](https://github.com/ros-claw/simscene/blob/main/src/simscene/verification/d6_admission.py): `src/simscene/verification/d6_admission.py`
- [Run input integrity](https://github.com/ros-claw/simscene/blob/main/src/simscene/run_integrity.py): `src/simscene/run_integrity.py`
- [Asset snapshot integrity](https://github.com/ros-claw/simscene/blob/main/src/simscene/snapshot_integrity.py): `src/simscene/snapshot_integrity.py`
- [Output hash checks](https://github.com/ros-claw/simscene/blob/main/src/simscene/evidence_integrity.py): `src/simscene/evidence_integrity.py`

### Agent access and delivery

- [MCP tools](https://github.com/ros-claw/simscene/blob/main/src/simscene/mcp_server.py): `src/simscene/mcp_server.py`
- [Capture and video](https://github.com/ros-claw/simscene/blob/main/src/simscene/capture.py): `src/simscene/capture.py`

### Other components

- **Agent / user**
- **Online asset sources**
- **Isaac Sim host**

## Connections

- Agent / user → MCP tools: requests tools (evidence: `README.md`)
- MCP tools → Catalog facade: exposes search (evidence: `src/simscene/catalog/service.py`)
- Catalog facade → Asset catalog: searches assets (evidence: `src/simscene/catalog/service.py`)
- Asset catalog → Catalog metadata: returns metadata (evidence: `src/simscene/catalog/search.py`)
- Asset catalog → Catalog providers: queries providers (evidence: `src/simscene/catalog/search.py`)
- Catalog providers → Online asset sources: retrieves listings (evidence: `README.md`)
- Agent / user → Asset acquisition: selects assets (evidence: `README.md`)
- Asset acquisition → Asset cache: stores downloads
- Agent / user → Preparation jobs: prepares selection (evidence: `README.md`)
- Preparation jobs → Preparation worker: runs job (evidence: `src/simscene/preparation/jobs.py`)
- Preparation worker → Asset acquisition: acquires selection (evidence: `src/simscene/preparation/worker.py`)
- Preparation worker → Asset physics binding: uses bindings (evidence: `src/simscene/preparation/worker.py`)
- Agent / user → Sand3D generation: requests generation (evidence: `README.md`)
- Agent / user → Scene recipes: reuses recipes (evidence: `README.md`)
- Agent / user → Editable scene: composes scene (evidence: `README.md`)
- Editable scene → Asset physics binding: validates assets (evidence: `src/simscene/scene.py`)
- Agent / user → Robotics profiles: configures robots
- Agent / user → Isaac execution: runs simulation (evidence: `README.md`)
- Isaac execution → Isaac Sim host: executes physics (evidence: `README.md`)
- Isaac execution → Case execution: runs case (evidence: `src/simscene/worker/isaac_run.py`)
- Isaac execution → Mechanism runtime: observes mechanisms (evidence: `src/simscene/worker/isaac_run.py`)
- Agent / user → Mechanism checks: checks observations (evidence: `README.md`)
- Agent / user → Passive network checks: checks handoffs (evidence: `README.md`)
- Agent / user → Structural load checks: checks loads (evidence: `README.md`)
- D6 mechanism checks → D6 admission: checks admission (evidence: `src/simscene/verification/mechanism_v2.py`)
- D6 network checks → D6 admission: checks admission (evidence: `src/simscene/verification/passive_network_v3.py`)
- Agent / user → Run input integrity: checks run locks (evidence: `README.md`)
- Run input integrity → Asset snapshot integrity: checks snapshots (evidence: `src/simscene/run_integrity.py`)
- Agent / user → Output hash checks: seals outputs (evidence: `README.md`)
- Agent / user → Capture and video: records simulation (evidence: `README.md`)
- Capture and video → Isaac Sim host: captures frames (evidence: `README.md`)
