# Workflows

**Revision:** r2
**Source:** CLAUDE.md, Code-Analyse
**Last updated:** 2026-04-10 14:00

---

## Wakeword-Erkennung

```
  Client (Satellite)           Server                 Client (andere)
       |                         |                         |
       | 1. Wakeword erkannt     |                         |
       |    (Erkennung pausieren) |                         |
       |    (Audio puffern)      |                         |
       |                         |                         |
       |--WakewordDetected------>|                         |
       |                         |<--WakewordDetected------|
       |                         |     (wenn auch erkannt) |
       |                         |                         |
       |         2. 1 Sekunde warten                       |
       |            (Arbitrierung:                         |
       |             hoechstes audio_level                 |
       |             gewinnt)                              |
       |                         |                         |
       |<--WakewordSelected------|                         |
       |   (conversation_id)     |--WakewordAbort--------->|
       |                         |                         |
       | 3. Audio streamen       |                         |
       |   (max 60s oder         |                         |
       |    3s Stille)           |                         |
       |                         |                         |
       |------Audio------------->|                         |
       |------Audio------------->|                         |
       |--RecordingDone--------->|                         |
       |                         |                         |
       |         4. raw_audio_input_received               |
       |            Event ausloesen                        |
       |                         |                         |
       |         5. STT -> NLP -> Intent                   |
```

### Timing-Parameter

| Parameter | Wert | Beschreibung |
|-----------|------|--------------|
| Arbitration Timeout | 1 Sekunde | Warten auf mehrere Wakewords |
| Max Silence | 3 Sekunden | Stille beendet Aufnahme |
| Max Duration | 60 Sekunden | Maximale Aufnahmedauer |
| Reconnect Interval | 5 Sekunden | Wiederverbindungsversuch |

## Satellite-Registrierung

1. Admin aktiviert Registrierungsmodus (60 Sekunden Timeout)
2. Neuer Client verbindet sich, sendet `SatelliteConnect` (MAC, Room, Alias)
3. Server prueft MAC — nicht registriert + Registrierungsmodus aktiv
4. Server speichert `satellites/{MAC}.json` und sendet `SatelliteAccepted`
5. Client erhaelt session_key und Ports

### Registrierungsdatei (satellites/{MAC}.json)

```json
{
    "id": "sat-uuid-1234",
    "room_id": "wohnzimmer",
    "mac_address": "AA-BB-CC-DD-EE-FF",
    "alias": "Echo Wohnzimmer",
    "registered_at": "2026-01-31T12:00:00.000Z"
}
```

## Service-Start-Reihenfolge

```
CRITICAL (0) -> CORE (10) -> NETWORK (20) -> MANAGER (30) -> PLUGIN (40) -> OPTIONAL (50)
     |              |              |              |              |              |
     v              v              v              v              v              v
  Logging      EventManager    Sockets        Satellite      Plugins        Extras
  Config                       Protocol       Registration   ConfigListener
                               ConfigListener
```

**Abhaengigkeiten werden automatisch aufgeloest:** Wenn Service B von Service A abhaengt, wird A vor B gestartet.

## Installer-Workflow

### Ablauf

```
1. CLI: --mode server|client|standalone --version X.X.X --source-archive /pfad/trixy.tar.gz
2. TUI startet mit F-Key Navigation:
   F1: System (Hostname, Username, Pfad, Autostart)
   F2: Netzwerk (WiFi-Hotspot / WLAN-Client / Server-Verbindung)
   F3: Plugins (Auswahl)
   F4: Hardware-Preflight (Disk/RAM Check)
   F5: Nutzungsbedingungen
   F6: Installation starten
3. Installation laeuft Schritt fuer Schritt mit Fortschritt
4. Bei Netzwerk-Aenderungen: Reboot-Warnung anzeigen
```

### WiFi-Hotspot Setup (Server, Bookworm-kompatibel)

```
step_wifi_ap():
  1. hostapd.conf schreiben (SSID, WPA2, Kanal)
  2. dnsmasq.conf schreiben (DHCP-Range, DNS)
  3. systemd-networkd: /etc/systemd/network/10-trixy-wlan0.network (statische IP)
  4. NetworkManager: /etc/NetworkManager/conf.d/99-trixy-wlan0-unmanaged.conf
  5. dnsmasq Race-Fix: systemd override mit ExecStartPre wait-loop
  6. sysctl: IP-Forwarding persistent
  7. iptables: MASQUERADE NAT-Regel
  8. Services nur ENABLE (nicht start) -> Deferred Activation nach Reboot
```

### WiFi-Client Setup (Client/Standalone)

```
step_wifi_connect():
  1. Primaeres WLAN: nmcli connection add mit autoconnect-priority=100
  2. Fallback-WLAN: nmcli connection add mit autoconnect-priority=10
  3. Auto-Switchback Timer installieren (optional)
  4. KEINE sofortige Aktivierung -> Deferred Activation nach Reboot
```

**Kritisch:** Netzwerk-Aktivierung ist IMMER deferred (erst nach Reboot), damit SSH-Sessions waehrend der Installation nicht abbrechen.

## Training-Workflow

### Trainer-Framework (ADR-008)

```
1. TrainerRegistry entdeckt Trainer:
   - Core: trixy_core/trainer/core/*.py + */trainer.py
   - Plugin: plugins/*/trainer.py
2. TUI: F7 zeigt Trainer-Liste
3. Sub-Navigation:
   F1: Info (Name, Version, Beschreibung)
   F2: Settings (dynamisches Formular aus FormSchema)
   F3: Dataset (Datensatz-Konfiguration)
   F4: Optional (zusaetzliche Optionen)
   F5: Validate (Pre-Training Checks: GPU, Daten, Speicher)
   F6: Training (Start/Pause/Stop, Fortschritt, LossChart)
4. Training laeuft als separater Prozess (multiprocessing.Process, spawn)
5. Fortschritt via Queue: Epoch, Loss, Accuracy, VRAM, ETA
6. LossChart Widget: Braille-Zeichen (U+2800-U+28FF), Bresenham-Linien
```

### Wakeword-Training

```
WakewordTrainer:
  1. TTS-Engines generieren synthetische Wakeword-Samples (Piper, gTTS, Edge, ...)
  2. Audio-Augmentation: Noise-Mix, Volume, Pitch-Shifting
  3. Mel-Spectrogram Features extrahieren
  4. LogisticRegression auf OpenWakeWord-Basis
  5. Export: model.pth, model.onnx, model.pt, metafile.json
```

### Intent-Training

```
IntentTrainer:
  1. DataGenerator sammelt Intents aus Plugin intents.yaml
  2. Pattern-Expansion mit Slot-Werten
  3. Sentence-Transformers Encoder (ONNX, 113MB)
  4. 2-Layer Linear Classifier
  5. Optional: BIO-Slot-Tagger Kopf
  6. Export: intent_classifier.onnx, slot_tagger.onnx, bio_labels.json
```

---

**See also:** [architecture.md](architecture.md), [integrations.md](integrations.md)