# firefly174/detm architecture

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

- Interactive diagram: https://gitdiagram.com/firefly174/detm
- Repository: https://github.com/firefly174/detm

## Overview

DETM is a research simulator for discrete entropy-time dynamics on a lattice, with headless and interactive workflows. The main path is launch/configure → create a session → advance model state → collect subscriber outputs and artifacts. The graph also preserves analysis, ComfyUI integration, and the documented fabric/coordination capability. Several fabric and UI internals are unsampled; their links are shown only where documented or left unverified, rather than inferred from directory names.

Main entry points: [`detm/runtime/api/core.py`](https://github.com/firefly174/detm/blob/main/detm/runtime/api/core.py) (Runtime API), [`detm_app/runner/headless/main.py`](https://github.com/firefly174/detm/blob/main/detm_app/runner/headless/main.py) (Headless Runner), [`detm_app/ui/napari/interactive/controller.py`](https://github.com/firefly174/detm/blob/main/detm_app/ui/napari/interactive/controller.py) (Napari Controls), [`detm_app/runtime/session`](https://github.com/firefly174/detm/tree/main/detm_app/runtime/session) (Simulation Session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launch["Launch and UI"]
  node_launcher["Launcher<br/>[main.py]"]
  node_headless["Headless Runner<br/>[main.py]"]
  node_interactive["Napari Controls<br/>[controller.py]"]
  node_graphui["Graph View<br/>[graph.py]"]
  node_render["Field Rendering<br/>[render.py]"]
end

subgraph group_model["Model Runtime"]
  node_session["Simulation Session"]
  node_api["Runtime API<br/>[core.py]"]
  node_state["Model State<br/>[state.py]"]
  node_lattice["Lattice Fields<br/>[fields.py]"]
  node_dynamics["Entropy Dynamics<br/>[entropy.py]"]
  node_backend["Compute Backends"]
  node_refinement["Refinement Pipeline<br/>[orchestrator.py]"]
end

subgraph group_results["Analysis and Results"]
  node_subscribers["Runtime Subscribers"]
  node_serialization["State Serialization<br/>[__init__.py]"]
  node_analysis["Diagnostics<br/>[attractors.py]"]
  node_experiments["Experiment Protocols<br/>[marker_protocol.py]"]
end

subgraph group_coordination["Integration and Fabric"]
  node_fabric["Coordination Fabric"]
  node_transport["Viz Transport<br/>[client.py]"]
  node_comfy["ComfyUI Nodes<br/>[core.py]"]
  node_acgs["ACGS Backend<br/>[acgs_backend.py]"]
end

node_user(("Researcher"))

node_user -->|"launches"| node_launcher
node_launcher -->|"routes to"| node_headless
node_user -->|"runs batch"| node_headless
node_headless -->|"creates"| node_session
node_headless -->|"attaches"| node_subscribers
node_session -.->|"advances via"| node_api
node_api -.->|"updates"| node_state
node_state -->|"uses"| node_lattice
node_state -->|"uses"| node_dynamics
node_api -->|"serializes"| node_serialization
node_api -.->|"selects"| node_backend
node_session -.->|"applies"| node_refinement
node_subscribers -.->|"collects"| node_analysis
node_headless -.->|"supports runs"| node_experiments
node_user -->|"opens UI"| node_interactive
node_launcher -->|"routes to"| node_interactive
node_interactive -->|"updates"| node_graphui
node_interactive -->|"renders"| node_render
node_interactive -.->|"steps"| node_session
node_user -.->|"uses nodes"| node_comfy
node_comfy -->|"calls"| node_api
node_api -.->|"configures"| node_fabric
node_user -->|"enables handshake"| node_fabric
node_user -.->|"connects viz"| node_transport
node_acgs -->|"adapts runtime"| node_api

click node_launcher "https://github.com/firefly174/detm/blob/main/main.py"
click node_headless "https://github.com/firefly174/detm/blob/main/detm_app/runner/headless/main.py"
click node_interactive "https://github.com/firefly174/detm/blob/main/detm_app/ui/napari/interactive/controller.py"
click node_graphui "https://github.com/firefly174/detm/blob/main/detm_app/ui/napari/interactive/flow/graph.py"
click node_render "https://github.com/firefly174/detm/blob/main/detm_app/ui/napari/interactive/flow/render.py"
click node_session "https://github.com/firefly174/detm/tree/main/detm_app/runtime/session"
click node_api "https://github.com/firefly174/detm/blob/main/detm/runtime/api/core.py"
click node_state "https://github.com/firefly174/detm/blob/main/detm/runtime/state.py"
click node_lattice "https://github.com/firefly174/detm/blob/main/detm/core/fields.py"
click node_dynamics "https://github.com/firefly174/detm/blob/main/detm/core/entropy.py"
click node_backend "https://github.com/firefly174/detm/tree/main/detm/runtime/backends"
click node_refinement "https://github.com/firefly174/detm/blob/main/detm/runtime/refinement/pipeline/orchestrator.py"
click node_subscribers "https://github.com/firefly174/detm/tree/main/detm_app/runtime/subscribers"
click node_serialization "https://github.com/firefly174/detm/blob/main/detm/runtime/serialization/__init__.py"
click node_analysis "https://github.com/firefly174/detm/blob/main/detm/runtime/diagnostics/attractors.py"
click node_experiments "https://github.com/firefly174/detm/blob/main/experiments/marker_protocol.py"
click node_fabric "https://github.com/firefly174/detm/tree/main/detm/runtime/fabric"
click node_transport "https://github.com/firefly174/detm/blob/main/detm_app/transport/client.py"
click node_comfy "https://github.com/firefly174/detm/blob/main/comfyui_nodes/DETM/core.py"
click node_acgs "https://github.com/firefly174/detm/blob/main/detm/integrations/acgs_backend.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_launcher,node_headless,node_interactive,node_graphui,node_render toneBlue
class node_session,node_api,node_state,node_lattice,node_dynamics,node_backend,node_refinement toneAmber
class node_subscribers,node_serialization,node_analysis,node_experiments toneMint
class node_fabric,node_transport,node_comfy,node_acgs toneRose
class node_user toneIndigo
```

## Components

### Launch and UI

- [Launcher](https://github.com/firefly174/detm/blob/main/main.py): `main.py`
- [Headless Runner](https://github.com/firefly174/detm/blob/main/detm_app/runner/headless/main.py): `detm_app/runner/headless/main.py`
- [Napari Controls](https://github.com/firefly174/detm/blob/main/detm_app/ui/napari/interactive/controller.py): `detm_app/ui/napari/interactive/controller.py`
- [Graph View](https://github.com/firefly174/detm/blob/main/detm_app/ui/napari/interactive/flow/graph.py): `detm_app/ui/napari/interactive/flow/graph.py`
- [Field Rendering](https://github.com/firefly174/detm/blob/main/detm_app/ui/napari/interactive/flow/render.py): `detm_app/ui/napari/interactive/flow/render.py`

### Model Runtime

- [Simulation Session](https://github.com/firefly174/detm/tree/main/detm_app/runtime/session): `detm_app/runtime/session`
- [Runtime API](https://github.com/firefly174/detm/blob/main/detm/runtime/api/core.py): `detm/runtime/api/core.py`
- [Model State](https://github.com/firefly174/detm/blob/main/detm/runtime/state.py): `detm/runtime/state.py`
- [Lattice Fields](https://github.com/firefly174/detm/blob/main/detm/core/fields.py): `detm/core/fields.py`
- [Entropy Dynamics](https://github.com/firefly174/detm/blob/main/detm/core/entropy.py): `detm/core/entropy.py`
- [Compute Backends](https://github.com/firefly174/detm/tree/main/detm/runtime/backends): `detm/runtime/backends`
- [Refinement Pipeline](https://github.com/firefly174/detm/blob/main/detm/runtime/refinement/pipeline/orchestrator.py): `detm/runtime/refinement/pipeline/orchestrator.py`

### Analysis and Results

- [Runtime Subscribers](https://github.com/firefly174/detm/tree/main/detm_app/runtime/subscribers): `detm_app/runtime/subscribers`
- [State Serialization](https://github.com/firefly174/detm/blob/main/detm/runtime/serialization/__init__.py): `detm/runtime/serialization/__init__.py`
- [Diagnostics](https://github.com/firefly174/detm/blob/main/detm/runtime/diagnostics/attractors.py): `detm/runtime/diagnostics/attractors.py`
- [Experiment Protocols](https://github.com/firefly174/detm/blob/main/experiments/marker_protocol.py): `experiments/marker_protocol.py`

### Integration and Fabric

- [Coordination Fabric](https://github.com/firefly174/detm/tree/main/detm/runtime/fabric): `detm/runtime/fabric`
- [Viz Transport](https://github.com/firefly174/detm/blob/main/detm_app/transport/client.py): `detm_app/transport/client.py`
- [ComfyUI Nodes](https://github.com/firefly174/detm/blob/main/comfyui_nodes/DETM/core.py): `comfyui_nodes/DETM/core.py`
- [ACGS Backend](https://github.com/firefly174/detm/blob/main/detm/integrations/acgs_backend.py): `detm/integrations/acgs_backend.py`

### Other components

- **Researcher**

## Connections

- Researcher → Launcher: launches (evidence: `README.md`)
- Launcher → Headless Runner: routes to (evidence: `main.py`)
- Researcher → Headless Runner: runs batch (evidence: `README.md`)
- Headless Runner → Simulation Session: creates (evidence: `detm_app/runner/headless/main.py`)
- Headless Runner → Runtime Subscribers: attaches (evidence: `detm_app/runner/headless/main.py`)
- Simulation Session → Runtime API: advances via
- Runtime API → Model State: updates
- Model State → Lattice Fields: uses (evidence: `detm/runtime/state.py`)
- Model State → Entropy Dynamics: uses (evidence: `detm/runtime/state.py`)
- Runtime API → State Serialization: serializes (evidence: `detm/runtime/api/__init__.py`)
- Runtime API → Compute Backends: selects
- Simulation Session → Refinement Pipeline: applies
- Runtime Subscribers → Diagnostics: collects
- Headless Runner → Experiment Protocols: supports runs
- Researcher → Napari Controls: opens UI (evidence: `README.md`)
- Launcher → Napari Controls: routes to (evidence: `main.py`)
- Napari Controls → Graph View: updates (evidence: `detm_app/ui/napari/interactive/controller.py`)
- Napari Controls → Field Rendering: renders (evidence: `detm_app/ui/napari/interactive/controller.py`)
- Napari Controls → Simulation Session: steps
- Researcher → ComfyUI Nodes: uses nodes
- ComfyUI Nodes → Runtime API: calls (evidence: `comfyui_nodes/DETM/core.py`)
- Runtime API → Coordination Fabric: configures
- Researcher → Coordination Fabric: enables handshake (evidence: `README.md`)
- Researcher → Viz Transport: connects viz
- ACGS Backend → Runtime API: adapts runtime (evidence: `detm/integrations/acgs_backend.py`)
