nexus/GENERAL.md

Projektbasis fuer neue Projekte

Dieses Dokument kombiniert die Erklaerung des allgemeinen Projektaufbaus mit einer konkreten Startstruktur fuer neue Projekte. Ziel ist, dass neue Projekte dieselbe technische Basis verwenden und dieselben Regeln fuer Routing, Verzeichnisse, Module, Assets und Konfiguration einhalten.

Grundprinzip

Das Projekt basiert auf einer schlanken PHP-Struktur mit:

• einem zentralen Web-Einstiegspunkt in public/index.php
• einem zentralen Bootstrap in config/fileload.php
• globalen Seiten unter partials/landingpages/
• globalem Layout unter partials/structure/
• optionalen Fachmodulen unter modules/
• globalen Assets unter public/assets/
• einer Deployment-gesteuerten Config-Aufteilung mit config/staging/ und config/prod/

Verbindliche Startstruktur fuer neue Projekte

Die folgende Struktur soll als Basis fuer neue Projekte verwendet werden. Sie beruecksichtigt ausdruecklich auch die Basisverzeichnisse aus .gitlab-ci.yml.

/
|-- .gitlab-ci.yml
|-- GENERAL.md
|-- api/
|   `-- .gitkeep
|-- config/
|   |-- .gitkeep
|   |-- base_db.php
|   |-- config.php
|   |-- fileload.php
|   |-- prod/
|   |   |-- .gitkeep
|   |   |-- db_settings_basic.php
|   |   |-- domaindata.php
|   |   `-- settings.php
|   `-- staging/
|       |-- .gitkeep
|       |-- db_settings_basic.php
|       |-- domaindata.php
|       `-- settings.php
|-- data/
|   `-- .gitkeep
|-- debug/
|   `-- .gitkeep
|-- modules/
|   `-- .gitkeep
|-- partials/
|   |-- landingpages/
|   |   |-- .gitkeep
|   |   `-- index.php
|   `-- structure/
|       |-- .gitkeep
|       |-- layout_end.php
|       `-- layout_start.php
|-- public/
|   |-- .gitkeep
|   |-- .htaccess
|   |-- index.php
|   `-- assets/
|       |-- css/
|       |   |-- .gitkeep
|       |   `-- app.css
|       |-- images/
|       |   `-- .gitkeep
|       `-- js/
|           |-- .gitkeep
|           `-- app.js
|-- src/
|   |-- .gitkeep
|   |-- App/
|   |   |-- .gitkeep
|   |   |-- App.php
|   |   |-- Assets.php
|   |   |-- Config.php
|   |   |-- Database.php
|   |   |-- ModuleManager.php
|   |   `-- functions.php
|   `-- Repository/
|       `-- .gitkeep
`-- tools/
    `-- .gitkeep

Pflichtordner

Diese Ordner muessen als Basis immer vorhanden sein, weil sie entweder vom Projektaufbau oder vom Deployment vorausgesetzt werden:

• api/
• config/
• data/
• debug/
• modules/
• partials/
• public/
• src/
• tools/

Diese Liste entspricht der Deploy-Basis aus .gitlab-ci.yml plus den notwendigen Unterordnern fuer die Anwendung.

Regel fuer leere Ordner

Wenn ein notwendiger Ordner anfangs noch keine echten Dateien enthaelt, muss er eine leere Datei mit dem Namen .gitkeep enthalten. Das gilt insbesondere fuer:

• api/
• data/
• debug/
• modules/
• tools/
• public/assets/images/
• src/Repository/
• weitere leere Unterordner, die im Template bereits vorgesehen sind

Damit bleiben die Verzeichnisse versionierbar und werden beim Kopieren und Deployment nicht versehentlich ausgelassen.

Rollen der wichtigsten Verzeichnisse

public/

public/ ist der Webroot. Hier liegen:

• index.php als zentraler Router
• globale Assets unter public/assets/
• Webserver-Dateien wie .htaccess

src/

src/ enthaelt den PHP-Kern der Anwendung.

• src/App/ fuer App-Klassen, Bootstrap-nahe Logik, Config, Assets, Datenbank, Request, Session und Modulverwaltung
• src/Repository/ fuer Datenzugriffslogik

partials/

partials/ enthaelt globale Templates.

• partials/landingpages/ fuer globale, direkt routbare Seiten
• partials/structure/ fuer das globale Layout

