Add documentation, manual and screenshots preview

ARCHITECTURE.md

@@ -0,0 +1,75 @@
+# 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.

HARDWARE-VALIDATION.md

@@ -0,0 +1,103 @@
+# Hardware Validation
+
+All rights reserved - Thomas / TuxiNet
+
+Target-platformen er en fysisk Debian 13 amd64-maskine. USB-DMX og OLA-output er allerede verificeret af systemejeren på den nuværende host. Codex har ikke selv udført fysisk hardwaretest eller ekstern signalmåling i denne workspace-session. Brug denne checkliste til gentest, ændringsvalidering og installationer på andre hosts.
+
+## 1. Kør diagnostics
+
+- Kommando: `scripts/collect-diagnostics.sh`
+- Forventet resultat: bundle oprettes uden secrets.
+- Fejlsøgning: kontroller skrivbar `data/diagnostics` og læserettigheder til logs.
+
+## 2. Kontrollér OLA
+
+- Kommando: `systemctl status olad`
+- Forventet resultat: `active (running)`.
+- Fejlsøgning: verificér OLA-pakke og pluginvalg.
+
+## 3. Tilslut USB-DMX
+
+- Forventet resultat: device ses i `lsusb` og i TuxDMX DMX-status.
+- Fejlsøgning: kontroller kabel, strøm og pluginunderstøttelse.
+
+## 4. Identificér device
+
+- Forventet resultat: vendor/product ID eller device path vises.
+- Fejlsøgning: kontrollér rettigheder til `/dev/ttyUSB*`.
+
+## 5. Patch port
+
+- Handling: vælg universe 1 og korrekt OLA-port i UI.
+- Forventet resultat: binding gemmes uden fejl.
+- Fejlsøgning: genstart `olad`, opdater device scan.
+
+## 6. Tilslut én simpel lampe
+
+- Forventet resultat: lampen er alene på DMX-linjen under første test.
+- Fejlsøgning: kontrol af terminering og kabling.
+
+## 7. Sæt lampens DMX address
+
+- Forventet resultat: lampen matcher patchstartadresse.
+- Fejlsøgning: verificér personligheds/mode-kanalantal.
+
+## 8. Test dimmer
+
+- Handling: brug kanaltest 20 % og 100 %.
+- Forventet resultat: lampen følger niveauerne og nulstilles efter timer.
+- Fejlsøgning: kontroller dimmerkanal i korrekt mode.
+
+## 9. Test RGB
+
+- Handling: aktivér en simpel farvescene.
+- Forventet resultat: farver matcher sceneværdier.
+- Fejlsøgning: tjek kanalrækkefølge og fixturemode.
+
+## 10. Test blackout
+
+- Handling: aktivér blackout.
+- Forventet resultat: output går til nul straks.
+- Fejlsøgning: kontroller prioritetslag og master-limit.
+
+## 11. Test reconnect
+
+- Handling: træk USB-DMX ud og tilslut igen.
+- Forventet resultat: UI går til degraded mode og reconnecter uden tilfældig flash.
+- Fejlsøgning: kontroller OLA-device refresh og log for reconnect count.
+
+## 12. Test scene
+
+- Handling: aktivér base-scene og en overlay-scene.
+- Forventet resultat: merge og return-to-base virker.
+- Fejlsøgning: tjek HTP/LTP-precedence og prioritet.
+
+## 13. Test MixItUp
+
+- Handling: send testtrigger via Web Request Action.
+- Forventet resultat: HTTP 202 og effekt i kø/log.
+- Fejlsøgning: verificér token, header og rate limits.
+
+## 14. Test BPM
+
+- Handling: tilslut lydinput eller syntetisk click track.
+- Forventet resultat: BPM, confidence og beatindikator opdateres.
+- Fejlsøgning: kontroller devicevalg, inputkanal og audioadapter.
+
+## 15. Test reboot/autostart
+
+- Handling: genstart værtsmaskinen.
+- Forventet resultat: OLA og TuxDMX starter automatisk, safe scene aktiveres.
+- Fejlsøgning: inspicér systemd-status og journald.
+
+## 16. Kør 2 timers soak test
+
+- Handling: hold UI åbent med scener, BPM og triggers aktive.
+- Forventet resultat: ingen memory leak, ingen ukontrollerede dropped frames.
+- Fejlsøgning: brug telemetri, temperatur og diagnostics bundle.
+
+## 17. Gem diagnostic bundle
+
+- Handling: kør diagnostics igen efter testen.
+- Forventet resultat: komplet bundle vedlagt til videre fejlsøgning.
+- Fejlsøgning: redigeringsfejl i config eller manglende læserettigheder.

INSTALL-LINUX.md

