# 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.