modules/

modules/ enthaelt fachlich getrennte Erweiterungen. Jedes Modul bleibt in seinem eigenen Ordner und kapselt Seiten, Assets, Partials und optionale Bootstrap-Logik.

api/

api/ ist fuer API-Funktionen vorgesehen, falls das Projekt eigene API-Endpunkte anbieten soll. Wenn ein Projekt keine API bereitstellt, kann der Ordner leer bleiben, soll aber als Teil der Basisstruktur dennoch vorhanden sein.

config/

config/ enthaelt den Bootstrap der Konfiguration sowie die umgebungsspezifischen Quellverzeichnisse staging und prod.

tools/

tools/ ist fuer CLI-Skripte, Worker und Hilfsprogramme vorgesehen.

Routing- und Renderstruktur

public/index.php

public/index.php ist der einzige Web-Einstiegspunkt und uebernimmt:

• Laden von config/fileload.php
• Normalisierung des Request-Pfads
• Pruefung optionaler Authentifizierung oder Schutzregeln
• Routing auf globale Seiten unter partials/landingpages/
• Routing auf Modulseiten unter modules/<modul>/pages/
• 404-Behandlung
• Rendern des Inhalts innerhalb des globalen Layouts

Globale Seiten

Globale Seiten liegen unter partials/landingpages/. Das Routing ist dateibasiert, also ohne externen Framework-Router.

Beispiele:

• / -> partials/landingpages/index.php
• /users -> partials/landingpages/users/index.php

Layout

Die globale HTML-Struktur liegt unter partials/structure/.

• layout_start.php oeffnet das Seitenlayout
• layout_end.php schliesst es

Module

Modulrouten folgen dem Schema:

/module/<modulname>
/module/<modulname>/<seite>

Diese Routen verweisen auf Dateien unter:

modules/<modulname>/pages/

Modulstruktur fuer neue Projekte

Wenn ein neues Projekt Module verwendet, sollte jedes Modul nach demselben Muster aufgebaut sein:

modules/<modulname>/
|-- assets/
|   `-- .gitkeep
|-- pages/
|   |-- .gitkeep
|   `-- index.php
|-- partials/
|   `-- .gitkeep
|-- bootstrap.php
`-- module.json

Regeln:

• modulspezifisches CSS und JavaScript bleibt unter modules/<modulname>/assets/
• globale Assets gehoeren nicht in Modulordner
• Modulcode gehoert nicht nach public/assets/
• Seiten eines Moduls liegen unter pages/
• wiederverwendbare Modul-Templates liegen unter partials/

Asset-Struktur

Globale Assets

Projektweite Dateien liegen unter:

• public/assets/css/
• public/assets/js/
• public/assets/images/

Modul-Assets

Modulbezogene Dateien liegen unter:

• modules/<modulname>/assets/

Neue Projekte sollen diese Trennung konsequent beibehalten.

Config-Aufteilung mit staging und prod

Dieser Teil ist fuer neue Projekte verpflichtend.

Quellverzeichnisse im Repository

Im Repository liegen die umgebungsspezifischen Config-Quellen unter:

config/staging/
config/prod/

Darin liegen typischerweise:

• domaindata.php
• settings.php
• db_settings_basic.php

Laufzeitlogik

Die Anwendung selbst laedt zur Laufzeit nicht direkt aus config/staging/ oder config/prod/, sondern aus dem Root von config/, also z. B.:

• config/settings.php
• config/domaindata.php
• config/db_settings_basic.php

config/fileload.php erwartet genau diese Root-Dateien.

Deployment-Regel

Beim Deployment wird die passende Umgebung in das aktive config/-Root kopiert:

1. allgemeine Root-Dateien aus config/ werden bereitgestellt
2. je nach Branch wird die Umgebungsvariante darueberkopiert
3. develop verwendet config/staging/
4. main verwendet config/prod/
5. im Zielsystem gelten die kopierten Dateien danach so, als waeren sie direkt normale Root-Configs

Neue Projekte muessen exakt dieses Prinzip uebernehmen.

Domain-Pflicht fuer neue Projekterstellungen

Neue Projekte duerfen nur erstellt werden, wenn beide Domains vorliegen:

• Live-Domain
• Staging-Domain

