76 lines
3.3 KiB
Markdown
76 lines
3.3 KiB
Markdown
# 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.
|