nexus/PROJECT_CONTEXT.md

Projekt-Zusammenfassung: Nexus Control Panel

1. Projekt-Zweck & Ziel Nexus ist ein zentrales, webbasiertes Admin-Interface zur Steuerung einer dynamischen IT-Infrastruktur. Module kapseln fachliche Funktionen (z.B. KEA DHCP, Pi Control).

2. Aktive Module (Kurzüberblick)

• KEA DHCP: Verwaltung von Hosts/Leases, Statische Reservierungen, Metadaten.
• Pi Control: Verwaltung von SSH-Hosts, Befehle/Preset, Konsole, Host-Status, Update/Upgrade-Checks.

3. Umgebungen & Domains

• Live: nexus.kusche.berlin
• Staging: staging.nexus.kusche.berlin

Container/Deploy-Layout:

• /app/live/ -> Live-Code
• /app/staging/ -> Staging-Code
• Jeweils mit eigenem /config-Unterordner:
  • /app/live/config/
  • /app/staging/config/

Repo-Layout zu Configs:

• /config/live/ und /config/staging/ liegen im Repo.
• Beim Deployment werden die Dateien daraus nach /app//config kopiert.
• WICHTIG: Im laufenden Container existiert /app/config/ NICHT, sondern nur /app/live/config und /app/staging/config.

4. Verzeichnisstruktur (Repo)

• /public/ -> Web Root (index.php, globale Assets)
• /api/ -> Backend/API-Endpunkte
• /src/ -> PHP-Kernklassen/Utilities
• /tools/ -> CLI/Worker/Jobs (z.B. tools/pi_control)
• /config/ -> Umgebungs-Configs (live/staging)
• /modules// -> Module (Pages, Assets, Bootstrap)
• /partials/structure/ -> Header/Footer/Menüs
• /partials/landingpages/ -> Komplette Seitenlayouts
• /debug/ -> Custom Logs

5. Modul-Konzept (WICHTIG)