@@ -0,0 +1,159 @@
+# Installation på Debian 13 amd64
+
+All rights reserved - Thomas / TuxiNet
+
+## Platform
+
+- Debian 13 amd64
+- `systemd`
+- OLA / `olad`
+- Node.js 20
+- `pnpm` 10.28.2
+- Standardport for TuxDMX: `8000/tcp`
+
+## 1. Forbered serveren
+
+```bash
+sudo apt-get update
+sudo apt-get install -y git curl
+git clone <privat-repo-url> tuxdmx
+cd tuxdmx
+```
+
+Hvis du deployer fra et ZIP-arkiv, saa udpak arkivet og skift til den mappe, foer du fortsaetter.
+
+## 2. Kildeplacering
+
+- Installeren finder repositoryet ud fra scriptets egen placering.
+- Det virker baade ved Git-clone og ved SFTP-kopieret projektmappe.
+- `sudo` maa ikke flytte source root til `/root`, fordi scriptet ikke bruger `$HOME` som kilde.
+
+## 3. Installer TuxDMX
+
+Interaktiv installation:
+
+```bash
+sudo ./scripts/install-linux.sh
+```
+
+Ikke-interaktiv installation:
+
+```bash
+sudo ./scripts/install-linux.sh --non-interactive --force
+```
+
+Hvis du allerede har en gyldig `frontend/dist`, kan du eksplicit springe frontend-build over:
+
+```bash
+sudo ./scripts/install-linux.sh --non-interactive --force --skip-frontend-build
+```
+
+Dette flag virker kun, hvis `frontend/dist/index.html` allerede findes.
+
+Scriptet:
+
+- validerer Debian 13 amd64,
+- installerer Python 3, `python3-venv`, SQLite, OLA, OLA Python-binding, Node.js 20-værktøjskæde og `olad`,
+- laaser frontend-tooling til `pnpm` 10.28.2,
+- bygger frontenden selv med `pnpm install --frozen-lockfile` og `pnpm build`,
+- opretter systembrugeren `tuxdmx`,
+- opretter `/opt/tuxdmx`, `/var/lib/tuxdmx`, `/var/log/tuxdmx` og `/etc/tuxdmx`,
+- bruger staging i `/opt/tuxdmx.new`,
+- normaliserer filrettigheder efter kopiering, ogsaa efter SFTP-upload,
+- opretter virtualenv med `--system-site-packages`,
+- installerer `requirements.lock`, koerer `pip check` og kontrollerer `greenlet`, `sqlalchemy` og `ola`,
+- koerer alle Alembic migrations som brugeren `tuxdmx`,
+- installerer og aktiverer `tuxdmx.service`,
+- health-checker `http://127.0.0.1:8000/api/v1/health`,
+- viser automatisk `systemctl status` og `journalctl`, hvis service-start fejler.
+
+Eksisterende database og konfiguration bevares, fordi de ligger i `/var/lib/tuxdmx` og `/etc/tuxdmx`.
+
+## 4. Permanente stier
+
+- Appkode: `/opt/tuxdmx`
+- Frontend build: `/opt/tuxdmx/frontend/dist`
+- Database og runtime-data: `/var/lib/tuxdmx`
+- Backups: `/var/lib/tuxdmx/backups`
+- Diagnostics: `/var/lib/tuxdmx/diagnostics`
+- Uploads: `/var/lib/tuxdmx/uploads`
+- Fixture-cache: `/var/lib/tuxdmx/fixtures`
+- Logs: `/var/log/tuxdmx`
+- Environment: `/etc/tuxdmx/tuxdmx.env`
+
+## 5. Kontroller drift
+
+```bash
+systemctl status tuxdmx.service
+systemctl status olad
+curl -fsS http://127.0.0.1:8000/api/v1/health
+curl -fsS http://127.0.0.1:8000/
+```
+
+Web UI:
+
+```text
+http://<server-ip>:8000/
+```
+
+## 6. Update
+
+```bash
+sudo ./scripts/update-linux.sh
+```
+
+Med eksisterende `frontend/dist`:
+
+```bash
+sudo ./scripts/update-linux.sh --skip-frontend-build
+```
+
+Update-scriptet:
+
+- tager backup af app, data og konfiguration,
+- bygger ny frontend eller genbruger eksisterende `dist`,
+- kopierer ny kode og `frontend/dist`,
+- geninstallerer Python-afhaengigheder,
+- koerer migrationer,
+- geninstallerer `tuxdmx.service`,
+- genstarter `olad` og `tuxdmx.service`,
+- ruller tilbage ved fejl.
+
+## 7. Uninstall
+
+```bash
+sudo ./scripts/uninstall-linux.sh
+sudo ./scripts/uninstall-linux.sh --purge-app
+sudo ./scripts/uninstall-linux.sh --purge-app --purge-data
+```
+
+## 8. Logs og health checks
+
+```bash
+journalctl -u tuxdmx.service -f
+journalctl -u olad -f
+systemctl status tuxdmx.service --no-pager --full
+curl -fsS http://127.0.0.1:8000/api/v1/health
+```
+
+- Health fejler: `journalctl -u tuxdmx.service -n 200 --no-pager`
+- OLA-binding mangler: kontroller at `python3-ola` eller `ola-python` findes i Debian-repositoriet
+- OLA-runtime fejler: `journalctl -u olad -n 200`
+- DB-fejl: `sqlite3 /var/lib/tuxdmx/tuxdmx.db "PRAGMA integrity_check;"`
+- Frontend-build fejler: kontroller `node --version`, `pnpm --version` og `package.json` packageManager-feltet
+- Importfejl `No module named 'app'`: kontrollér at `/opt/tuxdmx/backend/app/main.py` findes
+- Permission-fejl efter SFTP: installeren normaliserer rettigheder til `root:tuxdmx`, 0755 paa mapper og 0644 paa kode/dist-filer
+
+## 9. Root causes rettet i denne leverance
+
+- `greenlet` manglede i Python-lockfile, selv om SQLAlchemy async-laget kraever det
+- frontend-build var manuel i stedet for en del af installeren
+- pnpm-version var ikke fastlaast og kunne glide til en inkompatibel udgave
+- backend-layoutet i `/opt/tuxdmx` blev ikke verificeret eksplicit
+- relative runtime-stier gav `PermissionError` og uforudsigelig working directory-adfaerd
+- SFTP-overfoerte rettigheder blev kopieret ukritisk
+- systemd health-check viste ikke automatisk de egentlige servicefejl
+
+## 10. Hardwarestatus
+
+Installationsscriptet er lavet til Debian 13 amd64. USB-DMX og OLA-output er verificeret af systemejeren på den fysiske target-host, men Codex har ikke selv udført fysisk hardwaretest i denne workspace-session. Brug [HARDWARE-VALIDATION.md](HARDWARE-VALIDATION.md) til gentest, ændringsvalidering og nye installationer.

INSTALL-PI.md

@@ -0,0 +1,142 @@
+# Installation på Raspberry Pi
+
+All rights reserved - Thomas / TuxiNet
+
+Debian 13 amd64 bruger nu [INSTALL-LINUX.md](INSTALL-LINUX.md) samt `scripts/install-linux.sh` og `scripts/update-linux.sh`.
+
+## Platform
+
+- Raspberry Pi 4 eller 5
+- Raspberry Pi OS Lite 64-bit
+- OLA/`olad`
+- Valgfrit USB audio input til BPM
+- Standardport for TuxDMX: `8000/tcp`
+
+## 1. Forbered Pi
+
+```bash
+sudo apt-get update
+sudo apt-get install -y git curl
+git clone <privat-repo-url> tuxdmx
+cd tuxdmx
+```
+
+Hvis du deployer fra et ZIP-arkiv i stedet for Git, så udpak til en mappe og skift til den mappe før næste trin.
+
+## 2. Byg frontend før Pi-installation
+
+Kør dette på buildmaskinen eller direkte på Pi, før `install-pi.sh`:
+
+```bash
+pnpm install
+pnpm build
+```
+
+Installationsscriptet kræver, at `frontend/dist/index.html` findes.
+
+## 3. Installer TuxDMX
+
+Interaktiv installation:
+
+```bash
+sudo ./scripts/install-pi.sh
+```
+
+Ikke-interaktiv installation:
+
+```bash
+sudo ./scripts/install-pi.sh --non-interactive --force
+```
+
+Scriptet:
+
+- installerer systempakker,
+- opretter systembrugeren `tuxdmx`,
+- opretter `/opt/tuxdmx`, `/var/lib/tuxdmx`, `/var/log/tuxdmx` og `/etc/tuxdmx`,
+- genererer `/etc/tuxdmx/tuxdmx.env`,
+- installerer Python-afhængigheder,
+- kører Alembic migration,
+- installerer og starter `tuxdmx.service`.
+
+## 4. Kontroller service og URL
+
+```bash
+systemctl status tuxdmx.service
+systemctl status olad
+curl -fsS http://127.0.0.1:8000/api/v1/health
+```
+
+Web UI:
+
+```text
+http://<pi-ip>:8000/
+```
+
+## 5. Førstegangsopsætning
+
+1. Åbn Web UI.
+2. Opret administrator.
+3. Kontroller systemstatus og OLA-status.
+4. Vælg universe 1 og korrekt OLA-port.
+5. Sæt master-limit, blackout-adfærd og strobegrænser.
+6. Generér MixItUp-token ved behov.
+7. Gem safe scene.
+
+## 6. Logs og drift
+
+Følg applikationslog:
+
+```bash
+journalctl -u tuxdmx.service -f
+```
+
+Se OLA-log:
+
+```bash
+journalctl -u olad -f
+```
+
+Genstart TuxDMX:
+
+```bash
+sudo systemctl restart tuxdmx.service
+```
+
+## 7. Update
+
+```bash
+sudo ./scripts/update-pi.sh
+```
+
+Update-scriptet tager backup, kopierer ny version, installerer requirements, koerer migration og health check. Ved fejl rulles app-, data- og konfigurationstilstand tilbage.
+
+## 8. Uninstall
+
+Fjern kun service:
+
+```bash
+sudo ./scripts/uninstall-pi.sh
+```
+
+Fjern service og app:
+
+```bash
+sudo ./scripts/uninstall-pi.sh --purge-app
+```
+
+Fjern service, app og data:
+
+```bash
+sudo ./scripts/uninstall-pi.sh --purge-app --purge-data
+```
+
+## 9. Fejlsøgning
+
+- Health fejler: se `journalctl -u tuxdmx.service -n 200`
+- OLA utilgængelig: se `journalctl -u olad -n 200`
+- USB-DMX ikke fundet: brug `lsusb`, `dmesg | grep -i usb` og [HARDWARE-VALIDATION.md](HARDWARE-VALIDATION.md)
+- Databasefejl: kontrollér `/var/lib/tuxdmx/tuxdmx.db` og `sqlite3 /var/lib/tuxdmx/tuxdmx.db "PRAGMA integrity_check;"`
+
+## 10. Ikke fysisk testet af Codex
+
+Denne repository leverer scripts og dokumentation til Pi, men ingen fysisk Raspberry Pi-, OLA- eller USB-DMX-hardware er testet i denne desktop-session. Brug altid [HARDWARE-VALIDATION.md](HARDWARE-VALIDATION.md) efter installation.

