nexus/NEXUS_SYSTEM.md

Projektkontext: Nexus-System

1) Projekt-Zweck und Ziel
- Nexus ist ein zentrales, webbasiertes Admin-Interface zur Steuerung einer dynamischen IT-Infrastruktur.
- Module kapseln fachliche Funktionen, das Nexus-System stellt das globale Grundgerüst bereit.
- Das generelle Nexus-System wird unabhängig von den bestehenden Fachmodulen weiterentwickelt.

2) Umgebungen und Domains
- Live: `nexus.kusche.berlin`
- Staging: `staging.nexus.kusche.berlin`

Container- und 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/<env>/config` kopiert
- wichtig: im laufenden Container existiert `/app/config/` nicht, sondern nur `/app/live/config` und `/app/staging/config`

3) Verzeichnisstruktur
- `/public/` -> Web Root mit globalen Assets
- `/api/` -> Backend- und API-Endpunkte
- `/src/` -> PHP-Kernklassen und Utilities
- `/tools/` -> CLI, Worker und Jobs
- `/config/` -> Umgebungs-Configs
- `/modules/<modul>/` -> klassische Nexus-Module
- `/partials/structure/` -> Header, Footer, Menüs
- `/partials/landingpages/` -> komplette Seitenlayouts
- `/debug/` -> Custom Logs

4) Code-Änderungen nach Scope
- globale Layouts: `/partials/structure/` und `/public/assets/css/app.css`
- Konfigurationslogik: nur wenn nötig `/config/` und `/src/`
- Modul-Aufgaben: nur `/modules/<modul>/` und gegebenenfalls `/tools/<modul>`

5) 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` oder `Nexus Übersicht`
- `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`

Globale Struktur:
- zuerst Seitenheader-Box
- danach Submenü-Box
- danach Bereichs-Boxen und/oder Karten-Boxen je nach Seite

Layout-Regeln:
- vertikale Abstände zwischen `main-header-box`, `submenu-box` und den ersten Folge-Boxen müssen 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 dürfen keinen zusätzlichen `margin-top` oder Sonder-Gap erzeugen, der den Abstand nach dem Submenü verändert
- bei Layout-Reviews ist explizit zu prüfen, ob `Main-Header -> Submenü -> erste Section/Card` optisch denselben Rhythmus hat wie auf Referenzseiten
- die Optik der Submenü-Aktionsbuttons kommt ausschließlich aus dem globalen CSS

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

6) Nexus-Kerngerüst
- 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 parallel zum bestehenden Modulsystem eingeführt werden.
- 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 Verzeichnis `/modules/<modul>/` bleibt das Zuhause klassischer Nexus-Module
- das Dashboard-System ist ein zusätzliches globales Kernsystem
- neue Kernfunktionen müssen ohne Umbau bestehender Module lauffähig sein

7) Globale Zeitzonen-Logik
- globale Nexus-Einstellungen liegen unter `/settings`
- dort werden zentral gepflegt:
  - `Anzeige-Zeitzone`
  - `Standard-Zeitzone für Crons`

Regeln:
- ohne Custom bei der Anzeige-Zeitzone wird die System-Zeitzone verwendet
- die aktive Anzeige-Zeitzone soll angezeigt werden
- die Standard-Zeitzone für Crons ist der globale Default für Modul-Crons
- Module dürfen diese Zeitzone im Setup übersteuern
- einzelne Cron-Einträge dürfen sie ebenfalls übersteuern

UTC-Speicherregel:
- Zeitwerte sollen projektweit intern immer in `UTC` gespeichert werden
- Anzeige-Zeitzonen dienen nur der Darstellung für Benutzer
- Cron-Zeitzonen dienen nur der lokalen Auswertung von Zeitplänen und Fälligkeiten
- 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

8) Globales Debug-System
- das Debug-Popup ist eine globale Infrastruktur aus dem zentralen Layout
- die Aktivierung bleibt pro Modul über `debug_enabled` im Modul-Setup steuerbar
- das Debug-Symbol darf nur sichtbar sein, wenn für das aktuelle Modul Debug aktiv ist
- Module sollen keine eigene separate Debug-Oberfläche bauen, wenn der globale Debug-Stream genutzt werden kann

9) Sicherheits- und Netzwerk-Constraints
- Zugriff im Heimnetz `192.168.178.0/24` per Nginx begrenzt
- SSH-Hosts nur Heimnetz