Lauschfreunde — Dokumentation

Technische Referenz zum kooperativen Hör-Abenteuerspiel: Architektur, Spielablauf, QR-System, Sprachsynthese-Pipeline, PDF-Generierung und API.

Architektur-Übersicht

Lauschfreunde ist eine React-Single-Page-Application, die das Spiel und den Admin-Bereich in einem gemeinsamen Bundle ausliefert. Sie kommuniziert über eine REST-Schnittstelle mit dem Nexus-Backend — einer Node.js-Anwendung auf Basis von Express, mit eingebetteter SQLite-Datenbank und JWT-basierter Authentifizierung. Als Progressive Web App läuft das Frontend nach dem ersten Laden auch ohne Internetverbindung.

Frontend-Stack

Backend-Stack (Nexus)

Das Nexus-Backend ist eine schlanke Node.js-Anwendung auf einem einzelnen Server — ohne externe Datenbank-Abhängigkeit.

Dateistruktur

Das Frontend ist nach Feature-Bereichen gegliedert: getrennte Verzeichnisse für pages/game/ und pages/admin/, eigene Hooks bündeln die Spiel-Logik, und lib/ kapselt die API-Aufrufe und externen Anbindungen.

Spielablauf

Ein typisches Abenteuer durchläuft die folgenden Phasen:

Zustands-Übersicht

Der Spielzustand wird über Custom Hooks (vor allem useGameState) verwaltet. Die wichtigsten Zustände im Spielverlauf:

QR-System

Payload-Format

Jeder QR-Code enthält einen kompakten Identifikator nach folgendem Schema:

lauschfreunde:<box-slug>:<adventure-slug>:<card-slug>

Der Server liefert über GET /cards/resolve?qr=... die zugehörige Karte samt Audio-URL und Charakter-Zuordnung zurück.

Zwei Scanner parallel

Die App nutzt zwei Scanner-Bibliotheken nebeneinander, um auf möglichst vielen Geräten zuverlässig zu funktionieren:

TTS-Pipeline

Übersicht

Audio lässt sich direkt aus dem Admin-Editor per ElevenLabs erzeugen. Das Ergebnis wird als MP3 im Storage abgelegt und über eine URL mit der jeweiligen Karte oder dem Abenteuer verknüpft. Für produktive Aufnahmen können alternativ fertige MP3-Dateien hochgeladen werden.

Stimmen-Konfiguration

Jeder Charakter bekommt eine eigene Stimme. Die jeweilige Voice-ID wird pro Charakter in der Datenbank hinterlegt und beim Generieren mitgeschickt.

PDF-Generierung (optional — nur für selbst angelegte Editor-Inhalte)

Spielkarten

Für Welten, die im Editor selbst angelegt wurden, erzeugt das Admin-Panel druckfertige A4-PDFs mit den Karten, QR-Codes und Schnittmarken. Bei einem Verlagsprodukt entfällt das — die Box wird mit fertig produziertem Material ausgeliefert.

Urkunden

Nach Abschluss eines Abenteuers können die Kinder eine Urkunde als PDF herunterladen. Sie nennt das gelöste Abenteuer, das Datum und trägt ein Siegel mit Lauschfreunde-Branding.

API Endpoints

Übersicht

Die Nexus REST-API ist in zwei Bereiche aufgeteilt: öffentliche Game-Endpoints (kein Auth) und Admin-Endpoints (Bearer Token). Alle Antworten kommen im Envelope { data: ... }; Fehler als { error: "..." }.

Basis-URL in Produktion: https://cddevapps.com/api/nexus/lauschfreunde

Authentifizierung

Admin-Login über E-Mail + Passwort. Antwort enthält den Bearer Token, der im Frontend in localStorage liegt und bei jedem Admin-Request mitgeschickt wird.

POST /auth/login
Content-Type: application/json

{
  "email": "admin@example.com",
  "password": "***"
}

Response: { "data": { "token": "eyJhbG...", "user": { ... } } }

Spiel-Routen (öffentlich)

Admin: Inhalte verwalten (Bearer Token)

Admin: Uploads und Sprachsynthese (Bearer Token)