Diese Domains muessen in den umgebungsspezifischen Config-Dateien verwendet und automatisch eingetragen werden, insbesondere in:

• config/prod/domaindata.php
• config/prod/settings.php
• config/staging/domaindata.php
• config/staging/settings.php
• .gitlab-ci.yml, falls dort Domainreferenzen oder Umgebungs-URLs hinterlegt sind

Verbindliche Erstellungsregel

Wenn bei der Aufgabenstellung fuer ein neues Projekt keine Domains angegeben werden, muss vor der Projekterstellung explizit nach beiden Werten gefragt werden.

Die Erstellung ist in diesem Fall zu blockieren.

Sie darf erst fortgesetzt werden, wenn beide Angaben vorhanden sind:

1. Live-Domain
2. Staging-Domain

Fehlt mindestens eine der beiden Angaben, muss die Erstellung unterbunden werden mit einem klaren Hinweis, dass die Domains fehlen.

Zusaetzlich gilt:

• Platzhalterwerte fuer Domains duerfen nicht unveraendert uebernommen werden
• insbesondere Werte wie <LIVE_DOMAIN> und <STAGING_DOMAIN> muessen vor der Erstellung durch echte Domainnamen ersetzt werden
• solange einer dieser Platzhalter noch vorhanden ist, muss die Erstellung blockiert werden
• eine Ausfuehrung darf erst erfolgen, wenn beide echten Domainwerte gesetzt wurden

Reset-Regel fuer neue Projekterstellungen

Vor der eigentlichen Erstellung eines neuen Projekts muessen alle bestehenden Dateien und Ordner im Repository entfernt werden, mit genau einer Ausnahme:

• .gitlab-ci.yml

Die bestehende .gitlab-ci.yml bleibt erhalten, weil sie die Deploy-Basis vorgibt. Sie muss jedoch im Zuge der neuen Projekterstellung geprueft und angepasst werden, wenn darin Domainreferenzen, Umgebungs-URLs oder projektspezifische Zielpfade enthalten sind.

Fuer neue Projekterstellungen gilt deshalb verbindlich:

1. vorhandene Projektdateien und Projektordner loeschen
2. .gitlab-ci.yml behalten
3. .gitlab-ci.yml auf alte Domain- oder Projektreferenzen pruefen
4. vorhandene Domainreferenzen in .gitlab-ci.yml auf die neue Live- und Staging-Domain anpassen
5. danach erst die neue Basisstruktur und die neuen Basisdateien erstellen

Mindestinhalt der Config-Dateien

Die folgenden Dateien koennen als Basis aus diesem Projekttyp uebernommen werden und muessen pro neuem Projekt angepasst werden:

• config/fileload.php
• config/config.php
• config/base_db.php
• config/prod/domaindata.php
• config/prod/settings.php
• config/staging/domaindata.php
• config/staging/settings.php

Dabei gilt:

• die allgemeine Config-Logik kann uebernommen werden
• domainspezifische Werte muessen pro Projekt ersetzt werden
• staging und prod muessen immer unterschiedliche Zielwerte bekommen, sofern nicht ausdruecklich anders gefordert

Basisdateien fuer neue Projekte

Neben der Ordnerstruktur werden fuer neue Projekte auch Basisdateien benoetigt, insbesondere im Config-Bereich. Die konkreten Inhalte sind in einer separaten Datei beschrieben:

• BASE_FILES.md

Diese Datei ist dafuer gedacht, nach dem Anlegen eines neuen GitLab-Projekts zusammen mit GENERAL.md in das neue Repository kopiert zu werden, damit die Erstellung der Grundstruktur und der Konfigurationsdateien direkt auf einer klaren Vorlage basiert.

Kurzfassung fuer neue Projekte

Neue Projekte auf dieser Basis verwenden:

• einen zentralen Router in public/index.php
• einen zentralen Bootstrap in config/fileload.php
• globale Seiten in partials/landingpages/
• globale Layout-Dateien in partials/structure/
• optionale Module in modules/
• globale Assets in public/assets/
• modulspezifische Assets in modules/<modulname>/assets/
• eine Deploy-gesteuerte Config mit config/staging/ und config/prod/

Leere Pflichtordner erhalten immer .gitkeep. Eine neue Projekterstellung ist nur zulaessig, wenn sowohl Live- als auch Staging-Domain vorab angegeben wurden.