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