# noahROBOT Softwarearchitektur

Status: Version 1.2.0 ist auf dem realen PELADN als simulation-only
Windows-System installiert und ueber das private WLAN erreichbar. Die
vorhandene Windows-Installation blieb erhalten. HTTPS, mDNS, REST, WebSocket,
Pairing, Rollen und Safety-Policy wurden live abgenommen. Firmware-Flash und
Motorpfad sind nicht freigegeben.

## 1. Schichten und Vertrauensgrenzen

```text
MediaWiki/PWA (oeffentlich, keine Hardwareautoritaet)
        |
        | statische Assets / semantische Absichten
        v
lokale PWA auf HTTPS (Smartphone-Kopf oder iPad-Controller)
        |
        | authentifizierte, rollenbegrenzte WebSocket/API-Nachrichten
        v
Caddy auf Windows :443 ----> Gateway auf 127.0.0.1:8765
        |                         |
        |                         +--> deterministische Safety-Policy
        |                         +--> Simulation (aktiv)
        |                         +--> Serialadapter (deaktiviert)
        +--> lokale PWA

Funduino STATUS-only (nicht geflasht)
        X  keine Verbindung zu L298N/Motoren
```

Jede Grenze validiert Schema, Rolle, Sequenz, Rate und Lebensdauer. Browser,
MediaWiki, Sprache und LLM besitzen keinen Rohserial-, Pin- oder PWM-Kanal.

## 2. Komponenten

| Komponente | Ort | Aufgabe | Sicherheitsstatus |
| --- | --- | --- | --- |
| MediaWiki-Route `/robot/` | Webserver | oeffentliche Installations-/Simulations-PWA | kein lokales Hardwaregeheimnis |
| lokale PWA | PELADN/Caddy | Gesicht, Talk, Setup, Steuerung, Offline-Shell | STOP sichtbar; Medien nur nach Einwilligung |
| Gateway | Windows/FastAPI/Uvicorn | Pairing, Rollen, Lease, Policy, Telemetrie | localhost; WebSocket-Laufzeit gepinnt; Hardware-Gate geschlossen |
| Caddy | Windows-Dienst | lokales HTTPS, statische PWA, Reverse Proxy | private Netze; CA-Key nicht exportiert |
| mDNS | Windows-Dienst | `_https._tcp.local` fuer private IPv4 | keine Tokens/Identitaeten in TXT |
| Watchdog | Windows-Dienst | Health pruefen und Fehler markieren | erzeugt niemals Fahrbefehle |
| Robot Network | Windows-Dienst | lokaler Wi-Fi-Direct-Legacy-AP `NOAH-ROBOT` | kein NAT/Internet-Sharing; standardmaessig bis Aktivierung aus |
| Funduino | ATmega328P | spaeter letzter Echtzeit-Watchdog | STATUS-only vorhanden, ungeflasht |

Provider-/LLM-Logik, Renderer und MediaWiki-Artikelanlage bleiben von der
Robotik getrennt. NOAH-Talk darf nur semantische Absichten liefern; der
gemeinsame allowlist-basierte Intent-Router entscheidet deterministisch.

## 3. Windows-Dienstmodell

WinSW betreibt vier Kern- und einen getrennt freigebbaren Netzwerkdienst:

- `noah-robot-gateway`: Uvicorn/FastAPI auf Loopback
- `noah-robot-web`: Caddy auf HTTPS 443
- `noah-robot-mdns`: lokale Dienstanzeige
- `noah-robot-watchdog`: begrenzter Healthcheck
- `noah-robot-network`: autonomer Wi-Fi-Direct-Legacy-AP ohne Internetfreigabe

Abhaengigkeiten, Restart-Limits und Logrotation sind in
`scripts/windows/install.ps1` festgelegt. Ein Absturz setzt keinen alten
Fahrzustand fort. Bei Start, Stop, Reconnect oder Readiness-Fehler bleibt der
Sollzustand STOP.

## 4. Daten- und Netzwerkfluss

Die PWA laedt statische Assets offline-faehig. API-, WebSocket-, Health-,
Zertifikats-, Auth-, PIN-, Token-, Audio- und Videoantworten werden nicht vom
Service Worker gecacht. Pairing-Zustand bleibt lokal. Erlaubte Logs enthalten
nur Zeit, Version, pseudonyme Session, Befehlsklasse und Safety-Entscheidung.

Im Roboternetz zugaenglich sind auf dem PELADN nur:

- TCP 443 fuer PWA/API/WebSocket,
- UDP 5353 fuer mDNS,
- TCP 22 nur waehrend zeitlich begrenzter Recovery/Abnahme.

Der Gateway-Port 8765 bleibt Loopback. Der Realtek-8852BE-Adapter und die
Wi-Fi-Direct-API wurden im Benutzer- und SYSTEM-Kontext inventarisiert. Die
gewählte Legacy-AP-Technik stellt `NOAH-ROBOT` ohne Upstream bereit und leitet
keinen Verkehr in Schul- oder Heimnetze weiter. Ein vorhandenes WLAN bleibt ein
optionaler Wartungsweg.

## 5. Autoritaets- und Stop-Kette

```text
physischer rastender Not-Stopp
  > Firmware-E-Stop/Watchdog
  > Gateway STOP/Lease-Ende
  > PWA STOP/Dead-Man
  > bestaetigte Sprachabsicht
  > sonstige Funktion
```

Die physische Ebene muss Motorenergie unabhaengig von PC, USB und Software
unterbrechen. Die Software allein kann dieses Gate nicht freigeben.

## 6. Release- und Rollbackmodell

Releases liegen versioniert unter `C:\Program Files\noah-robot\releases`.
`current` und `previous` sind kontrolliert umschaltbare Junctions. Vor einem
Wechsel werden Konfiguration, Dienstdefinitionen und Zustand gesichert. Erst
nach Simulation-, Readiness- und Gate-Pruefung wird das neue Release aktiv.

## 7. Noch nicht hardwareseitig bestaetigt

- lokaler CA-Import und PWA-Installation auf den physischen Smartphone-/iPad-Geraeten
- stabile COM-Zuordnung des realen Funduino
- Firmware-Flash, Pinbelegung, Motorstrompfad und physischer Not-Stopp
- XTPower-Ausgang, Polaritaet, Sicherung und getrennte Spannungsdomaenen
- mechanische Montage und Zug-/Falltest der Auckly-Qi-Smartphone-Halterung
- Sensoren, Realfahrt und produktive externe KI

Diese Punkte sind manuell oder hardwaregebunden und bleiben bis zum jeweiligen
Abnahmegate gesperrt.
