# GeoGraSim · Sim-Architektur (Codex-Briefing)

## Verzeichnis-Layout (vereinfacht)

```
App/
├── pages/                       ← PHP-Wrapper für jede Sim und jede Top-Level-Route
│   ├── klima-2d.php             ← injiziert __GGS__-Kontext, lädt sims/klima/game-2d.html
│   ├── weltkueche.php           ← analog für Weltküche
│   ├── modul-klima.php          ← „Info-Seite" für das Modul (öffnet aus /teacher)
│   └── _partials/modul_detail.php  ← gemeinsamer Partial für alle Modul-Detail-Seiten
│
├── sims/                        ← die eigentlichen Simulationen
│   ├── klima/
│   │   ├── game-2d.html         ← 2D-Variante
│   │   ├── game-3d.html         ← 3D-Variante
│   │   └── engine.js            ← Engine, deterministisch, kein LLM
│   ├── weltkueche/
│   │   ├── game.html
│   │   ├── assets/data/         ← dishes.json, production-matrix.json, …
│   │   └── scripts/             ← Build-Tools, NICHT zur Laufzeit
│   └── …
│
├── php/
│   ├── api/                     ← JSON-Endpunkte
│   │   ├── live.php             ← Heartbeats + Lehrer-Cockpit
│   │   ├── results.php          ← Auswertung + Benchmark
│   │   ├── glossar.php          ← Begriffs-Lookup
│   │   └── …
│   ├── lib/                     ← Plattform-Code
│   │   ├── Benchmark.php        ← NEU (2026-06-11) — Score-Engine pro Modul
│   │   ├── Country.php          ← Land + Schuljahr + Lehrplan-Logik
│   │   ├── EasyLang.php         ← Leichte-Sprache-Helper
│   │   └── Session.php          ← Cookie-basiert für Schüler:innen
│   └── config/                  ← Constants, BASE_PATH, BASE_URL etc.
│
├── assets/
│   ├── js/
│   │   ├── live-client.js       ← Heartbeat, alle 4 s
│   │   └── glossar-tooltip.js   ← Plattform-Tooltip-Lib
│   └── img/                     ← Glossar-Bilder, Avatare, Card-Images
│
├── teacher.html                 ← Lehrer-Cockpit (SPA-ähnlich)
├── schueler.html                ← Schüler:innen-Dashboard
└── index.php                    ← Front-Controller, leitet auf pages/
```

## Wrapper-Pattern

Jede Sim wird über einen **PHP-Wrapper** geöffnet, nicht direkt als HTML.
Der Wrapper:
1. Setzt Session-Kontext (`__GGS__` mit sessionId, simId, baseUrl, basePath, apiUrl)
2. Lädt die `game.html` der Sim und gibt sie aus
3. Injiziert plattform-eigene Scripts: `live-client.js`, `glossar-tooltip.js`

Beispiel Klima:
```
GET /klima-2d  →  pages/klima-2d.php  →  liest sims/klima/game-2d.html
                                      →  injiziert <script>window.__GGS__ = {...}</script>
                                      →  injiziert live-client.js
                                      →  Echo
```

## Live-Daten-Vertrag

Jede Sim kann optional `window.GGS_LIVE_STATE = function(){return {...};}`
exponieren. Erwartete Plattform-Felder (für die Lehrer-Cockpit-Anzeige):

- `simId: string` — z.B. `'klima'`, `'weltkueche'`, …
- `phase: string` — menschenlesbar, z.B. `'Jahr 12 von 75'`, `'Auftrag 3/8'`
- `progressPct: number` — 0-100, für die generische Fortschritts-Anzeige

Plus sim-spezifische Felder. Beispiele:

| Sim | Sim-spezifische Felder |
|---|---|
| Klima 2D | `temp`, `co2`, `budget`, `floodedPct`, `population`, `seaLevelCm` |
| Heli | `planIndex`, `planTotal`, `planCorrect`, `planAttempts`, `missionId` |
| Weltküche | `ingSolved`, `ingTotal`, `mistakesInDish`, `score`, `dishName` |

## Benchmark-System (neu 2026-06-11)

`App/php/lib/Benchmark.php` enthält pro Sim eine Score-Formel
(`scoreSubmission`) und eine Aggregation pro Schüler:in
(`studentOverall`). Wird aus `live.php` (Cockpit) aufgerufen.

Skala 0–100, max. 3 beste Sessions pro Modul, dann Mittelwert über
alle gespielten Module. **Ist keine Note** — wird als „Benchmark"
bezeichnet, Schüler:innen sehen den Wert nicht direkt.

## Database

MariaDB. Wichtige Tabellen:
- `students` — class-Membership, display_name + username (display_name kann NULL sein!)
- `classes` — join_code, teacher_id
- `student_sessions` — UUID-Cookie-basiert
- `live_sessions` — aktive Heartbeats, gelöscht nach Timeout
- `assessments` — Submissions am Sim-Ende, mit results-JSON + process_log
- `glossar`, `glossar_modules` — Begriffe + Modul-Verknüpfung
- `lehrplan_anchors`, `kompetenzen`, `kompetenz_modules` — Lehrplan-System V1
  (V2-Tabellen sind LEER, bitte ignorieren wenn dir die unterkommen)
- `module_info` — Modul-Stammdaten (Titel, Icon, Status, Sort-Order)

## Was du als Codex NICHT siehst, aber wissen solltest

- Es gibt eine **Meister-Atlas-Instanz** für Server-Konfig — die handelt
  alle Apache/SSL/Cert-Themen. Wenn du etwas am Server findest, ist das
  Meister-Sache, nicht Atlas-Sache.
- **Memory persistent**: Atlas hat Notizen unter
  `C:\Users\herr_\.claude\projects\c--xampp-htdocs-geograsim\memory\`
  die historische Entscheidungen tragen. Wenn dir was komisch vorkommt,
  ist möglicherweise im Memory der Grund dokumentiert.
- **„kein Deploy" aktuell**: Stand 2026-06-10 sagt Thomas, dass alle
  Änderungen lokal bleiben (kein scp auf Prod). Wenn du also etwas
  online testest, das du im Repo nicht findest, ist das Prod-Stand, nicht
  aktueller Code.