# Chronolite — Referenzimplementierung

Referenzimplementierung der zentralen Komponenten des Forschungsprojekts **Chronolite**:
der **Chronolite-App**, des **Chronolite Data Hub** und eines **IoT Controllers** zur
Ansteuerung der Raumbeleuchtung.

Ziel des vom Bundesministerium für Digitales und Staatsmodernisierung (BMDS) geförderten
Projekts Chronolite war es, chronobiologisch wirksame, vernetzte Beleuchtung für den
Mobilitätssektor (Flugzeug, Transitbereich, Auto, Bahn) nutzbar zu machen. Diese
Referenzimplementierung veröffentlicht zum Projektabschluss den grundlegenden Aufbau und
die Wirkprinzipien von App und Hub in einer Form, die jede*r Interessierte lokal
ausführen und nachvollziehen kann.

## Einordnung: Referenz vs. Projektsystem

Im Förderprojekt kam eine **komplexere, hochskalierbare Variante** des Systems zum
Einsatz: eine cloudbasierte, serverlose Plattform mit verwalteten Datenbanken und
nativen iOS-/Android-Apps. Für die Veröffentlichung wurde das System bewusst **auf
Einfachheit und Nachvollziehbarkeit hin vereinfacht**:

| Aspekt | Projektsystem | Referenzimplementierung |
| --- | --- | --- |
| App | Native iOS-/Android-App | Lokale Webapp (Vite + React) |
| Data Hub | Serverlose Cloud-Plattform (hochskalierbar) | Ein lokaler Express-Prozess |
| Persistenz | Verwaltete Cloud-Datenbanken | Lesbare JSON-Datei |
| Raumerkennung | QR-Code, GPS, BLE-Raumbeacons | Manuelle Auswahl aus 3 Demo-Räumen |
| Raumverwaltung | Registrierung über API/Portal | Statische Liste |
| Lichtsensorik | Reale/infrastrukturgebundene/virtuelle Sensoren | Einfaches virtuelles Tageslichtmodell (Mock) |
| Leuchtenansteuerung | IoT-Protokolle (z. B. DALI/KNX, Kabinensysteme) | Formatierte Konsolenausgabe |

Die App ist hier **bewusst keine native Mobile-App**: Native Apps erfordern ein
komplexes lokales Entwickler-Setup (Xcode/Android Studio, Signierung, Emulatoren) und
müssten kontinuierlich an neue OS- und Toolchain-Versionen angepasst werden — beides
widerspricht dem Ziel einer dauerhaft einfach ausführbaren Referenz. Die Wirkprinzipien
(anonyme Registrierung, Raumzuordnung, Präferenzen, Routinen, Hub-Anbindung) sind
identisch umgesetzt.

Die Referenzimplementierung hat **keinerlei Abhängigkeiten zu externen oder verwalteten
Diensten** — alles läuft lokal mit Node.js.

## Komponenten

```
┌──────────────────┐   REST    ┌──────────────────────┐   REST + WebSocket   ┌──────────────────┐
│  Chronolite App   │──────────▶│  Chronolite Data Hub │◀────────────────────│  IoT Controller  │
│  (Port 4100)      │           │  (Port 4000)         │                      │  (Port 4200)     │
│  Webapp           │           │  Kurvenlogik +       │  presenceChanged ───▶│  Steuerschleife  │
│                   │           │  JSON-Persistenz     │                      │  1×/Minute       │
└──────────────────┘           └──────────────────────┘                      └──────────────────┘
```

| Komponente | Pfad | Port | Beschreibung |
| --- | --- | --- | --- |
| Chronolite App | `apps/app` | **4100** | Anonyme Registrierung, Raumauswahl, Präferenzen, Routinen, Kurven-Visualisierung |
| Chronolite Data Hub | `apps/hub` | **4000** | REST-API + WebSocket, Präferenz-/Routinen-Speicher, Kurvengenerierung |
| IoT Controller | `apps/iot-controller` | **4200** | Hört auf Anwesenheitsänderungen, berechnet minütlich die Lichtwerte |
| Kurven-Bibliothek | `packages/curves` | — | Polynom-Kurvengenerierung („Curvis") und Personalisierungs-Pipeline |

## Schnellstart

Voraussetzungen: [Node.js](https://nodejs.org) ≥ 20 und [pnpm](https://pnpm.io) ≥ 9.

```bash
pnpm install   # Abhängigkeiten installieren
pnpm dev       # Hub, IoT Controller und App gemeinsam starten
```

Danach die App im Browser öffnen: **http://localhost:4100**

Ausführliche Anleitung inkl. Demo-Walkthrough: [docs/INSTALLATION.md](docs/INSTALLATION.md)

## Demo in 2 Minuten

1. Die App öffnet sich, registriert sich anonym am Hub und speichert die erhaltene ID im
   Local Storage des Browsers.
2. Unter **Persönliche Präferenzen** Chronotyp (MSFsc), Geburtsjahr und
   Lichtfarb-Präferenz speichern.
3. Unter **Routinen** z. B. „20:00 — Lesen — Entspannung" anlegen.
4. Den Raum **Flughafen-Gate** betreten.
5. Im Terminal beobachten, wie der IoT Controller über den WebSocket benachrichtigt
   wird, die personalisierten Kurven lädt und minütlich neue Lichtwerte
   (Dimmwert + Farbtemperatur) „an die Beleuchtung übergibt" (Konsolenausgabe).
6. Den Raum verlassen → der Controller fällt auf die Basiskurven zurück.

## Dokumentation

- [docs/INSTALLATION.md](docs/INSTALLATION.md) — Installation, Start, Troubleshooting
- [docs/ARCHITEKTUR.md](docs/ARCHITEKTUR.md) — Systemaufbau, Datenfluss, Datenschutz, Vereinfachungen
- [docs/ALGORITHMEN.md](docs/ALGORITHMEN.md) — Kurvengenerierung (Tagesverlauf) und Steuerungslogik, mit Diagrammen
- [docs/API.md](docs/API.md) — REST- und WebSocket-API des Data Hub mit Beispielen

## Entwicklung

```bash
pnpm lint      # Biome (Linter + Formatter)
pnpm test      # Unit-Tests der Kurven-Bibliothek (Vitest)
```

Alle Abhängigkeiten sind **exakt auf die im Januar 2025 verfügbaren Versionen
fixiert**, damit die Referenzimplementierung reproduzierbar bleibt.

## Lizenz

MIT
