Statistikportal für einen All-the-Mods-10-Server (Minecraft 1.21.1, NeoForge 21.1) bei Mine-Hoster: Serverstatus mit Live-Ticker, 14 Ranglisten, Spielerprofile mit Verläufen und Aktivitäts-Heatmap, ATM10-Auswertungen (Aktivität je Mod und Bereich, FTB-Quests) und Serverleistung (TPS, Tickdauer, Speicher).

Mine-Hoster (ATM10)                          eigener Server (DMZ, Docker Compose hinter Traefik)
┌───────────────────────┐   HTTPS (signiert)   ┌─────────────────────────────────────────────┐
│ atmstats-Mod          │ ───────────────────▶ │ api     Fastify: Ingest, REST, SSE, Admin   │
│ (nur serverseitig)    │                      │ worker  SFTP-Abgleich, Snapshots, Retention │
└───────────────────────┘                      │ web     Next.js-Dashboard                   │
   ▲ world/stats, ftbquests, logs              │ db      PostgreSQL 16 + tägliches Backup    │
   └──────────── SFTP (Fallback) ◀─────────────┴─────────────────────────────────────────────┘

Inhalt des Repositorys

Ordner	Inhalt
`mod/`	NeoForge-Mod `atmstats` (Java 21): erfasst Ereignisse, puffert sie auf der Festplatte, sendet signiert per HTTPS
`backend/`	API und Worker (TypeScript, Fastify, PostgreSQL)
`web/`	Dashboard (Next.js, TypeScript, Tailwind, Recharts)
`shared/`	Protokoll-Schemas (Zod) und API-Typen, von Backend, Web und Simulator genutzt; Beispiel-Ereignisse in `shared/fixtures/protocol`
`deploy/`	Docker Compose (Traefik-Labels), `.env.example`, Backup-Skript
`tools/`	Simulator für Testdaten, Log-Anonymisierer, RCON-Client für lokale Tests
`docs/`	Architektur, Datenquellen und Einschränkungen, Betrieb

Dokumentation

docs/OPERATIONS.md: Installation auf dem DMZ-Server, Traefik/OPNsense, Mod bei Mine-Hoster einspielen, Backups, Fehlerbilder
docs/DATA-SOURCES.md: welche Statistik woher kommt, wie aktuell sie ist und was nicht erfasst wird
docs/ARCHITECTURE.md: Komponenten, Protokoll, Zuverlässigkeit, Datenmodell
mod/README.md: Mod bauen und konfigurieren
Design und Plan: docs/superpowers/specs/, docs/superpowers/plans/

Lokale Entwicklung

Voraussetzungen: Node 22, Docker, für die Mod JDK 21.

npm install
docker compose -f deploy/docker-compose.test.yml up -d          # Postgres auf localhost:54329

# Backend (eigene Datenbank für die Entwicklung anlegen)
docker exec deploy-db-test-1 createdb -U postgres atm_dev
export DATABASE_URL=postgres://postgres:postgres@localhost:54329/atm_dev
export INGEST_HMAC_SECRET=$(openssl rand -hex 32) NODE_ENV=development
npm run cli -w backend -- token:create                           # Token für Mod oder Simulator
npm run dev -w backend                                           # API auf :3001
npm run dev:worker -w backend                                    # optional: Snapshots, SFTP

# Frontend
npm run dev -w web                                               # http://localhost:3000

# Testdaten
npm run sim -w tools/simulator -- --token <token> --secret $INGEST_HMAC_SECRET --players 6 --minutes 300 --realtime

Tests

npm test -w shared                       # Protokoll-Schemas
npm test -w backend                      # API, Pipeline, Parser, Worker (braucht die Test-Datenbank)
npm test -w web                          # Komponenten und Formatierung
./mod/gradlew -p mod test                # Mod-Kern: Journal, Versand, Signatur, Serialisierung
cd web && npx playwright test            # E2E gegen einen laufenden Stack (E2E_BASE_URL)

Die Mod-Tests prüfen die Java-Serialisierung gegen dieselben Beispiel-Ereignisse, die das Backend validiert, und die HMAC-Signatur gegen denselben Testvektor. So bleiben Mod und Backend kompatibel.