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. Sicherheits-/Netzwerk-Constraints

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

9. 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.

10. 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.