# toto171/loom architecture

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

- Interactive diagram: https://gitdiagram.com/toto171/loom
- Repository: https://github.com/toto171/loom

## Overview

1. **What Loom is**
   Loom is a Python 3.12+ framework for composing a vehicle from swappable subsystems, checking those subsystem contracts, simulating the composed vehicle against a plant model, and generating safety evidence artifacts. The repository is organized around a single end-to-end pipeline, not a standalone app server or a library of unrelated utilities.

2. **Primary inputs and configuration**
   The core input is a vehicle composition YAML file in `spec/` that references module contracts, plant selection, and scenario/fault configuration. Module-specific contract files live under `modules/*/contract*.yaml`; plant implementations live under `plant/*/plant.py`; scenarios live under `scenarios/*.yaml`. Schema definitions in `spec/schema/` define the two main configuration domains: vehicle composition and module contracts.

3. **Composition and resolution layer**
   The `loom.compose` package is the first major subsystem. It loads the vehicle composition, resolves module references, and produces a composed model. This layer is the boundary where the declared vehicle architecture is turned into an executable configuration that later stages can validate, simulate, and analyze.

4. **Contract and static-checking layer**
   The `loom.contracts` package models each module’s contract and performs static composition checks. The checker enforces things like producer uniqueness, signal resolution, units consistency, and timing/assume-guarantee constraints. It also encodes an explicit license policy for default modules, so legal metadata is treated as part of the architecture rather than an afterthought.

5. **Runtime execution core**
   The execution entrypoint is `loom.run.execute_run`, which the CLI and dashboard both reuse. The main lifecycle is: compose → validate → check → gate → simulate → assure. This is the central data flow of the repo; every user-facing path ultimately converges here.

6. **Orchestrators and bus abstraction**
   Loom separates orchestration from the bus transport. The `loom.orchestrator` package defines the control loop and multiple orchestrator backends: in-process, Compose/KUKSA, and Ankaios. The `loom.bus` package provides the transport abstraction, with a shim/in-process bus and a KUKSA-backed bus. This boundary is important because it lets the same simulation/control loop run either locally or against distributed infrastructure.

7. **Modules and closed-loop vehicle behavior**
   The reference modules in `modules/` are the swappable subsystems being composed: BMS, powertrain, ADAS, HMI, and body. In the default closed loop, the driver target speed propagates through powertrain commands into the plant, while BMS tracks state of charge and reacts to plant state. These modules are intentionally split from the plant so the architecture can show how contract changes affect composition without changing the underlying physics model.

8. **Plant models**
   The `loom.plant` package loads the plant implementation selected by the vehicle spec. The repository includes at least two plant families: a longitudinal plant and a higher-fidelity Motoquant plant. Plant choice changes simulation fidelity and dynamics but does not require changing module contracts, which is a key separation in the architecture.

9. **Simulation, stimuli, and fault injection**
   The `loom.sim` package contains the execution-time mechanics around scenarios, stimulus generation, traces, and faults. Scenario files drive the simulated driving conditions, while fault injection can model dropout, stuck values, latency, and crashes. This layer feeds the runtime monitors and produces trace artifacts for later reporting.

10. **Monitoring and safety gating**
   Runtime checks live in `loom.monitors` and `loom.safety`. Monitors evaluate predicates over observed runtime signals, and the safety gate blocks below-line swaps unless revalidation is explicitly requested. This is the repository’s main safety boundary: it separates allowed “above the line” changes from changes that require renewed evidence.

11. **Assurance artifacts**
   The `loom.assurance` package generates evidence artifacts during or after a run. The README indicates three main outputs: per-module SBOMs, an aggregate vehicle SBOM, and a GSN assurance-case skeleton. These are written into each `runs/<id>/` directory along with trace and report data, making the run directory the primary evidence bundle for a composition.

12. **Deployment path**
   The `loom.deploy` package generates an Eclipse Ankaios workload manifest for composed systems. This is a separate output path from simulation: it translates the same composed vehicle model into deployment-oriented artifacts rather than runtime evidence. That makes deployment another first-class boundary in the architecture.

13. **Dashboard and operational surface**
   The `dashboard/` app is a FastAPI-based UI with HTML templates for composing vehicles, launching runs, and inspecting results. It is a thin operational frontend over the same execution core used by the CLI, so it does not define a separate business path; it visualizes and drives the same pipeline.

14. **Persistence and baseline state**
   Runs are persisted under `runs/` and the safety baseline is committed in `locks/*.lock.json`. The committed lock file is architecturally important because it prevents the safety gate from being reset simply by deleting local run outputs. In other words, the repository distinguishes transient evidence from versioned safety state.

