TuxDMX-WebUI/ARCHITECTURE.md

TuxDMX arkitektur

All rights reserved - Thomas / TuxiNet

Mål

TuxDMX er bygget som en browserstyret lyscontroller med ærlig telemetri, simulator-first udvikling og hardwareisolering bag adapterinterfaces. Release 1.0 prioriterer stabil drift på fysisk Debian 13 amd64, testbarhed uden fysisk hardware og et mørkt UI, der kan bruges uden kode.

Konkrete valg

• Backend: FastAPI, Pydantic, SQLAlchemy 2, Alembic og SQLite i WAL mode.
• Frontend: React, TypeScript, Vite og et bevidst dark-only design med semantiske CSS-variabler.
• DMX-engine: Et isoleret frame-loop i en asynkron baggrundsopgave. HTTP kalder aldrig DMX-backenden synkront.
• Hardware: DmxBackend som interface med SimulatorDmxBackend og OlaDmxBackend. FakeOlaAdapter bruges i tests.
• Fixtures: OFL importeres via klient, normaliseres til et stabilt internt format og gemmes både som rå kilde og normaliseret model.
• Sikkerhed: Lokale brugere, Argon2, sessionscookies, CSRF-token, API-tokens, auditlog og tydelig rolleopdeling.
• Drift: systemd-units, Linux-installationsscripts, backup/restore, diagnostics bundle og smoke-test.

Procesmodel

Release 1.0 kører som én Python-applikation med tre logiske dele:

1. FastAPI API og WebSocket-lag.
2. DMX-engine med simulator/OLA-adapter.
3. BPM-, trigger- og telemetritjenester.

Det reducerer kompleksitet i første release, men modulerne er isoleret, så engine senere kan flyttes til separat proces via lokal IPC uden at bryde API'et.

Domænemoduler

• app.auth: brugere, sessions og tokens.
• app.core: konfiguration, database, logging og lifecycle.
• app.dmx: frame model, merge-regler, simulator og OLA-adapter.
• app.fixtures: OFL-klient, normalisering og import.
• app.scenes: scene- og layerservice.
• app.effects: built-in effekter, sikkerhedsregler og runtime-stack.
• app.bpm: manual/tap/audio-abstraktion og beatbus.
• app.mixitup: mappings, kø, cooldowns og idempotency.
• app.telemetry: systemstatus, hændelser og historik.
• app.websocket: live snapshots og reconnect-venlige payloads.

Frame og merge

• Et universe er 512 kanaler med værdier 0..255.
• HTP bruges til intensitetskanaler og andre udtrykkeligt HTP-markerede kanaler.
• LTP bruges til bevægelse, farve, wheels og fallback-kanaler uden kendt HTP-behov.
• Blackout har absolut prioritet og nulstiller output uden at slette underliggende scene/effect-state.
• Freeze stopper opdateringer til target frame, men bevarer seneste output.

Telemetri

Telemetri skelner eksplicit mellem:

• beregnet frame,
• frame afleveret til backend,
• og fysisk verifikation.

Release 1.0 leverer kun software- og backendniveau. Dokumentation og UI siger tydeligt, at fysisk signal ikke er verificeret uden ekstern måling eller understøttet RX/RDM.

Simulator-first

Simulatoren er førsteklasses backend:

• samme frame-interface som OLA,
• fejlindsprøjtning,
• framehistorik,
• heatmap-venlig output,
• assertions i automatiske tests,
• og visuel brug i UI.

Uafklarede, men forberedte områder

• Flere universer ligger i datamodel og API, men UI fokuserer på universe 1.
• Audio-BPM bruger en adapterstruktur, så lokale Linux-audioinputs kan bruges i drift, mens tests benytter syntetiske click tracks.
• Art-Net, sACN, MIDI Clock og OSC er ikke aktive i 1.0, men backendinterfacet er forberedt til dem.