init

docs/ARCHITECTURE.md

@@ -0,0 +1,47 @@
+# Architektur und Datenhaltbarkeit
+
+Agenten verbinden sich aus jedem Segment per HTTPS zur zentralen Django-API.
+Jeder Host sammelt alle fünf Sekunden Messwerte. Ein Collector je Broker empfängt
+Celery-Events. Vor dem Versand werden Daten in einer SQLite-WAL-Outbox auf dem Host
+committet. Die API validiert den gesamten Batch, sperrt den Serverdatensatz und
+schreibt Ereignisarchiv und abgeleitete Zustände in einer PostgreSQL-Transaktion.
+Erst nach bestätigter Annahme löscht der Agent die lokalen Einträge.
+
+Ereignis-UUIDs verhindern Duplikate bei wiederholter Übertragung. Die API bindet
+Tokens an einen Server; Klartexttokens werden zentral nicht gespeichert. Bei Verlust
+der Antwort nach erfolgreichem Commit ist die Wiederholung unschädlich. Verspätete
+Messwerte überschreiben keine neueren Werte; veraltete Samples machen einen Host
+nicht online. Task-Endzustände werden nicht durch verspätetes RECEIVED überschrieben.
+
+Der NiceGUI-Prozess spricht intern mit Django; Browser erhalten keine Agent-Tokens.
+Ein fünfsekündiger Timer aktualisiert die Ansichten. Einstellungen und KI-Ausgabe
+werden während der Bearbeitung nicht automatisch neu aufgebaut. Redis dient als
+zentraler Celery-Broker und Login-Limit-Cache, PostgreSQL als Monitoringspeicher.
+Seaborn/NumPy erzeugen PNG-Auslastungsberichte, ECharts die Live-Diagramme.
+
+## Persistenzgrenzen
+
+- Ausfall des zentralen Servers/Netzes: bereits erfasste Events bleiben in der lokalen Outbox.
+- Agentenneustart: vorhandene Outbox bleibt erhalten; vor der lokalen Speicherung
+  verlorene Broker-Events können nicht rekonstruiert werden.
+- Voller Datenträger/Outbox-Limit: Erfassung kann ausfallen. Spool-Größe und Logs überwachen.
+- Celery-Eventtransport ist keine garantierte Geschäftsereignis-Zustellung.
+  Für lückenlose Nachweise zusätzlich eine transaktionale Outbox in den Fachanwendungen einsetzen.
+- Flower-Neustart: eigener Dateistand wird geladen; seit dem letzten Speichern
+  können bei hartem Absturz Daten fehlen. Zentrale bereits angenommene Events bleiben erhalten.
+- Aufbewahrung: Standard 90 Tage, einstellbar; stündliche bereinigende Celery-Aufgabe.
+  Backups besitzen eine davon unabhängige Aufbewahrung.
+- Task-Argumente, Rückgabewerte und Exceptiontexte werden bewusst nicht gesammelt.
+  Die Fehleransicht zeigt Zustände; Stacktraces bleiben in den jeweiligen Anwendungslogs.
+
+## Dimensionierung
+
+Bei fünf Sekunden pro Host entstehen 17.280 Host-Messereignisse pro Tag und Host,
+zusätzlich Flower-/Collector-Status sowie Task-/Worker-Events. Pro Metric werden
+Event- und Metric-Zeilen gespeichert. Kapazität mit echten Payloads messen.
+Für große Flotten sollten Partitionierung, ältere Zeitreihenaggregate und SQL-Abfragen
+unter Produktionslast optimiert werden; diese Version verwendet indizierte Tabellen
+und begrenzte Listen/Bereinigungsbatches, keine Partitionierung.
+
+Quellen: https://flower.readthedocs.io/en/latest/config.html und
+https://docs.celeryq.dev/en/stable/userguide/monitoring.html (geprüft 04.11.2026).