15. **How to think about the architecture diagram**
   A good diagram for this repo should show a left-to-right flow from composition spec and contracts, through static checking and gating, into simulation with modules, bus, orchestrator, and plant, and then out to monitoring, SBOM/GSN assurance artifacts, and deployment output. The key cross-cutting boundaries are: contract vs runtime, orchestrator vs bus, modules vs plant, and transient run evidence vs committed lock/baseline state.

Main entry points: [`loom/orchestrator/_loop.py`](https://github.com/toto171/loom/blob/main/loom/orchestrator/_loop.py) (Control loop), [`loom/run.py`](https://github.com/toto171/loom/blob/main/loom/run.py) (Run pipeline), [`loom/plant/loader.py`](https://github.com/toto171/loom/blob/main/loom/plant/loader.py) (Plant loader), [`spec/vehicle.example.yaml`](https://github.com/toto171/loom/blob/main/spec/vehicle.example.yaml) (Vehicle spec)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs & specs"]
  node_spec_vehicle["Vehicle spec<br/>composition yaml"]
  node_spec_schema_comp["Comp schema"]
  node_spec_schema_contract["Contract schema"]
end

subgraph group_core["Core pipeline"]
  node_contracts_loader["Contract loader<br/>contracts<br/>[loader.py]"]
  node_contracts_model["Contract model<br/>contracts<br/>[model.py]"]
  node_contracts_checker["Static checks<br/>contracts<br/>[checker.py]"]
  node_compose_loader["Compose loader<br/>[loader.py]"]
  node_compose_resolve["Resolver<br/>compose<br/>[resolve.py]"]
  node_compose_model["Composed model<br/>[model.py]"]
  node_run_execute["Run pipeline<br/>runtime<br/>[run.py]"]
  node_orchestrator_loop["Control loop<br/>orchestrator<br/>[_loop.py]"]
  node_safety_gate["Safety gate<br/>[gate.py]"]
  node_monitors_engine["Monitors<br/>runtime checks<br/>[engine.py]"]
end

subgraph group_runtime["Runtime backends"]
  node_bus_base["Bus API<br/>[base.py]"]
  node_bus_shim["Shim bus<br/>[shim.py]"]
  node_bus_kuksa["KUKSA bus<br/>[kuksa.py]"]
  node_orch_inprocess["In-process orch<br/>orchestrator<br/>[inprocess.py]"]
  node_orch_compose["Compose orch<br/>orchestrator<br/>[compose.py]"]
  node_orch_ankaios["Ankaios orch<br/>orchestrator<br/>[ankaios.py]"]
  node_modules["Modules<br/>swappable subsystems"]
  node_plant_loader["Plant loader<br/>[loader.py]"]
  node_plant_long["Longitudinal<br/>plant model<br/>[plant.py]"]
  node_plant_moto["Motoquant<br/>plant model<br/>[plant.py]"]
  node_sim_faults["Faults<br/>simulation<br/>[faults.py]"]
  node_sim_scenario["Scenario<br/>simulation<br/>[scenario.py]"]
end

subgraph group_outputs["Outputs & ops"]
  node_sim_trace["Trace<br/>simulation<br/>[trace.py]"]
  node_assure_sbom["SBOMs<br/>assurance<br/>[sbom.py]"]
  node_assure_gsn["GSN case<br/>assurance<br/>[gsn.py]"]
  node_deploy_ankaios["Deploy manifest<br/>deployment<br/>[ankaios.py]"]
  node_dashboard_app["Dashboard<br/>fastapi UI<br/>[app.py]"]
  node_runs[("Run artifacts<br/>evidence store")]
  node_locks["Safety lock<br/>baseline state"]
end

node_spec_vehicle -->|"loads"| node_compose_loader
node_spec_vehicle -->|"selects"| node_plant_loader
node_spec_vehicle -->|"references"| node_sim_scenario
node_spec_schema_comp -->|"validates"| node_compose_loader
node_spec_schema_contract -->|"validates"| node_contracts_loader
node_contracts_loader -->|"builds"| node_contracts_model
node_contracts_model -->|"checks"| node_contracts_checker
node_compose_loader -->|"hands off"| node_compose_resolve
node_compose_resolve -->|"produces"| node_compose_model
node_compose_model -->|"static check"| node_contracts_checker
node_compose_model -->|"inputs"| node_run_execute
node_run_execute -->|"drives"| node_orchestrator_loop
node_orchestrator_loop -->|"uses"| node_bus_base
node_bus_base -->|"implements"| node_bus_shim
node_bus_base -->|"implements"| node_bus_kuksa
node_orchestrator_loop -->|"backend"| node_orch_inprocess
node_orchestrator_loop -->|"backend"| node_orch_compose
node_orchestrator_loop -->|"backend"| node_orch_ankaios
node_orchestrator_loop -->|"executes"| node_modules
node_modules -->|"commands"| node_plant_loader
node_plant_loader -->|"loads"| node_plant_long
node_plant_loader -->|"loads"| node_plant_moto
node_sim_scenario -->|"combines"| node_sim_faults
node_sim_faults -->|"records"| node_sim_trace
node_orchestrator_loop -->|"observes"| node_monitors_engine
node_monitors_engine -->|"gates"| node_safety_gate
node_run_execute -->|"emits"| node_assure_sbom
node_run_execute -->|"emits"| node_assure_gsn
node_run_execute -->|"exports"| node_deploy_ankaios
node_run_execute -->|"persists"| node_runs
node_sim_trace -->|"stored in"| node_runs
node_dashboard_app -->|"reuses"| node_run_execute
node_locks -->|"baseline"| node_safety_gate

click node_spec_vehicle "https://github.com/toto171/loom/blob/main/spec/vehicle.example.yaml"
click node_spec_schema_comp "https://github.com/toto171/loom/blob/main/spec/schema/composition.schema.json"
click node_spec_schema_contract "https://github.com/toto171/loom/blob/main/spec/schema/contract.schema.json"
click node_contracts_loader "https://github.com/toto171/loom/blob/main/loom/contracts/loader.py"
click node_contracts_model "https://github.com/toto171/loom/blob/main/loom/contracts/model.py"
click node_contracts_checker "https://github.com/toto171/loom/blob/main/loom/contracts/checker.py"
click node_compose_loader "https://github.com/toto171/loom/blob/main/loom/compose/loader.py"
click node_compose_resolve "https://github.com/toto171/loom/blob/main/loom/compose/resolve.py"
click node_compose_model "https://github.com/toto171/loom/blob/main/loom/compose/model.py"
click node_run_execute "https://github.com/toto171/loom/blob/main/loom/run.py"
click node_orchestrator_loop "https://github.com/toto171/loom/blob/main/loom/orchestrator/_loop.py"
click node_bus_base "https://github.com/toto171/loom/blob/main/loom/bus/base.py"
click node_bus_shim "https://github.com/toto171/loom/blob/main/loom/bus/shim.py"
click node_bus_kuksa "https://github.com/toto171/loom/blob/main/loom/bus/kuksa.py"
click node_orch_inprocess "https://github.com/toto171/loom/blob/main/loom/orchestrator/inprocess.py"
click node_orch_compose "https://github.com/toto171/loom/blob/main/loom/orchestrator/compose.py"
click node_orch_ankaios "https://github.com/toto171/loom/blob/main/loom/orchestrator/ankaios.py"
click node_modules "https://github.com/toto171/loom/tree/main/modules"
click node_plant_loader "https://github.com/toto171/loom/blob/main/loom/plant/loader.py"
click node_plant_long "https://github.com/toto171/loom/blob/main/plant/longitudinal/plant.py"
click node_plant_moto "https://github.com/toto171/loom/blob/main/plant/motoquant/plant.py"
click node_sim_faults "https://github.com/toto171/loom/blob/main/loom/sim/faults.py"
click node_sim_scenario "https://github.com/toto171/loom/blob/main/loom/sim/scenario.py"
click node_sim_trace "https://github.com/toto171/loom/blob/main/loom/sim/trace.py"
click node_safety_gate "https://github.com/toto171/loom/blob/main/loom/safety/gate.py"
click node_monitors_engine "https://github.com/toto171/loom/blob/main/loom/monitors/engine.py"
click node_assure_sbom "https://github.com/toto171/loom/blob/main/loom/assurance/sbom.py"
click node_assure_gsn "https://github.com/toto171/loom/blob/main/loom/assurance/gsn.py"
click node_deploy_ankaios "https://github.com/toto171/loom/blob/main/loom/deploy/ankaios.py"
click node_dashboard_app "https://github.com/toto171/loom/blob/main/dashboard/app.py"
click node_locks "https://github.com/toto171/loom/blob/main/locks/toy-ev-l7.lock.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_spec_vehicle,node_spec_schema_comp,node_spec_schema_contract toneBlue
class node_contracts_loader,node_contracts_model,node_contracts_checker,node_compose_loader,node_compose_resolve,node_compose_model,node_run_execute,node_orchestrator_loop,node_safety_gate,node_monitors_engine toneAmber
class node_bus_base,node_bus_shim,node_bus_kuksa,node_orch_inprocess,node_orch_compose,node_orch_ankaios,node_modules,node_plant_loader,node_plant_long,node_plant_moto,node_sim_faults,node_sim_scenario toneMint
class node_sim_trace,node_assure_sbom,node_assure_gsn,node_deploy_ankaios,node_dashboard_app,node_runs,node_locks toneRose
```

## Components

### Inputs & specs

Repository files that declare vehicles, contracts, scenarios, and schemas.

- [Vehicle spec](https://github.com/toto171/loom/blob/main/spec/vehicle.example.yaml): composition yaml · Top-level vehicle composition and subsystem selection. · `spec/vehicle.example.yaml`
- [Comp schema](https://github.com/toto171/loom/blob/main/spec/schema/composition.schema.json): schema · Vehicle composition schema definitions. · `spec/schema/composition.schema.json`
- [Contract schema](https://github.com/toto171/loom/blob/main/spec/schema/contract.schema.json): schema · Module contract schema definitions. · `spec/schema/contract.schema.json`

### Core pipeline

Composition, checking, orchestration, simulation, and runtime control.

- [Contract loader](https://github.com/toto171/loom/blob/main/loom/contracts/loader.py): contracts · Loads module contracts from YAML. · `loom/contracts/loader.py`
- [Contract model](https://github.com/toto171/loom/blob/main/loom/contracts/model.py): contracts · Represents module contracts and related metadata. · `loom/contracts/model.py`
- [Static checks](https://github.com/toto171/loom/blob/main/loom/contracts/checker.py): contracts · Enforces uniqueness, resolution, units, timing, and policy rules. · `loom/contracts/checker.py`
- [Compose loader](https://github.com/toto171/loom/blob/main/loom/compose/loader.py): compose · Loads the vehicle composition and module references. · `loom/compose/loader.py`
- [Resolver](https://github.com/toto171/loom/blob/main/loom/compose/resolve.py): compose · Resolves referenced modules into a composed model. · `loom/compose/resolve.py`
- [Composed model](https://github.com/toto171/loom/blob/main/loom/compose/model.py): compose · Executable vehicle configuration used by later stages. · `loom/compose/model.py`
- [Run pipeline](https://github.com/toto171/loom/blob/main/loom/run.py): runtime · Main execution entrypoint that drives compose, validate, check, gate, simulate, and assure. · `loom/run.py`
- [Control loop](https://github.com/toto171/loom/blob/main/loom/orchestrator/_loop.py): orchestrator · Shared orchestration loop for runtime execution. · `loom/orchestrator/_loop.py`
- [Safety gate](https://github.com/toto171/loom/blob/main/loom/safety/gate.py): safety · Blocks below-line swaps unless revalidation is requested. · `loom/safety/gate.py`
- [Monitors](https://github.com/toto171/loom/blob/main/loom/monitors/engine.py): runtime checks · Evaluates predicates over observed runtime signals. · `loom/monitors/engine.py`

### Runtime backends

Swappable modules, buses, plants, and deployment targets.

- [Bus API](https://github.com/toto171/loom/blob/main/loom/bus/base.py): bus · Transport abstraction for module communication. · `loom/bus/base.py`
- [Shim bus](https://github.com/toto171/loom/blob/main/loom/bus/shim.py): bus · In-process bus implementation. · `loom/bus/shim.py`
- [KUKSA bus](https://github.com/toto171/loom/blob/main/loom/bus/kuksa.py): bus · KUKSA-backed bus implementation. · `loom/bus/kuksa.py`
- [In-process orch](https://github.com/toto171/loom/blob/main/loom/orchestrator/inprocess.py): orchestrator · Local orchestrator backend. · `loom/orchestrator/inprocess.py`
- [Compose orch](https://github.com/toto171/loom/blob/main/loom/orchestrator/compose.py): orchestrator · Compose/KUKSA orchestrator backend. · `loom/orchestrator/compose.py`
- [Ankaios orch](https://github.com/toto171/loom/blob/main/loom/orchestrator/ankaios.py): orchestrator · Distributed Ankaios orchestrator backend. · `loom/orchestrator/ankaios.py`
- [Modules](https://github.com/toto171/loom/tree/main/modules): swappable subsystems · Reference vehicle subsystems such as BMS, powertrain, ADAS, HMI, and body. · `modules`
- [Plant loader](https://github.com/toto171/loom/blob/main/loom/plant/loader.py): plant · Selects and loads the configured plant implementation. · `loom/plant/loader.py`
- [Longitudinal](https://github.com/toto171/loom/blob/main/plant/longitudinal/plant.py): plant model · Lower-fidelity longitudinal plant. · `plant/longitudinal/plant.py`
- [Motoquant](https://github.com/toto171/loom/blob/main/plant/motoquant/plant.py): plant model · Higher-fidelity Motoquant plant. · `plant/motoquant/plant.py`
- [Faults](https://github.com/toto171/loom/blob/main/loom/sim/faults.py): simulation · Fault injection for dropout, stuck values, latency, and crashes. · `loom/sim/faults.py`
- [Scenario](https://github.com/toto171/loom/blob/main/loom/sim/scenario.py): simulation · Driving scenario and stimulus selection. · `loom/sim/scenario.py`

### Outputs & ops

Safety evidence, run artifacts, dashboard, and persisted state.

- [Trace](https://github.com/toto171/loom/blob/main/loom/sim/trace.py): simulation · Execution traces produced by runs. · `loom/sim/trace.py`
- [SBOMs](https://github.com/toto171/loom/blob/main/loom/assurance/sbom.py): assurance · Per-module and aggregate SBOM evidence. · `loom/assurance/sbom.py`
- [GSN case](https://github.com/toto171/loom/blob/main/loom/assurance/gsn.py): assurance · Assurance-case skeleton generation. · `loom/assurance/gsn.py`
- [Deploy manifest](https://github.com/toto171/loom/blob/main/loom/deploy/ankaios.py): deployment · Generates Ankaios workload manifests from the composed vehicle. · `loom/deploy/ankaios.py`
- [Dashboard](https://github.com/toto171/loom/blob/main/dashboard/app.py): fastapi UI · Operational frontend for composing, launching runs, and inspecting results. · `dashboard/app.py`
- **Run artifacts**: evidence store · Per-run evidence bundle containing traces, reports, and generated artifacts.
- [Safety lock](https://github.com/toto171/loom/blob/main/locks/toy-ev-l7.lock.json): baseline state · Committed safety baseline that persists across local run cleanup. · `locks/toy-ev-l7.lock.json`

## Connections

- Vehicle spec → Compose loader: loads · The vehicle spec is parsed by the composition loader.
- Vehicle spec → Plant loader: selects · The vehicle spec selects the plant implementation.
- Vehicle spec → Scenario: references · The vehicle spec can reference scenarios and faults.
- Comp schema → Compose loader: validates · Composition schema constrains vehicle YAML.
- Contract schema → Contract loader: validates · Contract schema constrains module contract YAML.
- Contract loader → Contract model: builds · Contract files are loaded into the contract model.
- Contract model → Static checks: checks · The checker operates on the loaded contract model.
- Compose loader → Resolver: hands off · Loaded composition is resolved into concrete module references.
- Resolver → Composed model: produces · Resolution yields the composed vehicle model.
- Composed model → Static checks: static check · The composed model is checked against module contracts.
- Composed model → Run pipeline: inputs · The run pipeline consumes the composed model.
- Run pipeline → Control loop: drives · The run pipeline invokes the shared control loop.
- Control loop → Bus API: uses · The control loop communicates through the bus abstraction.
- Bus API → Shim bus: implements · Shim bus is one transport backend.
- Bus API → KUKSA bus: implements · KUKSA bus is another transport backend.
- Control loop → In-process orch: backend · In-process orchestration is one backend.
- Control loop → Compose orch: backend · Compose/KUKSA orchestration is one backend.
- Control loop → Ankaios orch: backend · Ankaios orchestration is one backend.
- Control loop → Modules: executes · Modules participate in the closed-loop control execution.
- Modules → Plant loader: commands · Module outputs drive the plant interface through the runtime loop.
- Plant loader → Longitudinal: loads · The loader can select the longitudinal plant.
- Plant loader → Motoquant: loads · The loader can select the Motoquant plant.
- Scenario → Faults: combines · Scenario execution can include injected faults.
- Faults → Trace: records · Faulted execution contributes to trace artifacts.
- Control loop → Monitors: observes · Runtime signals are evaluated by monitors.
- Monitors → Safety gate: gates · Monitor outcomes feed the safety gate.
- Run pipeline → SBOMs: emits · Runs generate SBOM evidence.
- Run pipeline → GSN case: emits · Runs generate assurance-case artifacts.
- Run pipeline → Deploy manifest: exports · The same composed model can be translated into deployment artifacts.
- Run pipeline → Run artifacts: persists · Run execution writes artifacts into the run directory.
- Trace → Run artifacts: stored in · Traces become part of the run evidence bundle.
- Dashboard → Run pipeline: reuses · The dashboard drives the same execution core as the CLI.
- Safety lock → Safety gate: baseline · Committed locks provide persistent safety baseline state.