# j8-diablo/ddmx architecture

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

- Interactive diagram: https://gitdiagram.com/j8-diablo/ddmx
- Repository: https://github.com/j8-diablo/ddmx

## Overview

DDMX is a Flask-based web controller for DMX/ArtNet lighting rigs. Operators configure fixtures and devices, edit or select JSON cues, then trigger playback or live effects; the backend renders channel values and sends ArtNet output. The UI also exposes identify, timeline/sequence, and video-sync capabilities. The README documents the API and workflow, while excerpts show engine rendering and ArtNet emission; some internal routing and optional integrations are not shown, so those connections are omitted or marked unverified.

Main entry points: [`app.py`](https://github.com/j8-diablo/ddmx/blob/main/app.py) (Flask API), [`dmx_engine.py`](https://github.com/j8-diablo/ddmx/blob/main/dmx_engine.py) (Render Engine), [`static/ui.js`](https://github.com/j8-diablo/ddmx/blob/main/static/ui.js) (Web UI), [`fixture_runtime.py`](https://github.com/j8-diablo/ddmx/blob/main/fixture_runtime.py) (Fixture Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Operator Interface"]
  node_web_ui["Web UI<br/>[ui.js]"]
  node_rig_editor["Rig Editor<br/>[rig.js]"]
  node_cue_editor["Cue Editor<br/>[cues.js]"]
  node_effects_ui["Effects UI<br/>[effects.js]"]
  node_timeline["Timeline<br/>[timeline.js]"]
  node_video_sync["Video Sync<br/>[sync_video.js]"]
  node_desktop_shell["Desktop Shell<br/>[gui.py]"]
end

subgraph group_control["Control and Show Data"]
  node_flask_api["Flask API<br/>[app.py]"]
  node_fixture_runtime["Fixture Parser<br/>[fixture_runtime.py]"]
  node_fixture_defs["Fixture Definitions"]
  node_cue_files["Cue Files"]
  node_effect_catalog["Effect Catalog"]
end

subgraph group_render["Rendering"]
  node_render_engine["Render Engine<br/>[dmx_engine.py]"]
  node_simple_engine["Simple Engine"]
  node_effect_lfo["LFO Effects<br/>[Effect.py]"]
  node_intelligent_fx["Intelligent Effects<br/>[intelligent_fx.py]"]
end

subgraph group_transport["DMX Transport"]
  node_artnet_client["ArtNet Sender<br/>[DMXE.py]"]
  node_artnet_network(("ArtNet Network"))
end

node_operator(("Lighting Operator"))

node_operator -->|"operates"| node_web_ui
node_web_ui -->|"calls API"| node_flask_api
node_rig_editor -->|"manages rig"| node_flask_api
node_cue_editor -->|"manages cues"| node_flask_api
node_effects_ui -->|"starts effects"| node_flask_api
node_timeline -->|"controls playback"| node_flask_api
node_video_sync -.->|"sync settings"| node_flask_api
node_flask_api -->|"parses fixtures"| node_fixture_runtime
node_fixture_runtime -->|"loads definitions"| node_fixture_defs
node_flask_api -->|"reads and writes"| node_cue_files
node_flask_api -->|"lists effects"| node_effect_catalog
node_flask_api -->|"controls rendering"| node_render_engine
node_render_engine -->|"sends universes"| node_artnet_client
node_artnet_client -->|"emits packets"| node_artnet_network
node_render_engine -->|"uses LFOs"| node_effect_lfo
node_render_engine -->|"evaluates effects"| node_intelligent_fx
node_flask_api -.->|"selects engine"| node_simple_engine
node_desktop_shell -.->|"hosts server"| node_flask_api

click node_web_ui "https://github.com/j8-diablo/ddmx/blob/main/static/ui.js"
click node_rig_editor "https://github.com/j8-diablo/ddmx/blob/main/static/rig.js"
click node_cue_editor "https://github.com/j8-diablo/ddmx/blob/main/static/cues.js"
click node_effects_ui "https://github.com/j8-diablo/ddmx/blob/main/static/effects.js"
click node_timeline "https://github.com/j8-diablo/ddmx/blob/main/static/timeline.js"
click node_video_sync "https://github.com/j8-diablo/ddmx/blob/main/static/sync_video.js"
click node_flask_api "https://github.com/j8-diablo/ddmx/blob/main/app.py"
click node_fixture_runtime "https://github.com/j8-diablo/ddmx/blob/main/fixture_runtime.py"
click node_fixture_defs "https://github.com/j8-diablo/ddmx/tree/main/fixtures"
click node_cue_files "https://github.com/j8-diablo/ddmx/tree/main/cue"
click node_effect_catalog "https://github.com/j8-diablo/ddmx/blob/main/effects_definitions.json"
click node_render_engine "https://github.com/j8-diablo/ddmx/blob/main/dmx_engine.py"
click node_simple_engine "https://github.com/j8-diablo/ddmx/blob/main/dmx_engine_simple.py"
click node_effect_lfo "https://github.com/j8-diablo/ddmx/blob/main/Effect.py"
click node_intelligent_fx "https://github.com/j8-diablo/ddmx/blob/main/intelligent_fx.py"
click node_artnet_client "https://github.com/j8-diablo/ddmx/blob/main/DMXE.py"
click node_desktop_shell "https://github.com/j8-diablo/ddmx/blob/main/gui.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_web_ui,node_rig_editor,node_cue_editor,node_effects_ui,node_timeline,node_video_sync,node_desktop_shell toneBlue
class node_flask_api,node_fixture_runtime,node_fixture_defs,node_cue_files,node_effect_catalog toneAmber
class node_render_engine,node_simple_engine,node_effect_lfo,node_intelligent_fx toneMint
class node_artnet_client,node_artnet_network toneRose
class node_operator toneIndigo
```

## Components

### Operator Interface

- [Web UI](https://github.com/j8-diablo/ddmx/blob/main/static/ui.js): `static/ui.js`
- [Rig Editor](https://github.com/j8-diablo/ddmx/blob/main/static/rig.js): `static/rig.js`
- [Cue Editor](https://github.com/j8-diablo/ddmx/blob/main/static/cues.js): `static/cues.js`
- [Effects UI](https://github.com/j8-diablo/ddmx/blob/main/static/effects.js): `static/effects.js`
- [Timeline](https://github.com/j8-diablo/ddmx/blob/main/static/timeline.js): `static/timeline.js`
- [Video Sync](https://github.com/j8-diablo/ddmx/blob/main/static/sync_video.js): `static/sync_video.js`
- [Desktop Shell](https://github.com/j8-diablo/ddmx/blob/main/gui.py): `gui.py`

### Control and Show Data

- [Flask API](https://github.com/j8-diablo/ddmx/blob/main/app.py): `app.py`
- [Fixture Parser](https://github.com/j8-diablo/ddmx/blob/main/fixture_runtime.py): `fixture_runtime.py`
- [Fixture Definitions](https://github.com/j8-diablo/ddmx/tree/main/fixtures): `fixtures`
- [Cue Files](https://github.com/j8-diablo/ddmx/tree/main/cue): `cue`
- [Effect Catalog](https://github.com/j8-diablo/ddmx/blob/main/effects_definitions.json): `effects_definitions.json`

### Rendering

- [Render Engine](https://github.com/j8-diablo/ddmx/blob/main/dmx_engine.py): `dmx_engine.py`
- [Simple Engine](https://github.com/j8-diablo/ddmx/blob/main/dmx_engine_simple.py): `dmx_engine_simple.py`
- [LFO Effects](https://github.com/j8-diablo/ddmx/blob/main/Effect.py): `Effect.py`
- [Intelligent Effects](https://github.com/j8-diablo/ddmx/blob/main/intelligent_fx.py): `intelligent_fx.py`

### DMX Transport

- [ArtNet Sender](https://github.com/j8-diablo/ddmx/blob/main/DMXE.py): `DMXE.py`
- **ArtNet Network**

### Other components

- **Lighting Operator**

## Connections

- Lighting Operator → Web UI: operates (evidence: `README.md`)
- Web UI → Flask API: calls API (evidence: `README.md`)
- Rig Editor → Flask API: manages rig (evidence: `README.md`)
- Cue Editor → Flask API: manages cues (evidence: `README.md`)
- Effects UI → Flask API: starts effects (evidence: `README.md`)
- Timeline → Flask API: controls playback (evidence: `README.md`)
- Video Sync → Flask API: sync settings
- Flask API → Fixture Parser: parses fixtures (evidence: `app.py`)
- Fixture Parser → Fixture Definitions: loads definitions (evidence: `README.md`)
- Flask API → Cue Files: reads and writes (evidence: `README.md`)
- Flask API → Effect Catalog: lists effects (evidence: `README.md`)
- Flask API → Render Engine: controls rendering (evidence: `README.md`)
- Render Engine → ArtNet Sender: sends universes (evidence: `dmx_engine.py`)
- ArtNet Sender → ArtNet Network: emits packets (evidence: `DMXE.py`)
- Render Engine → LFO Effects: uses LFOs (evidence: `dmx_engine.py`)
- Render Engine → Intelligent Effects: evaluates effects (evidence: `dmx_engine.py`)
- Flask API → Simple Engine: selects engine (evidence: `app.py`)
- Desktop Shell → Flask API: hosts server (evidence: `gui.py`)