README.md

@@ -0,0 +1,173 @@
+# TuxDMX
+
+All rights reserved - Thomas / TuxiNet
+
+TuxDMX er en headless, browserbaseret DMX-controller med FastAPI-backend, React dark UI, simulator-first udvikling og hardwareabstraktion mod OLA/USB-DMX.
+
+## Status
+
+- Simulator mode kan startes lokalt og bruges til backend-, UI- og API-verifikation uden fysisk hardware.
+- Primær target-platform er fysisk Debian 13 amd64.
+- USB-DMX og OLA-output er verificeret af systemejeren på target-hosten.
+- Codex påstår ikke, at den fysiske hardware er målt eller testet direkte i denne workspace-session.
+- Resten af den manuelle hardwarevalidering og regressionstest er samlet i [HARDWARE-VALIDATION.md](HARDWARE-VALIDATION.md).
+
+## Hurtig simulatorstart
+
+### Backend
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -r requirements.lock
+python -m uvicorn app.main:app --app-dir backend --reload
+```
+
+Windows PowerShell:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -r requirements.lock
+python -m uvicorn app.main:app --app-dir backend --reload
+```
+
+### Frontend
+
+```bash
+pnpm install
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm dev
+```
+
+### Standard-URL'er
+
+- Web UI: `http://127.0.0.1:8000/` når backend serverer `frontend/dist`
+- API health: `http://127.0.0.1:8000/api/v1/health`
+- Live WebSocket: `ws://127.0.0.1:8000/ws/live`
+
+## Verifikation
+
+- Backend-tests: `pytest`
+- Frontend-tests: `pnpm test`
+- Frontend linting: `pnpm lint`
+- TypeScript typecheck: `pnpm typecheck`
+- Frontend production build: `pnpm build`
+- Python lint/typecheck: `ruff check backend` og `mypy backend/app`
+
+## Dokumentation
+
+- [ARCHITECTURE.md](ARCHITECTURE.md)
+- [INSTALL-LINUX.md](INSTALL-LINUX.md)
+- [INSTALL-PI.md](INSTALL-PI.md)
+- [HARDWARE-VALIDATION.md](HARDWARE-VALIDATION.md)
+- [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+- [SECURITY.md](SECURITY.md)
+- [docs/API-ENDPOINTS.md](docs/API-ENDPOINTS.md)
+- [docs/MIXITUP.md](docs/MIXITUP.md)
+- [docs/OFL.md](docs/OFL.md)
+- [docs/BPM.md](docs/BPM.md)
+- [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md)
+- [docs/IMPLEMENTATION-STATUS.md](docs/IMPLEMENTATION-STATUS.md)
+
+## Repositoryoversigt
+
+- `backend/`: FastAPI, simulator, DMX-engine, auth, fixtures, BPM, triggers, backups og tests.
+- `frontend/`: React dark UI, sidekomponenter og frontend-tests.
+- `scripts/`: Linux/Pi-installation, update, uninstall, smoke-test og diagnostics.
+- `systemd/`: systemd-unit og environment-eksempel til Linux-drift.
+- `test-data/fixtures/`: små lovlige fixtures til simulator- og OFL-tests.
+
+## Produktion på Linux
+
+- Debian 13 amd64: `sudo ./scripts/install-linux.sh`, `sudo ./scripts/update-linux.sh` og `sudo ./scripts/uninstall-linux.sh`
+- Raspberry Pi / ARM: `sudo ./scripts/install-pi.sh` og `sudo ./scripts/update-pi.sh`
+
+## Windows sync til Linux-share
+
+Hvis du arbejder i Windows og vil kopiere den deploy-klare kode til et mounted share som `Q:\home\thomas\TuxDMXWebUI`, kan du bruge:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\sync-windows-deploy.ps1
+```
+
+Alternativt:
+
+```cmd
+scripts\sync-windows-deploy.cmd
+```
+
+Scriptet kopierer projektet uden `data`, `node_modules`, `.venv`, cache-mapper, `__pycache__` og git-metadata. Det sletter ikke noget paa destinationen. Brug `-DryRun` for at se, hvad der vil blive kopieret, eller `-DestinationRoot <sti>` for at pege paa en anden mappe.
+
+Hvis sharet ikke tillader overwrite af enkelte filer, kan du bygge en lokal update-pakke i stedet:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\sync-windows-deploy.ps1 -PackageOnly
+```
+
+Standard-stien for pakken er `Desktop\TuxDMXWebUI-update`, og den kan aendres med `-StageRoot <sti>`.
+
+## Produktionsnoter
+
+- Debian 13 amd64 er nu førsteborger-platform for Linux-installation.
+- Den nuværende produktionsmaskine er en fysisk Debian 13 amd64-host.
+- Frontend-tooling er fastlaast til Node 20 og `pnpm` 10.28.2 via `packageManager` og `engines`.
+- OLA og OLA Python-binding forventes fra Debian-pakker, og virtualenv oprettes med `--system-site-packages`.
+- Permanente data ligger under `/var/lib/tuxdmx`, logs under `/var/log/tuxdmx` og environment i `/etc/tuxdmx/tuxdmx.env`.
+
+## Home Assistant live-test
+
+Denne sektion beskriver en konkret live-testopsætning for parallel drift med fysisk USB-DMX og Home Assistant. Den er en testopskrift og ikke en påstand om, at den er udført direkte fra denne Codex-workspace-session.
+
+### Mål
+
+- `Universe 1`: fysisk OLA-output til USB-DMX og almindelige DMX-lamper
+- `Universe 10`: internt HA-universe til Home Assistant-bro
+
+### Testsetup
+
+1. Sæt DMX-backend til `OLA / USB-DMX`, `Universe 1` og korrekt OLA-port i `Settings`.
+2. Under `Home Assistant-bro`:
+   - sæt `Base URL`
+   - indsæt long-lived token
+   - sæt `Standard HA-universe` til `10`
+   - tryk `Test forbindelse`
+3. Tryk `Hent HA-enheder` og vælg de relevante entiteter.
+
+### Konkrete mappings
+
+- RGB med master:
+  - `Universe 10`
+  - `Startadresse 1`
+  - `Fixturetype rgb`
+  - `Entity light.bar_rgb`
+  - `Master dimmer = ja`
+  - Kanalbrug:
+    - `1 = master`
+    - `2 = rød`
+    - `3 = grøn`
+    - `4 = blå`
+
+- Dimmer:
+  - `Universe 10`
+  - `Startadresse 5`
+  - `Fixturetype dimmer`
+  - `Entity light.bar_dimmer`
+
+- Scene-trigger:
+  - `Universe 10`
+  - `Startadresse 6`
+  - `Fixturetype scene`
+  - `Entity scene.party_mode`
+
+### Forventet adfærd
+
+- DMX på `Universe 1` går fortsat ud via OLA og USB-DMX uden afhængighed af Home Assistant.
+- HA-mappings på `Universe 10` oversætter kun de valgte kanaler til HA-kald.
+- `Scene` og `automation` trigges kun på rising edge.
+- `Switch` bruger hysterese og må ikke flappe omkring midtpunktet.
+- Ved langsomt eller utilgængeligt HA droppes gamle pending opdateringer, så kun nyeste ønskede værdi sendes videre.
+- `Fade` sendes som HA `transition` frem for mange mellemtrin.

SECURITY.md

@@ -0,0 +1,36 @@
+# Security
+
+All rights reserved - Thomas / TuxiNet
+
+## LAN deployment
+
+- Drift antages som udgangspunkt på isoleret LAN eller bag reverse proxy.
+- Eksponér ikke adminadgang uden netværkskontrol og HTTPS.
+
+## Credentials
+
+- Ingen standard adminpassword.
+- Brug Argon2 til passwordhash.
+- Sessions og API-tokens skal kunne roteres og tilbagekaldes.
+
+## Reverse proxy og HTTPS
+
+- Reverse proxy er anbefalet ved adgang uden for lokalt netværk.
+- Brug TLS-terminering, IP-filtrering og stærke cookies i produktion.
+
+## Secrets
+
+- Commit aldrig secrets.
+- Brug `.env` eller systemd environment-fil på Pi.
+- Diagnostics bundle må ikke indeholde rå tokens eller passwordhashes.
+
+## Backup
+
+- Krypter backup uden for enheden, hvis den forlader lokal drift.
+- Restore kræver administratorvalidering.
+
+## Reporting
+
+- Brug auditlog og diagnostics bundle til hændelsesanalyse.
+- Fysisk DMX-verifikation er separat fra softwaretelemetri.
+

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,12 @@
+# Third Party Notices
+
+All rights reserved - Thomas / TuxiNet
+
+Dette projekt bruger eller er designet til at arbejde sammen med tredjepartskomponenter, herunder:
+
+- Python: FastAPI, Pydantic, SQLAlchemy, Alembic, Argon2, httpx, psutil, uvicorn.
+- Frontend: React, Vite, TypeScript, ESLint, Vitest, Testing Library.
+- Hardware/software integration: Open Lighting Architecture (OLA).
+- Fixture metadata: Open Fixture Library (OFL).
+
+Repository indeholder kun små, reducerede testfixtures i `test-data/fixtures` skrevet særskilt til intern test. De er ikke kopier af tredjeparts kodebaser og er kun beregnet som lovlige testdata til normalisering og simulator.

TROUBLESHOOTING.md

@@ -0,0 +1,74 @@
+# Troubleshooting
+
+All rights reserved - Thomas / TuxiNet
+
+## OLA kan ikke se USB
+
+- Bekræft `lsusb`, `systemctl status olad` og at korrekt OLA-plugin er aktivt.
+- Genstart OLA før du genpatcher porten i UI.
+
+## Permission denied på `/dev/ttyUSB*`
+
+- Sørg for at `tuxdmx` er medlem af `dialout` og `plugdev`.
+- Bekræft udev-rettigheder eller device-ejerskab.
+
+## Ingen DMX-output
+
+- Bekræft universe, port og fixtureaddress.
+- Kontroller, at blackout ikke er aktiv.
+- Se DMX monitor for current/target/source.
+
+## Flimren
+
+- Reducér frame rate til 25 eller 30 fps.
+- Kontroller at ingen overliggende effekt skriver LTP/HTP utilsigtet.
+
+## Web UI virker ikke
+
+- Kontroller `tuxdmx.service`.
+- Brug `/api/v1/health` og se browser-konsol for WebSocket-fejl.
+- Kør `systemctl status tuxdmx.service --no-pager --full`.
+- Kør `journalctl -u tuxdmx.service -n 200 --no-pager`.
+
+## Frontend-build eller pnpm fejler
+
+- Kontroller `node --version` og bekræft Node 20.
+- Kontroller `pnpm --version` og bekræft `10.28.2`.
+- Kontroller at `package.json` har `packageManager: pnpm@10.28.2`.
+- Hvis build skal genbruges fra en CI-artefakt, brug `--skip-frontend-build` kun naar `frontend/dist/index.html` allerede findes.
+
+## No module named `app`
+
+- Kontroller at backend er landet som `/opt/tuxdmx/backend/app`.
+- Kontroller `test -f /opt/tuxdmx/backend/app/main.py`.
+- Kør importtesten som servicebrugeren:
+  `sudo -u tuxdmx /opt/tuxdmx/.venv/bin/python -c "import sys; sys.path.insert(0, '/opt/tuxdmx/backend'); import app.main"`
+
+## PermissionError på `frontend/dist` eller `data/backups`
+
+- Installeren normaliserer rettigheder til `root:tuxdmx` for appkode og `tuxdmx:tuxdmx` for runtime-data.
+- Kontroller `sudo -u tuxdmx test -r /opt/tuxdmx/frontend/dist/index.html`.
+- Kontroller `namei -l /opt/tuxdmx/frontend/dist/index.html`.
+
+## MixItUp timeout
+
+- Bekræft at endpointet returnerer `202 Accepted`.
+- Kontroller rate limiting, token og netværksrute.
+
+## BPM finder forkert tempo
+
+- Justér BPM-range og half/double.
+- Brug syntetiske click tracks for at isolere lydinputproblemer.
+
+## Databasefejl
+
+- Kontroller diskplads og SQLite WAL-filer.
+- Kør backup før restore eller manuel reparation.
+- Kontroller at `tuxdmx` kan skrive til `/var/lib/tuxdmx`.
+- Kontroller `sqlite3 /var/lib/tuxdmx/tuxdmx.db "PRAGMA integrity_check;"`.
+
+## OLA kan ikke importeres i virtualenv
+
+- Virtualenv skal oprettes med `python3 -m venv --system-site-packages /opt/tuxdmx/.venv`.
+- Kontroller:
+  `sudo -u tuxdmx /opt/tuxdmx/.venv/bin/python -c "import ola; print(ola.__file__)"`

docs/API-ENDPOINTS.md

@@ -0,0 +1,65 @@
+# API endpoints
+
+Roller nedenfor er den tilsigtede adgangsrolle for Release 1.0. Den nuværende kodebase dokumenterer rollerne, men håndhæver dem endnu ikke konsekvent i runtime.
+
+| Metode | Sti | Rolle | Formål |
+| --- | --- | --- | --- |
+| `GET` | `/api/v1/health` | Read only | Health check til lokal drift og monitoring. |
+| `GET` | `/api/v1/system/status` | Read only | Samlet systemstatus med engine, telemetri og BPM. |
+| `GET` | `/api/v1/system/diagnostics` | Administrator | Udvidet diagnostik til support og bundle. |
+| `POST` | `/api/v1/system/restart-service` | Administrator | Planlægger restart af TuxDMX-servicen på Linux-værten. |
+| `GET` | `/api/v1/dmx/status` | Read only | DMX-engine status og backendforbindelse. |
+| `GET` | `/api/v1/dmx/devices` | Operator | Liste over tilgængelige DMX-backends/devices. |
+| `GET` | `/api/v1/dmx/universes` | Operator | Oversigt over univers-konfiguration. |
+| `GET` | `/api/v1/dmx/frame` | Read only | Aktuelt DMX-frame og source-map. |
+| `POST` | `/api/v1/dmx/test-channel` | Operator | Midlertidig kanaltest til setup/diagnostik. |
+| `POST` | `/api/v1/dmx/blackout` | Operator | Aktiverer blackout med højeste prioritet. |
+| `POST` | `/api/v1/dmx/release-blackout` | Operator | Frigiver blackout. |
+| `GET` | `/api/v1/fixtures` | Operator | Lister lokalt importerede fixtures. |
+| `POST` | `/api/v1/fixtures/search-ofl` | Operator | Søger fixtures via OFL eller lokal fallback. |
+| `POST` | `/api/v1/fixtures/preview-ofl` | Operator | Henter preview og normaliseret modeoversigt før import. |
+| `POST` | `/api/v1/fixtures/import-ofl` | Operator | Importerer fixture fra OFL til lokal cache/runtime. |
+| `POST` | `/api/v1/fixtures/import-file` | Operator | Importerer fixture fra lokal/custom payload. |
+| `POST` | `/api/v1/fixtures/custom` | Operator | Opretter custom fixture uden OFL. |
+| `GET` | `/api/v1/fixtures/{id}` | Operator | Henter ét lokalt fixture. |
+| `PUT` | `/api/v1/fixtures/{id}` | Operator | Opdaterer et lokalt fixture. |
+| `DELETE` | `/api/v1/fixtures/{id}` | Administrator | Sletter et lokalt fixture. |
+| `GET` | `/api/v1/patch` | Operator | Lister patch-entries. |
+| `POST` | `/api/v1/patch` | Operator | Opretter patch-entry. |
+| `PUT` | `/api/v1/patch/{id}` | Operator | Opdaterer patch-entry. |
+| `DELETE` | `/api/v1/patch/{id}` | Operator | Sletter patch-entry. |
+| `POST` | `/api/v1/patch/validate` | Operator | Validerer startadresse og kanalantal. |
+| `GET` | `/api/v1/scenes` | Operator | Lister scener. |
+| `POST` | `/api/v1/scenes` | Operator | Opretter scene. |
+| `GET` | `/api/v1/scenes/{id}` | Operator | Henter scene. |
+| `PUT` | `/api/v1/scenes/{id}` | Operator | Opdaterer scene. |
+| `DELETE` | `/api/v1/scenes/{id}` | Operator | Sletter scene. |
+| `POST` | `/api/v1/scenes/{slug}/activate` | Operator | Aktiverer scene på engine-stacken. |
+| `POST` | `/api/v1/scenes/{slug}/release` | Operator | Frigiver scene-layer. |
+| `GET` | `/api/v1/effects` | Operator | Lister effekter. |
+| `POST` | `/api/v1/effects` | Operator | Opretter effekt. |
+| `PUT` | `/api/v1/effects/{id}` | Operator | Opdaterer effekt. |
+| `DELETE` | `/api/v1/effects/{id}` | Operator | Sletter effekt. |
+| `POST` | `/api/v1/effects/{slug}/trigger` | Operator | Trigger effekt på engine-stacken. |
+| `POST` | `/api/v1/effects/{slug}/stop` | Operator | Stopper aktiv effekt. |
+| `GET` | `/api/v1/bpm/status` | Read only | Aktuel BPM-status, mode og confidence. |
+| `POST` | `/api/v1/bpm/manual` | Operator | Sætter manuel BPM. |
+| `POST` | `/api/v1/bpm/tap` | Operator | Registrerer tap-tempo. |
+| `POST` | `/api/v1/bpm/audio/start` | Operator | Starter audioanalyse mod valgt ALSA- eller syntetisk inputdevice. |
+| `POST` | `/api/v1/bpm/audio/stop` | Operator | Stopper audio-mode. |
+| `POST` | `/api/v1/bpm/external` | Operator | Sætter BPM fra ekstern kilde/API. |
+| `GET` | `/api/v1/bpm/devices` | Operator | Lister tilgængelige BPM-devices/kilder. |
+| `GET` | `/api/v1/integrations/mixitup` | Administrator | Lister MixItUp-integrationer. |
+| `POST` | `/api/v1/integrations/mixitup` | Administrator | Opretter MixItUp-integration. |
+| `PUT` | `/api/v1/integrations/mixitup/{id}` | Administrator | Opdaterer MixItUp-integration. |
+| `DELETE` | `/api/v1/integrations/mixitup/{id}` | Administrator | Sletter MixItUp-integration. |
+| `POST` | `/api/v1/integrations/mixitup/{id}/test` | Administrator | Tester MixItUp-integration. |
+| `POST` | `/api/v1/triggers/{slug}` | API token | Hurtigt triggerendpoint til MixItUp/Twitch. |
+| `GET` | `/api/v1/telemetry/live` | Read only | Aktuel telemetri. |
+| `GET` | `/api/v1/telemetry/history` | Read only | Historiske samples. |
+| `GET` | `/api/v1/events` | Read only | Nylige systemevents. |
+| `GET` | `/api/v1/logs` | Administrator | Hændelser/logfeed. |
+| `POST` | `/api/v1/backups` | Administrator | Opretter ZIP-backup i simulator/runtime. |
+| `GET` | `/api/v1/backups` | Administrator | Lister tilgængelige backups. |
+| `POST` | `/api/v1/backups/{id}/restore` | Administrator | Gendanner backup og opretter pre-restore backup. |
+| `DELETE` | `/api/v1/backups/{id}` | Administrator | Sletter backuparkiv. |

docs/BPM.md

@@ -0,0 +1,37 @@
+# BPM-kilder
+
+## Manual
+
+- Endpoint: `POST /api/v1/bpm/manual?bpm=<tal>`
+- UI: knapper og direkte værdisætning
+- Status: fuldt implementeret i simulator/runtime
+
+## Tap
+
+- Endpoint: `POST /api/v1/bpm/tap`
+- UI: `Tap tempo`
+- Algoritme: median af de seneste tap-intervaller inden for et kort vindue
+- Status: implementeret og verificerbar lokalt
+
+## Audio input
+
+- Endpoints:
+  - `POST /api/v1/bpm/audio/start?device=<navn>`
+  - `POST /api/v1/bpm/audio/stop`
+  - `GET /api/v1/bpm/devices`
+- Devices i denne leverance:
+  - `synthetic-click-track`
+  - `jack:auto`
+  - `alsa:default`
+- Status: simuleret/delvist implementeret. API og UI findes, men ægte audioanalyse mod aubio/JACK/ALSA er ikke implementeret endnu i denne kodebase.
+
+## External
+
+- Endpoint: `POST /api/v1/bpm/external?bpm=<tal>`
+- Status: implementeret som simpel ekstern BPM-injektion
+
+## Verifikation uden hardware
+
+- Manual og tap kan verificeres direkte i UI eller via API.
+- Audio-mode kan verificeres som simulator-flow og device-API, men ikke som ægte beat detection uden videre implementation.
+

docs/DEPENDENCIES.md

@@ -0,0 +1,54 @@
+# Dependencies og licenser
+
+Denne oversigt dækker de deklarerede direkte afhængigheder i repositoryet samt de eksterne platformskomponenter, som systemet integrerer med.
+
+## Python
+
+| Pakke | Version | Licensfelt | Formål |
+| --- | --- | --- | --- |
+| `alembic` | `1.14.0` | `MIT` | Database migrations |
+| `aiosqlite` | `0.20.0` | `ikke deklareret i metadata` | Async SQLite-driver |
+| `argon2-cffi` | `23.1.0` | `ikke deklareret i metadata` | Password hashing |
+| `fastapi` | `0.115.6` | `ikke deklareret i metadata` | REST API og WebSocket-app |
+| `httpx` | `0.28.1` | `BSD-3-Clause` | OFL HTTP-klient |
+| `pydantic` | `2.10.4` | `ikke deklareret i metadata` | Datavalidering |
+| `pydantic-settings` | `2.7.0` | `MIT` | Settings fra env |
+| `psutil` | `6.1.1` | `BSD-3-Clause` | Systemtelemetri |
+| `python-multipart` | `0.0.20` | `ikke deklareret i metadata` | Multipart/form parsing |
+| `sqlalchemy` | `2.0.36` | `MIT` | ORM og DB-lag |
+| `uvicorn` | `0.34.0` | `BSD-3-Clause` | ASGI-server |
+| `mypy` | `1.14.1` | `MIT` | Typecheck |
+| `pytest` | `8.3.4` | `MIT` | Test |
+| `pytest-asyncio` | `0.25.2` | `Apache 2.0` | Async tests |
+| `pytest-cov` | `6.0.0` | `MIT` | Coverage/testhjælp |
+| `ruff` | `0.8.6` | `MIT` | Linting |
+
+## Frontend / Node
+
+| Pakke | Version | Licens | Formål |
+| --- | --- | --- | --- |
+| `react` | `18.3.1` | `MIT` | UI runtime |
+| `react-dom` | `18.3.1` | `MIT` | DOM rendering |
+| `@testing-library/jest-dom` | `6.6.3` | `MIT` | DOM assertions |
+| `@testing-library/react` | `16.1.0` | `MIT` | React UI-tests |
+| `@eslint/js` | `9.18.0` | `MIT` | ESLint base config |
+| `@types/react` | `18.3.18` | `MIT` | TypeScript typer |
+| `@types/react-dom` | `18.3.5` | `MIT` | TypeScript typer |
+| `@vitejs/plugin-react` | `4.3.4` | `MIT` | Vite React-plugin |
+| `eslint` | `9.18.0` | `MIT` | Frontend linting |
+| `eslint-plugin-react-hooks` | `5.1.0` | `MIT` | React Hook-regler |
+| `eslint-plugin-react-refresh` | `0.4.16` | `MIT` | Vite/React refresh-regler |
+| `globals` | `15.14.0` | `MIT` | Browser-globals til ESLint |
+| `jsdom` | `25.0.1` | `MIT` | Browser-lignende testmiljø |
+| `typescript` | `5.7.3` | `Apache-2.0` | TypeScript compiler |
+| `typescript-eslint` | `8.20.0` | `MIT` | TypeScript-parser og regler til ESLint |
+| `vite` | `6.0.7` | `MIT` | Frontend dev/build |
+| `vitest` | `2.1.8` | `MIT` | Frontend tests |
+
+## Eksterne komponenter
+
+| Komponent | Licensstatus | Rolle |
+| --- | --- | --- |
+| OLA / `olad` | ekstern systempakke, se distributionens licensinfo | DMX-backend |
+| Open Fixture Library | ekstern tjeneste/dataformat | Fixture-søgning og import |
+| SQLite | ekstern runtimekomponent | Lokal database |

docs/IMPLEMENTATION-STATUS.md

@@ -0,0 +1,47 @@
+# Implementationsstatus
+
+## Fuldt implementeret og lokalt verificeret
+
+- FastAPI app-start og health endpoint
+- Simulator-DMX-backend
+- OLA-DMX-backend med rigtig `SendDmx`-integration via lokal OLA Python-klientadapter
+- 512-kanals frame-model
+- HTP/LTP merge og blackout-tests
+- Backend-status med `connected`, `last_successful_frame`, `frames_sent`, `send_errors`, `reconnect_count`, universe og output-port
+- Automatisk reconnect/degraded mode i OLA-backend samt mock OLA-adapter til tests
+- Sceneoprettelse og sceneaktivering i runtime
+- Effektoprettelse og trigger i runtime
+- Manual BPM
+- Tap BPM
+- MixItUp triggerendpoint med `202 Accepted`
+- WebSocket live-feed
+- Frontend dark UI med dashboard, fixtures, live desk, scenes, effects, BPM, MixItUp, DMX monitor, telemetry, backup og settings
+- Alembic migration fra tom database
+- Backup/restore i simulator-mode via service og API
+- Linux- og Pi-install/update/uninstall/diagnostics scripts som leverede artefakter
+- Debian 13 amd64 install/update/uninstall-flow med staging, frontend-build, `pip check`, OLA-importcheck og systemd health diagnostics
+- Patch med persisted grupper/link og fysisk placering
+- Fixture-/gruppebaserede scener med persisted targets
+- ALSA-baseret BPM-capture, device discovery og syntetiske audio-tests
+- Placering/view over patched fixtures i Web UI
+
+## Delvist implementeret
+
+- OLA-integrationen er implementeret og testet automatisk mod mock adapter. USB-DMX og OLA-output er verificeret af systemejeren på fysisk Debian 13 amd64-host, men ikke fysisk målt af Codex i denne workspace-session
+- Debian 13-installationsflowet er rettet og statisk/testmæssigt verificeret i repositoryet, men ikke end-to-end genkørt af Codex i en rigtig Debian VM i denne desktop-session
+- Fixtureimport persistes i runtime, men ikke fuldt i relationel database
+- MixItUp integrationer/mappings er dokumenteret, men ikke fuldt persisted eller rollebeskyttet
+- Telemetry history er kun stubbet som tom historik
+- Backup UI er funktionelt mod backup-endpoints, men uden download-knap
+
+## Simuleret
+
+- Hardwaretilstande som USB-frakobling og OLA-fejl via simulator/faults
+
+## Endnu ikke implementeret
+
+- Role enforcement og login/session-flow i hele API'et
+- Chaser-timeline og den fulde effektliste fra specifikationen
+- Avanceret patch-editor med flere universer og mere QLC+-agtig patch-oversigt
+- Historisk telemetrilagring, pruning og aggregering
+- Fuld scene/effect restore-stack med udløbstider og underliggende state-retur

docs/MIXITUP.md

@@ -0,0 +1,104 @@
+# MixItUp integration
+
+## Triggerendpoint
+
+Primært endpoint:
+
+```http
+POST /api/v1/triggers/{slug}
+Authorization: Bearer <mixitup-token>
+Content-Type: application/json
+```
+
+Eksempel med `raid`:
+
+```http
+POST /api/v1/triggers/raid
+Host: tuxdmx.local:8000
+Authorization: Bearer REPLACE_WITH_TOKEN
+Content-Type: application/json
+```
+
+```json
+{
+  "eventType": "raid",
+  "username": "streamviewer42",
+  "displayName": "StreamViewer42",
+  "amount": 120,
+  "eventId": "raid-evt-20260712-001",
+  "platform": "twitch",
+  "metadata": {
+    "source": "mixitup",
+    "notes": "Raid test i simulator"
+  }
+}
+```
+
+Forventet svar:
+
+```json
+{
+  "accepted": true,
+  "queue_depth": 1
+}
+```
+
+HTTP-status:
+
+```text
+202 Accepted
+```
+
+## Simple endpoints
+
+- `POST /api/v1/scenes/{sceneSlug}/activate`
+- `POST /api/v1/effects/{effectSlug}/trigger`
+- `POST /api/v1/dmx/blackout`
+- `POST /api/v1/bpm/tap`
+
+## Headers
+
+- `Authorization: Bearer <token>`
+- `Content-Type: application/json`
+
+Token må aldrig sendes i querystring.
+
+## MixItUp Web Request Action
+
+1. Vælg `POST`.
+2. Brug URL `http://<tuxdmx-host>:8000/api/v1/triggers/<slug>`.
+3. Tilføj header `Authorization` med `Bearer <token>`.
+4. Tilføj header `Content-Type` med `application/json`.
+5. Indsæt JSON-body.
+
+## Eksempel-body med MixItUp special identifiers
+
+```json
+{
+  "eventType": "raid",
+  "username": "$username",
+  "displayName": "$displayname",
+  "amount": "$raidviewercount",
+  "eventId": "$eventid",
+  "platform": "twitch",
+  "metadata": {
+    "eventName": "$eventname"
+  }
+}
+```
+
+## Test i simulator-mode
+
+```bash
+curl -i -X POST http://127.0.0.1:8000/api/v1/triggers/raid \
+  -H "Authorization: Bearer test-token" \
+  -H "Content-Type: application/json" \
+  -d '{"eventType":"raid","displayName":"AuditTest","amount":42,"eventId":"raid-audit-1","platform":"twitch","metadata":{}}'
+```
+
+## Sikkerhed
+
+- Roter token ved mistanke om læk.
+- Brug IP-allowlist eller reverse proxy, hvis endpointet eksponeres uden for isoleret LAN.
+- Rate limiting og duplicate/idempotency skal håndhæves server-side.
+

docs/OFL.md

@@ -0,0 +1,74 @@
+# Open Fixture Library
+
+## Søgeflow
+
+1. Web UI sender `POST /api/v1/fixtures/search-ofl?query=<tekst>`.
+2. Backend bruger OFL API, eller falder tilbage til lokale testfixtures i `test-data/fixtures`.
+3. Resultater vises som `manufacturer/fixture`.
+
+## Preview
+
+Preview kaldes via:
+
+```http
+POST /api/v1/fixtures/preview-ofl?manufacturer_key=<manufacturer>&fixture_key=<fixture>
+```
+
+Preview returnerer normaliseret fixturedata uden at skrive til lokal fixtureliste.
+
+I UI kan brugeren:
+
+- åbne preview,
+- se schema-version,
+- se kategorier,
+- vælge og inspicere modes,
+- se kanalindeks, displaynavn, precedence og opløsning.
+
+## Import
+
+Import kaldes via:
+
+```http
+POST /api/v1/fixtures/import-ofl?manufacturer_key=<manufacturer>&fixture_key=<fixture>
+```
+
+Import:
+
+- henter rå OFL-data,
+- normaliserer til TuxDMX-format,
+- gemmer resultatet i lokal runtime/cache.
+
+## Modevalg
+
+Modevalg bruges i preview til inspektion af kanalstruktur. Importen bevarer alle normaliserede modes i fixturemodellen, så patch/UI senere kan vælge korrekt mode.
+
+## Fixture-normalisering
+
+Normalisering sker i `backend/app/fixtures/normalize.py`:
+
+- OFL JSON læses ikke direkte af runtime.
+- Hver mode bliver til en stabil intern struktur med:
+  - `key`
+  - `channel_count`
+  - `channels[]`
+- Hver kanal får:
+  - `index`
+  - `key`
+  - `display_name`
+  - `precedence`
+  - `resolution`
+
+Fallback-regel i denne leverance:
+
+- kanaler med `dim` i navnet bliver markeret som `HTP`
+- øvrige kanaler bliver markeret som `LTP`, medmindre OFL-data allerede angiver noget andet
+
+## Offline fallback
+
+Hvis OFL ikke kan nås, søger klienten i lokale fixtures under `test-data/fixtures`.
+
+## Begrænsninger i denne leverance
+
+- OFL update-diff, warnings og backup før fixturemigration er endnu ikke fuldt implementeret.
+- Runtime persistence til database for importerede fixtures er kun delvist implementeret; preview/import virker i simulator-runtime og kan verificeres via API/UI.
+

docs/system-manual/MANUAL.md

@@ -0,0 +1,323 @@
+# TuxDMX Manual
+
+## Formål
+
+TuxDMX er et browserbaseret lyskontrolsystem med disse hovedspor:
+
+- fysisk DMX-output via `OLA / USB-DMX`
+- virtuelle universer til Home Assistant-bro
+- fixture-baseret patch
+- scenes, live-mixer, effekter og BPM
+
+Denne manual beskriver den nuvaerende WebUI og de vigtigste arbejdsgange.
+
+## Vigtigt
+
+- Screenshots i denne mappe er genereret lokalt i `mock`-tilstand den 23. juli 2026.
+- De afspejler UI og flows, men er ikke bevis for fysisk hardwareafvikling.
+- Fysisk hardwaretest skal stadig vurderes separat paa target-maskinen.
+
+## Arkitektur kort fortalt
+
+- `Universe 1`
+  Typisk fysisk DMX-universe til OLA og USB-DMX.
+- `Universe 10`
+  Typisk internt universe til Home Assistant-mappings.
+- `Patch`
+  Bruges til rigtige DMX-fixtures med fixture-definition, mode, adresse og grupper.
+- `Home Assistant mappings`
+  Bruges til virtuelle enheder, som reagerer paa DMX-vaerdier fra et valgt HA-universe.
+
+## Foerstegangsopsætning
+
+### 1. DMX backend
+
+Gaa til `Settings` og vaelg:
+
+- `Backend = OLA / USB-DMX`
+- korrekt `Universe`
+- korrekt `OLA output-port`
+
+Gem derefter `DMX output`.
+
+### 2. Home Assistant-bro
+
+Hvis du vil styre Home Assistant parallelt:
+
+- indsaet `Base URL`
+- indsaet `Long-lived token`
+- saet `Standard HA-universe`, typisk `10`
+- saet `Bro aktiv = Ja`
+- tryk `Test forbindelse`
+- tryk `Hent HA-enheder`
+
+Der skal normalt ikke installeres noget ekstra i Home Assistant. TuxDMX bruger HA API direkte.
+
+### 3. Fixtures
+
+Gaa til `Fixtures` og:
+
+- soeg i OFL
+- preview fixture
+- import fixture
+
+Hvis din fixture ikke findes i OFL, kan du bruge fixture-fil import, hvis formatet er understoettet af TuxDMX.
+
+### 4. Patch
+
+Gaa til `Patch` og:
+
+- vaelg fixture
+- vaelg mode
+- giv fixture et navn
+- saet startadresse
+- brug grupper/link som fx `front`, `wash`, `synk-a`
+- gem patch
+
+## Daglig brug
+
+## Dashboard
+
+`Dashboard` er et overblik:
+
+- backend-status
+- BPM-status
+- kø-status
+- CPU/RAM/oppetid
+- hurtig adgang til blackout og systemkontrol
+
+## Live Desk
+
+`Live Desk` er den manuelle mixer.
+
+Her vises nu:
+
+- patched fixtures
+- virtuelle Home Assistant-enheder fra dine HA-mappings
+
+Du kan:
+
+- vaelge en enhed i venstre liste
+- se universe og kanalrange
+- justere kanaler live med sliders
+- nulstille den valgte enhed
+- bruge blackout / release blackout
+
+For HA-enheder vises ogsaa:
+
+- `entity_id`
+- status
+- senest sendte HA-servicekald
+
+## Fixtures
+
+`Fixtures` bruges til bibliotek og import:
+
+- OFL-soegning
+- OFL-preview
+- OFL-import
+- filimport
+- videresendelse til patch-flow
+
+## Patch
+
+`Patch` bruges til rigtig DMX-adressering:
+
+- fixturevalg
+- modevalg
+- start/slutadresse
+- overlap-validering
+- grupper/link
+- universe-grid
+- fysisk placering
+
+## Placering
+
+`Placering` viser patched fixtures som et simpelt layout-view.
+
+Det bruges til:
+
+- scene-layout
+- gruppering og overblik
+- senere visualisering og positionseffekter
+
+## Scener
+
+`Scener` er fixture- og gruppebaseret.
+
+Du bygger scener ud fra:
+
+- en bestemt fixture
+- eller en gruppe
+
+Derefter vaelger du attributter og vaerdier som fx:
+
+- Dimmer
+- RGB
+- strobe
+- andre importerede attributter fra fixture-mode
+
+## Effekter
+
+`Effekter` er beregnet til effekt- og triggerarbejde.
+
+Siden bruges til:
+
+- oprettelse af effekter
+- trigger
+- stop
+- senere BPM- og triggerbindinger
+
+## BPM
+
+`BPM` bruges til:
+
+- manuel BPM
+- tap tempo
+- audio-start og audio-stop
+- lydniveau og beatstatus
+- effektkobling til BPM
+
+ALSA-input skal vaelges i `Settings`, og derefter bruges BPM-siden til selve drift og trigger-workflow.
+
+## MixItUp
+
+`MixItUp` er til trigger-workflow og eksterne events.
+
+Herfra kan du teste triggerflow og senere knytte stream-events til scener eller effekter.
+
+## DMX monitor
+
+`DMX monitor` viser DMX-aktivitet.
+
+Formålet er:
+
+- se hvilke kanaler der bærer vaerdier
+- se hvor data kommer fra
+- kontrollere frame-output under fejlfinding
+
+## Telemetry
+
+`Telemetry` viser tekniske driftsdata:
+
+- CPU
+- RAM
+- temperatur, hvis tilgaengelig
+- reconnects
+- queue depth
+- events og fejlspor
+
+## Backup
+
+`Backup` bruges til:
+
+- backup-oprettelse
+- restore
+- hurtig recovery af driftstilstand
+
+## Settings
+
+`Settings` samler de vigtigste driftsindstillinger:
+
+- DMX output
+- Home Assistant-bro
+- BPM / audio-input
+- servicegenstart
+- host-genstart
+
+Det er her de fleste systemvalg foretages, men selve daglig styring foregaar typisk i `Live Desk`, `Scener`, `Effekter` og `BPM`.
+
+## Home Assistant workflow
+
+Den anbefalede model er:
+
+- fysisk DMX paa `Universe 1` via OLA / USB-DMX
+- HA-bro paa `Universe 10`
+
+Eksempel:
+
+- `Universe 10`, `adresse 1`, `fixturetype switch`, `entity light.loft_bunker`
+- `Universe 10`, `adresse 10`, `fixturetype rgb`, `entity light.bar_rgb`
+
+### Vigtigt om fixturetype
+
+`fixturetype` styrer kun hvordan TuxDMX fortolker DMX-data:
+
+- `switch`
+  binær on/off med hysterese
+- `dimmer`
+  brightness
+- `rgb`, `rgbw`, `cct`
+  farvepayload
+- `scene`, `automation`
+  rising-edge trigger
+
+Selve HA-service-domænet udledes nu fra `entity_id`, fx:
+
+- `light.loft_bunker` → `light.turn_on/off`
+- `switch.relay` → `switch.turn_on/off`
+- `scene.party_mode` → `scene.turn_on`
+- `automation.something` → `automation.trigger`
+
+## Opdatering og deploy
+
+### Windows
+
+Fra denne workspace:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\sync-windows-deploy.ps1
+```
+
+### Linux target-host
+
+```bash
+cd ~/TuxDMXWebUI
+sudo bash ./scripts/update-linux.sh --non-interactive --force
+sudo systemctl restart tuxdmx.service
+```
+
+Kontrol:
+
+```bash
+systemctl status tuxdmx.service --no-pager
+curl http://127.0.0.1:8000/api/v1/health
+```
+
+## Fejlfinding kort
+
+### Home Assistant forbinder men reagerer ikke
+
+Kontroller:
+
+- korrekt `entity_id`
+- korrekt `fixturetype`
+- at HA-mapping ligger paa det forventede universe
+- at service-routing passer til entity-domænet
+
+### DMX virker ikke fysisk
+
+Kontroller:
+
+- `Backend = OLA / USB-DMX`
+- korrekt OLA-port
+- korrekt universe
+- at `olad` koerer
+
+### Audio/BPM reagerer ikke
+
+Kontroller:
+
+- valgt ALSA-input
+- at device ikke er optaget
+- at der er signal paa input
+
+## Bilag
+
+- [SCREENSHOTS.md](./SCREENSHOTS.md)
+- [API-ENDPOINTS.md](../API-ENDPOINTS.md)
+- [BPM.md](../BPM.md)
+- [MIXITUP.md](../MIXITUP.md)
+- [OFL.md](../OFL.md)
+- [IMPLEMENTATION-STATUS.md](../IMPLEMENTATION-STATUS.md)
+- [HARDWARE-VALIDATION.md](../HARDWARE-VALIDATION.md)

docs/system-manual/README.md

@@ -0,0 +1,25 @@
+# TuxDMX Systemmanual
+
+Denne mappe samler en enkel manuel dokumentationspakke til TuxDMX WebUI.
+
+Indhold:
+
+- `MANUAL.md`
+  Samlet brugermanual med opsaetning, daglig brug, Home Assistant-flow og service/update.
+- `SCREENSHOTS.md`
+  Oversigt over alle genererede screenshots med korte forklaringer.
+- `screenshots/`
+  PNG-screenshots af hele WebUI'et side for side.
+
+Vigtigt:
+
+- Screenshots i denne mappe er genereret den 23. juli 2026 fra den lokale WebUI i `mock=1` mode.
+- De viser den aktuelle UI-struktur og sideopbygning.
+- De er ikke dokumentation for fysisk Raspberry Pi-, OLA-, USB-DMX- eller lys-hardwaretest.
+- Hardwareafgraensninger og manuel hardwarevalidering hoerer stadig hjemme i [HARDWARE-VALIDATION.md](../HARDWARE-VALIDATION.md).
+
+Anbefalet laeseraekkefoelge:
+
+1. `MANUAL.md`
+2. `SCREENSHOTS.md`
+3. de enkelte filer i `screenshots/`

docs/system-manual/SCREENSHOTS.md

@@ -0,0 +1,68 @@
+# Screenshots
+
+Dette er et samlet screenshotsaet af TuxDMX WebUI genereret den 23. juli 2026.
+
+Kilde:
+
+- lokal UI-visning i `mock=1`
+- capture fra browser via lokal preview-server
+
+Formaal:
+
+- vise sideopbygning
+- understoette manualen
+- give et hurtigt visuelt overblik over systemet
+
+## Oversigt
+
+### Dashboard
+
+![Dashboard](./screenshots/dashboard.png)
+
+### Live Desk
+
+![Live Desk](./screenshots/live-desk.png)
+
+### Fixtures
+
+![Fixtures](./screenshots/fixtures.png)
+
+### Patch
+
+![Patch](./screenshots/patch.png)
+
+### Placering
+
+![Placering](./screenshots/placement.png)
+
+### Scener
+
+![Scener](./screenshots/scenes.png)
+
+### Effekter
+
+![Effekter](./screenshots/effects.png)
+
+### BPM
+
+![BPM](./screenshots/bpm.png)
+
+### MixItUp
+
+![MixItUp](./screenshots/mixitup.png)
+
+### DMX monitor
+
+![DMX monitor](./screenshots/dmx-monitor.png)
+
+### Telemetry
+
+![Telemetry](./screenshots/telemetry.png)
+
+### Backup
+
+![Backup](./screenshots/backup.png)
+
+### Settings
+
+![Settings](./screenshots/settings.png)