# Installation & Start

Diese Anleitung führt Schritt für Schritt durch Installation und Start der
Chronolite-Referenzimplementierung. Es werden **keine externen Dienste, Konten oder
Cloud-Ressourcen** benötigt — alles läuft lokal.

## 1. Voraussetzungen

| Werkzeug | Version | Prüfen mit |
| --- | --- | --- |
| [Node.js](https://nodejs.org) | ≥ 20 (LTS) | `node --version` |
| [pnpm](https://pnpm.io) | ≥ 9 | `pnpm --version` |

pnpm lässt sich am einfachsten über Corepack aktivieren, das bei Node.js mitgeliefert
wird:

```bash
corepack enable
```

## 2. Installation

Im Wurzelverzeichnis des Repositories:

```bash
pnpm install
```

Das installiert die Abhängigkeiten aller Workspace-Pakete. Alle Versionen sind exakt
fixiert (Stand Januar 2025), sodass die Installation reproduzierbar ist.

## 3. Start

### Variante A: Alles auf einmal

```bash
pnpm dev
```

Startet Data Hub, IoT Controller und App gemeinsam (farblich getrennte Log-Ausgaben:
`hub`, `controller`, `app`).

### Variante B: Jede Komponente in einem eigenen Terminal

```bash
# Terminal 1 — Chronolite Data Hub (zuerst starten)
pnpm --filter @chronolite/hub start

# Terminal 2 — IoT Controller (Standard-Raum: gate)
pnpm --filter @chronolite/iot-controller start

# Terminal 3 — Chronolite App
pnpm --filter @chronolite/app dev
```

Der IoT Controller lässt sich per Umgebungsvariable auf einen anderen Raum setzen:

```bash
ROOM_ID=train pnpm --filter @chronolite/iot-controller start
```

### Feste Ports

| Komponente | URL |
| --- | --- |
| Chronolite Data Hub (REST) | http://localhost:4000 |
| Chronolite Data Hub (WebSocket) | ws://localhost:4000/ws |
| Chronolite App | http://localhost:4100 |
| IoT Controller (Status) | http://localhost:4200/status |

## 4. Demo-Walkthrough

1. **App öffnen:** http://localhost:4100. Die App registriert sich automatisch anonym
   am Hub; die erhaltene ID wird oben angezeigt und im Local Storage des Browsers
   gespeichert.
2. **Präferenzen speichern:** Chronotyp als MSFsc-Wert eintragen (den eigenen
   Chronotyp bestimmen: [Was ist dein Chronotyp?](https://www.chronsulting.org/was-ist-dein-chronotyp)),
   Geburtsjahr und Lichtfarb-Präferenz setzen, speichern.
3. **Routine anlegen:** z. B. `20:00 / Lesen / Entspannung`.
4. **Raum betreten:** „Flughafen-Gate" auswählen. Die App meldet die Anwesenheit an den
   Hub; der Hub benachrichtigt den IoT Controller über den WebSocket.
5. **Controller beobachten:** Im Terminal des Controllers erscheint

   ```
   [controller:gate] Presence changed (1 present) — refreshing curves
   [controller:gate] Curves updated — personalised for first user <id>
   [controller:gate] 14:31:26 | target mEDI 395 lx | daylight 452 lx | >>> set luminaires to 0 % @ 5635 K
   ```

   Die letzte Zeile ist die (in der Referenz als Konsolenausgabe umgesetzte) Übergabe
   der Sollwerte an die Raumbeleuchtung — einmal pro Minute neu berechnet.
6. **Kurven ansehen:** In der App zeigt das Diagramm „Tageskurven im aktuellen Raum"
   die beiden vom Hub gelieferten Polynomkurven (Ziel-mEDI und CCT-Präferenz, 0–24 Uhr).
   Präferenzen oder Routinen ändern und beobachten, wie sich die Kurven verschieben.
7. **Raum verlassen:** Der Controller erhält erneut eine Benachrichtigung und fällt auf
   die Basiskurven zurück.
8. **Status prüfen (optional):** http://localhost:4200/status zeigt den letzten
   Steuerungs-Tick als JSON.

## 5. Tests & Linting

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

## 6. Troubleshooting

| Problem | Ursache / Lösung |
| --- | --- |
| App zeigt „Der Chronolite Data Hub ist nicht erreichbar" | Hub zuerst starten (Port 4000), dann die App neu laden. |
| `EADDRINUSE` beim Start | Einer der festen Ports (4000/4100/4200) ist belegt. Den blockierenden Prozess beenden (`lsof -i :4000`). |
| Controller loggt „Could not fetch curves" | Hub läuft nicht oder `HUB_URL` zeigt auf eine falsche Adresse. |
| Gespeicherte Daten zurücksetzen | Hub stoppen und `apps/hub/data/hub-data.json` löschen. Die App registriert sich beim nächsten Laden automatisch neu. |
| pnpm nicht gefunden | `corepack enable` ausführen oder pnpm gemäß https://pnpm.io/installation installieren. |
