Architektur-Übersicht

System-Architektur

Das System besteht aus drei Hauptkomponenten:

1. Frontend (Statische Website)

Technologie: HTML, CSS, JavaScript (Vanilla) Build-System: Node.js mit ESM-Modulen

Struktur

content/
├── globals.json      # Site-Konfiguration (Navigation, Event-Daten, etc.)
├── pages.json        # Seiten-Definitionen
├── *.md             # Markdown-Inhalte
└── *.html           # HTML-Inhalte (Impressum, Datenschutz)

static/
├── assets/          # CSS, JavaScript, Bilder
├── anmeldung/       # PHP: Formular anzeigen (GET)
├── registration/    # PHP: Formular verarbeiten (POST)
└── api/             # PHP: kleine JSON-Endpunkte (z.B. event-date)

Build-Prozess

Das Build-Script (scripts/build.mjs) führt folgende Schritte aus:

1. Markdown → HTML: Konvertiert Markdown-Dateien zu HTML
2. Layout-Generierung: Fügt Header, Navigation und Footer hinzu
3. Asset-Kopierung: Kopiert statische Dateien nach public/
4. Backend-Kopierung: Kopiert Backend-Code nach public/backend/
5. Datenverzeichnis: Erstellt public/data/ für SQLite-Datenbank
6. PHP-Dateien kopieren: Kopiert PHP-Dateien aus static/ nach public/ (z.B. static/anmeldung/index.php → public/anmeldung/index.php)

Content-Management

• globals.json: Zentrale Konfiguration

  • Site-Titel, Navigation
  • Event-Daten (Datum, Ort, Zeit)
  • Organisations-Informationen
  • Social Media Links

• pages.json: Seiten-Definitionen

  • Slug (URL-Pfad)
  • Titel
  • Datei-Referenz
  • Typ (markdown/html)

2. Backend (PHP)

Architektur: MVC-ähnlich mit Repository-Pattern Datenbank: SQLite

Verzeichnisstruktur

zgb-backend/
├── Model/           # Domain-Models
│   ├── Registration.php
│   └── Config.php
├── Repository/      # Datenzugriff
│   ├── RegistrationRepository.php
│   ├── ConfigRepository.php
│   ├── Repository.php (Basis-Klasse)
│   └── Schema/     # SQL-Dateien
│       ├── Config/
│       └── Registration/
├── Service/         # Business-Logik
│   ├── AuthService.php
│   ├── CSRFService.php
│   ├── MailService.php
│   ├── SessionService.php
│   ├── RateLimitService.php
│   ├── LogService.php
│   └── MailQueueWorker.php
└── web/            # Controller/Endpoints
    ├── admin.php
    ├── admin_login.php
    └── ...

Architektur-Pattern

Repository-Pattern:

• Abstraktion der Datenzugriffsschicht
• SQL in separaten Dateien (Schema/)
• Automatische Schema-Initialisierung

Service-Layer:

• AuthService: Authentifizierung und Rate-Limiting
• CSRFService: CSRF-Token-Verwaltung
• MailService: E-Mail-Versand mit Templates
• SessionService: Zentrales, sicheres Session-Setup
• RateLimitService: File-basiertes Rate-Limiting für spezifische Aktionen
• LogService: Strukturiertes Logging für Fehler und Events
• MailQueueWorker: Asynchroner E-Mail-Versand mit Queue-System

Model-Klassen:

• Immutable Value Objects (readonly properties)
• Type-safe mit PHP strict types

3. Datenbank (SQLite)

Datei: public/data/zwergenboerse.db

Tabellen

registrations:

• Anmeldedaten (Name, Adresse, Kontakt)
• Vergebene Nummern
• Zeitstempel

config:

• Anmeldezeitraum (startDate, endDate)
• Nummernbereich (startNumber, maxNumber)
• Event-Datum
• Organisator-E-Mail

Schema-Management

• SQL-Dateien in Repository/Schema/
• Automatische Initialisierung beim ersten Zugriff
• Migrationen durch SQL-Dateien

Datenfluss

Anmelde-Prozess

1. Formular-Anzeige (static/anmeldung/index.php → /anmeldung/)

   • Lädt Konfiguration
   • Prüft Anmeldezeitraum
   • Findet freie Nummer
   • Zeigt Formular

2. Formular-Submission (static/registration/index.php → /registration/)

   • Validierung
   • Duplikat-Prüfung
   • Speicherung in Datenbank
   • Mail-Queue oder Direktversand (User + Organisator)

3. Admin-Verwaltung (admin.php)

   • Konfiguration bearbeiten
   • Anmeldungen exportieren
   • Anmeldungen löschen (außerhalb Zeitraum)

Detail-Flow inkl. Build-/Laufzeit-Pfade: Projekt-Landkarte (Code-getrieben)

Sicherheits-Architektur

Authentifizierung

• Session-basiert
• Passwort-Hash in Datenbank
• Rate-Limiting (5 Fehlversuche → 10 Min. Block)

CSRF-Schutz

• Token-basiert
• Token-Rotation nach erfolgreichen Aktionen
• Prüfung bei allen POST-Requests

Input-Validierung

• Server-seitige Validierung
• HTML5-Validierung im Frontend
• Prepared Statements (SQL-Injection-Schutz)

HTTP-Security-Headers

• X-Frame-Options: SAMEORIGIN
• X-Content-Type-Options: nosniff
• Content-Security-Policy
• Referrer-Policy

Build & Deployment

Build-Prozess

npm run build

Führt aus:

1. Content-Verarbeitung
2. Asset-Kopierung
3. Backend-Kopierung
4. Datenverzeichnis-Vorbereitung

Deployment

• public/ wird auf Server deployed
• PHP muss verfügbar sein
• SQLite-Verzeichnis muss beschreibbar sein
• sendmail/postfix für E-Mail-Versand

Erweiterbarkeit

Neue Seiten hinzufügen

1. Content-Datei in content/ erstellen
2. Eintrag in pages.json hinzufügen
3. Build ausführen

Backend-Funktionen erweitern

1. Model in zgb-backend/Model/ erstellen
2. Repository in zgb-backend/Repository/ erstellen
3. SQL-Schema in Repository/Schema/ hinzufügen
4. Service in zgb-backend/Service/ (falls nötig)
5. Controller in zgb-backend/web/ erstellen