• Jedes Modul lebt unter /modules//.
• Pflicht-Dateien i.d.R.:
  • module.json
  • bootstrap.php (Schema/Setup)
  • pages/*.php (UI/Endpoints)
  • assets/* (modulspezifisches CSS/JS)

Modulspezifische Assets:

• Modul-JS/CSS MUSS im Modul-Ordner liegen.
• Laden über Modul-Assets, z.B.:
  • $assets->addStyle('/module/pi_control/asset?file=pi_control.css');
  • $assets->addScript('/module/pi_control/asset?file=hosts.js', 'footer', true);
• KEINE modulspezifischen Änderungen in /public/assets/*.

6. Code-Änderungen nach Scope

• Modul-Aufgaben: nur /modules// + ggf. /tools/ ändern.
• Globale Layouts: /partials/structure und /public/assets/css/app.css.
• Konfigurationslogik: nur wenn nötig /config/ und /src/.

7. UI-Naming und Seitenaufbau

• Seitenheader-Box: oberste globale Header-Box mit Seitentitel, Login und Farbschema.
• Submenü-Box: Box direkt unter der Seitenheader-Box für modul- oder seitenbezogene Aktionen.
• Submenü-Aktionen: rechtsbündige Zusatzbuttons innerhalb der Submenü-Box, z.B. Setup, Nexus Übersicht oder Zur Startseite-Ersatz.
• Bereichs-Box: größere Inhaltsbox für einen zusammenhängenden Seitenbereich.
• Karten-Box: kleinere Karte auf derselben Ebene wie Bereichs-Boxen, meist in Grids.
• Zentrale CSS-Klassen:
  • main-header-box
  • submenu-box
  • module-submenu-actions
  • section-box
  • card-box
• Modulseiten sollen diesem Muster folgen:
  • zuerst Seitenheader-Box
  • danach Submenü-Box
  • danach Bereichs-Boxen und/oder Karten-Boxen je nach Modul
• Vertikale Abstände zwischen main-header-box, submenu-box und den ersten Folge-Boxen muessen aus der globalen Shell kommen.
  • Maßgeblich sind module-page-bg und module-page-stack in public/assets/css/app.css.
  • Top-Level-Wrapper wie Grids, Kartencontainer oder Modul-Listen duerfen keinen eigenen zusaetzlichen margin-top oder Sonder-Gap erzeugen, der den Abstand nach dem Submenue veraendert.
  • Bei Layout-Reviews ist explizit zu pruefen, ob Main-Header -> Submenue -> erste Section/Card optisch denselben Rhythmus hat wie auf Referenzseiten wie dem Boersenchecker.
• Setup gehört in Modulen grundsätzlich in die Submenü-Box.
• In Verwaltungsseiten soll Nexus Übersicht als fester Button in den Submenü-Aktionen vorhanden sein.
• Die Optik der Submenü-Aktionsbuttons kommt ausschließlich aus dem globalen CSS. Module sollen dort keine eigenen Farb- oder Variantenlogiken einschleusen.
• Beispielstruktur:
  • Börsenchecker: Seitenheader-Box, Submenü-Box, Bereichs-Box, Karten-Boxen, Bereichs-Box
  • FX-Rates: Seitenheader-Box, Submenü-Box, danach Bereichs-Boxen
  • Mining-Checker: Seitenheader-Box, Submenü-Box, Bereichs-Box, Karten-Boxen, Karten-Boxen, Bereichs-Box
  • Modulverwaltung: Seitenheader-Box, Submenü-Box, danach Karten-Boxen

8. Globales Setup-System (VERBINDLICH)

• Modul-Setup wird zentral über partials/landingpages/modules/setup.php gerendert.
• Die Bereiche
  • Allgemein
  • Datenbank
  • Zugriffsrechte
  • Cron Einstellungen muessen fuer alle Module aus dieser gemeinsamen Setup-Logik kommen.
• Nur Custom Settings darf modulspezifischen Inhalt enthalten.
• Modul-spezifische Sonderlayouts fuer die Bereiche Allgemein, Datenbank, Zugriffsrechte oder Cron Einstellungen sind nicht erlaubt.
• Wenn sich das Verhalten eines dieser Bereiche ändert, muss die Änderung zentral erfolgen, so dass sie automatisch fuer alle Module gilt.

Was global im Setup bereits verfügbar ist:

• gemeinsame Setup-Navigation mit festen Unterseiten
• rechte Aktionsseite mit
  • Nexus Übersicht
  • Zurück zum Modul
• gemeinsames Speichern pro Bereich
• gemeinsames Rendering von
  • Textfeldern
  • Zahlenfeldern
  • Checkboxen
  • Selects
  • Multiselects
  • Textareas
• globale Debug aktivieren-Option pro Modul im Bereich Allgemein
• gemeinsame Datenbank-Logik mit
  • Eigene Modul-DB nutzen
  • Anzeige/Verbergen der Custom-DB-Felder
  • optional mehreren DB-Gruppen wie db.* und metadata_db.*
  • Verbindung testen
  • Standardwerte laden
• gemeinsame Auth-/Zugriffslogik mit
  • Login erforderlich
  • erlaubten Benutzern
  • erlaubten Gruppen
  • bekannten Keycloak-Benutzern und -Gruppen
• gemeinsame Cron-/Scheduler-Logik mit
  • Anzeige von Intervall-Tasks
  • Anzeige von Cron-Jobs
  • Bearbeiten von Cron-Einträgen im Modal
  • Cron-Test direkt aus dem Setup
  • Mehrfacheinträgen bei mode = multi
  • Modul-Zeitzonen-Override fuer Crons
  • Vererbung globaler Cron-Zeitzonen-Defaults
• gemeinsame Darstellung von Setup-Aktionen und Statusblöcken
• globale Zeitzonen-Datalist aus nexus_timezones

Was ein Modul für das Setup nur noch liefern muss:

• module.json mit setup.fields
• optional setup.sections.database
• optional interval_tasks
• optional scheduler_jobs
• optional auth
• optional Bootstrap-Funktionen:
  • setup_actions
  • run_setup_action
  • setup_status
  • runtime_settings
  • save_runtime_settings

Was nicht mehr jedes Modul selbst bauen darf:

• eigene Setup-Seitenstruktur fuer Allgemein, Datenbank, Zugriffsrechte, Cron Einstellungen
• eigene DB-Toggle-Logik fuer Standard/Custom
• eigene Cron-Editor-Grundlogik
• eigene Debug-UI-Grundlogik
• eigene globale Zeitzonen-Defaults

Setup-Navigation:

• Setup-Routen laufen zentral ueber:
  • /modules/setup/<modul>/general
  • /modules/setup/<modul>/database
  • /modules/setup/<modul>/access
  • /modules/setup/<modul>/cron
  • /modules/setup/<modul>/custom
• Setup gehoert in der Modulansicht in die rechte Aktionsseite der Submenü-Box.

Steuerung per module.json:

• Ein Modul kann ueber setup.sections.database: true|false steuern, ob der Menüpunkt Datenbank angezeigt wird.
• Wenn setup.sections.database fehlt, kann die zentrale Setup-Logik den Punkt implizit aktivieren, sobald DB-Felder vorhanden sind.
• Modulfelder fuer Allgemein, Datenbank, Cron und Custom Settings werden zentral nach Feldnamen aufgeteilt:
  • debug_enabled -> Allgemein
  • use_separate_db und db.* / metadata_db.* -> Datenbank
  • schedule_timezone -> Cron Einstellungen
  • alle übrigen Setup-Felder -> Custom Settings

Weitere anerkannte Setup-Bausteine:

• interval_tasks
  • fuer automatische Aufgaben beim Modulaufruf
• scheduler_jobs
  • fuer zentrale Cron-Jobs ueber den Nexus-Scheduler
• auth
  • fuer den initialen Modulschutz
• db_defaults
  • fuer vorbefuellte Standard-DB-Werte im Datenbankbereich
• metadata_db_defaults
  • fuer weitere globale DB-Gruppen im Datenbankbereich

Speicherregel:

• Beim Speichern eines Setup-Bereichs duerfen nur die in diesem Bereich sichtbaren Felder aktualisiert werden.
• Felder aus anderen Bereichen duerfen nicht mit null, 0 oder leeren Strings ueberschrieben werden.

Datenbankbereich:

• Eigene Modul-DB nutzen ist der zentrale Standard-Schalter fuer Module mit optionaler eigener DB.
• Wenn der Schalter deaktiviert ist, duerfen keine Custom-DB-Eingabefelder sichtbar sein.
• Datenbankaktionen und Tabellenstatus gehoeren in den Menüpunkt Datenbank, nicht in Custom Settings.

9. Globale Zeitzonen-Logik (VERBINDLICH)

• Globale Nexus-Einstellungen liegen unter /settings.
• Dort werden zentral gepflegt:
  • Anzeige-Zeitzone
  • Standard-Zeitzone für Crons
• Anzeige-Zeitzone:
  • hat eine Custom-Checkbox
  • ohne Custom wird die System-Zeitzone verwendet
  • die aktive Zeitzone soll angezeigt werden
• Standard-Zeitzone für Crons:
  • ist der globale Default fuer Modul-Crons
  • Module duerfen diese Zeitzone im Setup uebersteuern
  • einzelne Cron-Einträge duerfen sie ebenfalls uebersteuern

Modul-Cron-Verhalten:

• Im Modul-Setup gibt es keinen nackten Pflicht-Default mehr, der immer direkt eingegeben werden muss.
• Stattdessen:
  • Anzeige des aktuell wirksamen Modul-Cron-Defaults
  • Custom-Zeitzone verwenden fuer Modul-Override
  • einzelne Cron-Einträge koennen ebenfalls Custom-Zeitzone verwenden
• Ohne Override erbt ein Cron-Eintrag die Modul-Zeitzone, und die Modul-Zeitzone erbt den globalen Nexus-Cron-Default.

Globale PHP-Helfer:

• Neue Module sollen fuer zentrale Zeit-/Debug-Defaults nach Moeglichkeit die globalen Funktionen aus src/App/functions.php nutzen:
  • nexus_settings()
  • nexus_save_settings(array $settings)
  • nexus_system_timezone_name()
  • nexus_display_timezone_name()
  • nexus_cron_timezone_name()
  • module_debug_enabled(string $module)
  • module_debug_push(string $module, array $entry)
  • module_debug_clear(string $module)

Regel fuer neue Module:

• Keine Zeitzone wie Europe/Berlin hart im Modul als Standard erzwingen, wenn dafuer ein globaler Nexus-Default existiert.
• Fuer Anzeige-/Formatierungslogik nach Moeglichkeit nexus_display_timezone_name() nutzen.
• Fuer Cron-Fallbacks nach Moeglichkeit nexus_cron_timezone_name() nutzen.

UTC-Speicherregel (VERBINDLICH):

• Zeitzonen-Einstellungen haben keinen Einfluss auf das Speicherformat von Zeitwerten in der Datenbank.
• Zeitwerte sollen projektweit intern immer in UTC gespeichert werden.
• Anzeige-Zeitzonen dienen nur der Darstellung fuer Benutzer.
• Cron-Zeitzonen dienen nur der lokalen Auswertung von Zeitplaenen und Faelligkeiten.
• Beim Einlesen lokaler Eingaben muss vor dem Speichern nach UTC normalisiert werden.
• Beim Anzeigen gespeicherter Werte muss von UTC in die jeweils wirksame Anzeige-Zeitzone umgerechnet werden.
• Neue Module duerfen keine lokalen Zeitzonen direkt in Datenbank-Zeitspalten persistieren.

10. Globales Debug-System

• Das Debug-Popup ist eine globale Infrastruktur aus dem zentralen Layout.
• Aktivierung bleibt jedoch pro Modul ueber debug_enabled im Modul-Setup.
• Das Debug-Symbol darf nur sichtbar sein, wenn fuer das aktuelle Modul Debug aktiv ist.
• Module sollen keine eigene separate Debug-Oberflaeche bauen, wenn der globale Debug-Stream genutzt werden kann.

11. Sicherheits-/Netzwerk-Constraints

• Zugriff im Heimnetz (192.168.178.0/24) per Nginx begrenzt.
• SSH-Hosts nur Heimnetz.

12. Pi Control Besonderheiten (konkret)

• Worker/Jobs unter /tools/pi_control/
• Check-Updates & Cron nutzen die gleichen SSH-Routinen.
• Host-Karten, Befehle und Konsole sind UI im Modul.
• Update/Upgrade-Checks liefern Debug-Ausgaben, die als Tooltip oder Debugzeile angezeigt werden.

13. Zusammenfassung (kurz) Nexus ist modular, mit strikter Trennung zwischen globalem Layout und modulspezifischem Code. Staging/Live haben eigene /app//config-Strukturen; /config/ im Repo wird beim Deployment kopiert. Modul-Assets gehören ausschließlich in den Modul-Ordner und werden dort geladen.

14. Nexus-Kerngerüst und Dashboard-Zielbild (VERBINDLICH)

• Der aktuelle Ausbauschritt betrifft das generelle Nexus-System, nicht die bestehenden Fachmodule.
• Bestehende Module sind funktional und strukturell zunächst ausgenommen und dürfen durch Arbeiten am Kerngerüst nicht beeinträchtigt werden.
• Neue Kernfunktionen müssen deshalb so eingeführt werden, dass sie parallel zum bestehenden Modulsystem laufen können.
• Zielbild ist ein Nexus-Grundsystem mit flexiblen Benutzer-Dashboards, Integrationen und datengetriebenen Seitenmodulen.

Produktprinzip:

• Nexus ist nicht nur Modul-Launcher, sondern ein persönliches und gruppenfähiges Dashboard-System.
• Benutzer sollen eigene Dashboards anlegen, anordnen und konfigurieren können.
• Inhalte auf Dashboards sollen aus drei Quellen kommen können:
  • interne Nexus-Funktionen
  • externe Integrationen
  • einfache Seitenmodule ohne eigene Modul-Implementierung

Abgrenzung zu bestehenden Modulen:

• Das bestehende Verzeichnis /modules/<modul>/ bleibt das Zuhause klassischer Nexus-Module.
• Das neue Dashboard-System ist ein zusätzliches globales Kernsystem.
• Ein Dashboard-Widget darf Daten aus einem Modul anzeigen, aber das Dashboard-System darf keine Modulstruktur voraussetzen oder überschreiben.
• Neue Kernfunktionen müssen ohne Umbau bestehender Module lauffähig sein.

15. Neue globale Kernbausteine (VERBINDLICH)

• Dashboard
  • Eine benutzerspezifische oder freigegebene Übersichtsseite.
  • Ein Benutzer kann mehrere Dashboards besitzen.
  • Ein Dashboard kann als Standard-Dashboard markiert sein.
• Dashboard-Element
  • Ein platzierbares Objekt innerhalb eines Dashboards.
  • Eigenschaften sind mindestens Typ, Position, Größe, Sichtbarkeit und Konfiguration.
• Widget-Typ
  • Beschreibt, welche Art Element gerendert wird.
  • Beispiele:
    • Kennzahl
    • Link-/Bookmark-Gruppe
    • iFrame/Webseite
    • Integrationsstatus
    • Modulansicht im Kleinformat
• Integration
  • Zentrale Anbindung an ein externes System.
  • Beispiele:
    • Home Assistant
    • Pi-hole
    • Proxmox
    • Docker
    • Arr-Tools
• Seitenmodul
  • Ein datengetriebenes, on-the-fly angelegtes Modul ohne eigenen Code-Ordner unter /modules/.
  • Typische Verwendung:
    • externer Link
    • eingebettete Webseite
    • einfache Startseite für ein Tool

16. Anforderungen an Benutzer-Dashboards

• Jeder Benutzer soll mehrere eigene Dashboards anlegen können.
• Jedes Dashboard braucht mindestens:
  • Name
  • Slug oder technische ID
  • Eigentümer
  • Sichtbarkeit
  • Sortierung
  • optional Standardstatus
• Dashboards sollen perspektivisch auch teilbar sein:
  • privat
  • gruppenbasiert
  • optional global sichtbar
• Ein Benutzer soll seine Dashboards selbst umsortieren, umbenennen, duplizieren und löschen können.
• Dashboard-Konfigurationen müssen datenbankbasiert gespeichert werden, nicht in Moduldateien.

17. Anforderungen an Dashboard-Layout und Editor

• Dashboards müssen vom Benutzer flexibel bearbeitet werden können.
• Jedes Dashboard-Element braucht mindestens:
  • Spaltenbreite
  • Höhe oder Zeilenspanne
  • Position im Grid
  • gerätespezifische Layoutdaten, sobald Mobile/Desktop getrennt unterstützt werden
• Der Editor soll ein frei konfigurierbares Grid unterstützen.
• Größen und Positionen müssen pro Element speicherbar sein.
• Ein Wechsel zwischen Anzeige-Modus und Bearbeiten-Modus ist vorzusehen.
• Das Layout-System dieses Editors ist globales Nexus-Kerngerüst und darf nicht in einzelnen Modulen dupliziert werden.

18. Integrationen als globales Kernsystem

• Integrationen sind keine Module und keine Widgets, sondern eine eigene Systemschicht.
• Eine Integration stellt Verbindung, Zugangsdaten, Basis-URL und technische Einstellungen für ein Fremdsystem bereit.
• Widgets oder Seitenmodule greifen nicht direkt auf Rohkonfigurationen zu, sondern auf eine definierte Integration.
• Zugangsdaten müssen zentral und getrennt von Widget-Konfigurationen gespeichert werden.
• Eine Integration soll mehrfach anlegbar sein, z.B. mehrere Home-Assistant- oder Pi-hole-Instanzen.
• Integrationen müssen benennbar und für Benutzer oder Gruppen freigebbar sein.

19. Seitenmodule on the fly

• Ein Seitenmodul ist ein vom Benutzer oder Administrator angelegtes Objekt ohne eigenen Programmcode.
• Seitenmodule sind Teil des Nexus-Kerngerüsts und nicht Teil des klassischen Modulordners.
• Ein Seitenmodul kann mindestens folgende Typen haben:
  • link
  • iframe
  • bookmark_group
  • external_status
• Seitenmodule sollen in Dashboards eingebunden werden können.
• Seitenmodule sollen optional auch in der allgemeinen Nexus-Übersicht auftauchen können.
• Seitenmodule dürfen keine globale CSS- oder Layoutlogik mitbringen; sie müssen auf dem zentralen Dashboard-/Widget-System aufsetzen.

20. V1-Datenmodell für das Kerngerüst

• Für das generelle Nexus-System sollen neue zentrale Tabellen vorgesehen werden.
• Empfohlene V1-Struktur:
  • nexus_dashboards
    • Dashboard-Metadaten
  • nexus_dashboard_items
    • platzierte Elemente pro Dashboard
  • nexus_integrations
    • technische Integrationen und Verbindungsdaten
  • nexus_page_modules
    • on-the-fly angelegte Seitenmodule
  • nexus_dashboard_shares
    • optionale Freigaben für Benutzer oder Gruppen
• JSON-Konfigurationen sind für flexible Widget- oder Layoutoptionen erlaubt, aber Kerneigenschaften wie Eigentümer, Typ, Position und Sichtbarkeit sollen eigene Spalten behalten.

21. Kollisionsschutz zu Modulen (VERBINDLICH)

• Änderungen am Nexus-Kerngerüst dürfen nicht voraussetzen, dass bestehende Module sofort migriert werden.
• Neue Tabellen, Services und Seiten müssen unter globalen Namen aufgebaut werden, nicht unter einem Modulpräfix.
• Bestehende Modulrouten, Modul-Assets und Modul-Setups dürfen durch neue Dashboard-Funktionen nicht ersetzt werden.
• Integrationen sind global zu denken und dürfen nicht als versteckte Modul-Features in einzelne Module eingestreut werden.
• Wenn ein bestehendes Modul später Widgets für Dashboards anbietet, muss das über definierte Adapter oder Provider geschehen, nicht über direkte Eingriffe in das Modul-Layout.

22. Empfohlene Umsetzungsreihenfolge für das Kerngerüst

• Phase 1:
  • zentrale Begriffe und Datenmodelle festlegen
  • globale Tabellen für Dashboards, Dashboard-Elemente, Integrationen und Seitenmodule einführen
  • globale Seiten für Dashboard-Verwaltung anlegen
• Phase 2:
  • erstes Dashboard pro Benutzer
  • einfacher Grid-Editor
  • erste Widget-Typen link, iframe, bookmark_group
• Phase 3:
  • Integrationsverwaltung
  • erste Integrationsadapter, z.B. Home Assistant
  • widgetfähige Abfrage von externen Daten
• Phase 4:
  • Freigaben, Gruppenrechte, Dashboard-Duplikate
  • spätere optionale Anbindung bestehender Module über definierte Widget-Provider