From 88732a8ae77518a6c3041613bd134839c8ed2de4 Mon Sep 17 00:00:00 2001
From: madgerm <madgerm@msn.com>
Date: Tue, 3 Feb 2026 01:38:03 +0100
Subject: [PATCH] Document architecture and permissions in SSOT

---
 docs/game_rulebook.md | 132 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 131 insertions(+), 1 deletion(-)

diff --git a/docs/game_rulebook.md b/docs/game_rulebook.md
index ef15d22..19fd7e8 100644
--- a/docs/game_rulebook.md
+++ b/docs/game_rulebook.md
@@ -380,5 +380,135 @@ Optional zusätzlich: `upkeep` (consume) als natürliche Bremse, statt Hardcaps.
 
 ---
 
-## 13) Decision Log
+
+---
+
+## 13) Architektur-Pflichten: Modularität wie Drupal (Slim-Backend)
+
+### 13.1 Grundsatz: Alles ist ein Modul
+Das Projekt wird **modular** aufgebaut. Jede fachliche Domäne liegt in einem eigenen Modul.
+Beispiele (nicht abschließend):
+- `Module\Auth` (Login/Registrierung/Sessions)
+- `Module\Users` (Profile, Gruppen)
+- `Module\Permissions` (Rechte/Policies/Middleware)
+- `Module\Blueprints` (Baukasten: Blueprints, Taxonomie)
+- `Module\PlanetGenerator` (Planetklassen, Generator, Seeds)
+- `Module\Economy` (Ressourcen-Tick, Multiplikatoren)
+- `Module\BuildQueue` (Bauzentren, Jobs, Finalize)
+- `Module\Universe` (Space Objects, Koordinaten, Generator-Admin)
+- `Module\Admin` (Admin UI/Tools, sofern getrennt gewünscht)
+
+**Pflicht:** Neue Features müssen einem Modul zugeordnet werden (oder neues Modul erstellen).
+Keine „God-Classes“ im globalen Namespace.
+
+### 13.2 Technische Leitlinien (Slim + PSR)
+Backend basiert auf **Slim** und PSR-Standards:
+- PSR-4 Autoloading (Composer)
+- PSR-7 Request/Response
+- PSR-15 Middleware
+- PSR-11 Container (DI)
+
+**Modulstruktur (Empfehlung):**
+Jedes Modul kann enthalten:
+- `Routes.php` (Registriert Endpoints)
+- `Controller/` (Request-Handler)
+- `Service/` (Business-Logik)
+- `Domain/` (Entities/Value Objects)
+- `Repo/` (DB Zugriff)
+- `Policy/` (Permission Checks)
+- `Migrations/` (optional; oder zentral, aber mit Modul-Prefix)
+- `Tests/` (unit + integration)
+
+### 13.3 Routing-Pflicht
+- Jedes Modul registriert seine Routen selbst (z.B. `Module\X\Routes::register($app)`).
+- Jede Route muss:
+  1) Auth-Middleware (wenn nötig)
+  2) Permission-Middleware (wenn nötig)
+  3) Input-Validation (Schema)
+  enthalten.
+
+### 13.4 Server-Authority-Pflicht
+Auch wenn UI Buttons versteckt werden:
+- **Die Server-API ist die letzte Instanz.**
+- Jede kritische Aktion muss serverseitig Permissions prüfen.
+
+---
+
+## 14) Permission-System (feingranular + negative permissions)
+
+### 14.1 Ziel
+Ein Drupal-artiges, feingranulares System:
+- Permissions sind **Strings**
+- gehören logisch zu einem Modul
+- steuern UI (Knöpfe/Seiten) und API (Actions)
+- unterstützen **negative Permissions** (Deny/Override pro User)
+
+### 14.2 Permission-Namensschema (Pflicht)
+Permission Keys verwenden das Schema:
+- `<module>.<area>.<action>`
+
+Beispiele:
+- `planet.admin.generate`
+- `planet.admin.regen`
+- `planet.public.view`
+- `blueprints.admin.add`
+- `blueprints.public.suggest`
+- `forum.public.read`
+- `forum.public.write`
+
+**Pflicht:** Jede Permission wird einem Modul zugeordnet und im Modul registriert (z.B. `Module\PlanetGenerator\Permissions::definitions()`).
+
+### 14.3 Rollen/Gruppen + User Overrides
+Es gibt:
+- **Roles/Groups** (Benutzergruppen): erhalten allow-Permissions
+- **User Overrides**: erlauben explizit `allow` oder `deny` pro Permission
+
+**Regel der Auswertung (Pflicht, stabil):**
+1) Wenn User eine **explicit deny** für Permission hat → **verboten**
+2) Sonst wenn User eine **explicit allow** hat → erlaubt
+3) Sonst wenn eine seiner Rollen die Permission erlaubt → erlaubt
+4) Sonst → verboten
+
+**Deny gewinnt immer**, außer bei einem optionalen Sonderfall:
+- `system.superadmin` (wenn aktiviert) kann deny ignorieren (SSOT-Default: Superadmin existiert, aber nur manuell setzbar).
+
+### 14.4 Negative Permissions (Beispiele)
+- Gruppe „Spieler“ hat `forum.public.read` und `forum.public.write`
+- User spammt: Admin setzt User Override `deny forum.public.write`
+→ User kann weiter lesen, aber nicht schreiben.
+
+Genauso für:
+- Vorschläge neuer Gebäude: `blueprints.public.suggest`
+- Chat/PM: `comms.public.send`
+
+### 14.5 Permission-Middleware (Pflicht)
+Jede geschützte Route nutzt Permission Middleware, z.B.:
+- `requirePermission('planet.admin.generate')`
+
+UI darf Buttons nur zeigen, wenn:
+- `can(user, permission)` true
+Aber: UI ist nur Komfort. Server prüft immer.
+
+### 14.6 Datenmodell (Minimal)
+Empfohlenes DB-Modell:
+- `roles (id, key, name)`
+- `permissions (id, key, module, description)`
+- `role_permissions (role_id, permission_id)`  (allow-liste)
+- `user_roles (user_id, role_id)`
+- `user_permission_overrides (user_id, permission_id, effect)`  
+  - `effect` in `{allow, deny}`
+
+Optional:
+- Cache-Tabelle oder Cache-Layer für „effective permissions“ pro User (Performance).
+
+### 14.7 Auditing (Empfehlung)
+Für Admin-Aktionen (z.B. Universe regen) sollte es ein Audit-Log geben:
+- `audit_log (who, what_permission, action, target, at, metadata)`
+
+---
+
+
+## 15) Decision Log
 - [2026-02-03] v1.0 erstellt: Baukasten-Blueprint-System + Planet-Generator (Constraints+Budget) + Build-Center-Queues + destroyable Flag + Auto-Cost Prinzip.
+
+- [2026-02-03] v1.1 ergänzt: Slim-Modul-Architektur + Drupal-artiges Permission-System inkl. deny Overrides.