Interactive Classroom

Interactive Classroom ist eine Mehr-Service-Anwendung für digitale Kurse mit:

Login, Registrierung und Gastzugang
JWT-basierter Authentifizierung mit Refresh-Token
Kursen (Environments) und darin enthaltenen Sessions
kollaborativem Whiteboard mit Hocuspocus und Y.js
Session- und Board-Realtime
persistenter Speicherung in PostgreSQL

Schnellstart

Ein frischer Clone kann lokal direkt gestartet werden:

macOS mit Colima: ./scripts/start.sh
Linux / Windows / Docker Desktop: docker compose up --build

Danach ist die Anwendung unter http://localhost erreichbar.

Typische Entwicklungs-URLs:

App: http://localhost
Traefik-Dashboard: http://localhost:8080
Collab-Health: http://localhost:1234/health
pgAdmin: http://localhost:5050

Optional:

.env.example nach .env kopieren, falls du Defaults überschreiben willst
ohne .env funktionieren die lokalen Dev-Defaults bereits

Diagramme

Zusätzliche Architektur- und Ablaufbilder liegen im Ordner images/ und sind auch direkt im README eingebunden:

Projektarchitektur: images/PROJEKT_ARCHITEKTUR.svg
JWT-/Access-Flow: images/jwt-auth-flow.svg
Datenbankübersicht: images/liveclass_board_database.svg

Was aktuell vorhanden ist

Der aktuelle Stand ist kein reines Backend-Projekt mehr, sondern ein komplettes System mit Frontend, API, Realtime und Whiteboard.

Frontend

Das React-Frontend in apps/web enthält aktuell:

Login-Seite mit drei Modi:
- Anmelden
- Registrieren
- Gastzugang
geschützte Routen für Dashboard und Board
automatischen Silent-Login beim App-Start über Refresh-Token
Dashboard für:
- eigene Kurse anzeigen
- Kurs erstellen
- Kurs per Code beitreten
- Sessions pro Kurs anzeigen
- Sessions öffnen, löschen oder verlassen
Board-Seite für:
- Session- und Kurs-Kontext anzeigen
- Shared Boards und persönliche Boards nutzen
- Mitgliederliste und aktives Mitglied anzeigen
- Session öffnen und schließen
- aktives Mitglied manuell oder zufällig setzen
- Board als persönliche Kopie übernehmen
- PDF-Export
- QR-Code zum Beitritt
- Zoom, Undo, Redo
- Bilder einfügen
- Mehrseiten-Notizbuch pro Board
- Seiten anlegen und löschen
- Hintergrundtyp und Ausrichtung pro Board / Seite

Backend / API

Die Express-API in apps/api enthält aktuell:

Authentifizierung
JWT-Ausgabe für API und Collab-Zugriff
Refresh-Token-Verwaltung in PostgreSQL
Kurs-/Environment-Verwaltung
Session-Verwaltung
Realtime-Stream für Session-Updates
Berechnung und Synchronisation von Board-Schreibrechten
Verwaltung von Shared Boards und persönlichen Board-Kopien

Whiteboard / Realtime

Der Collab-Service in apps/collab enthält aktuell:

Hocuspocus WebSocket-Server
Y.js-Synchronisation
serverseitige JWT-Prüfung für Board-Dokumente
Snapshot-Persistenz in PostgreSQL
relationale Projektion für Board-Daten
Redis-Backplane für verteilte Kollaboration

Architektur

Services

apps/web: React/Vite-Frontend
apps/api: Express-API für Auth, Kurse, Sessions und Session-Realtime
apps/collab: Hocuspocus/Y.js-Service für das Whiteboard
db: PostgreSQL
redis: Realtime-Backplane für Hocuspocus
traefik: Reverse Proxy
migrate: Prisma-Migrationen beim Start
pgadmin: optionale DB-Oberfläche für Entwicklung

Laufzeitbild

Zusätzlich zum Mermaid-Überblick gibt es eine visuelle Gesamtübersicht als SVG:

flowchart LR
    Browser -->|HTTP| Traefik
    Browser -->|REST + Stream| API
    Browser -->|WS Y.js| Collab

    Traefik --> API1[api-1]
    Traefik --> API2[api-2]
    Traefik --> WEB[web]

    API1 --> Postgres[(PostgreSQL)]
    API2 --> Postgres
    API1 -->|LISTEN/NOTIFY| Postgres
    API2 -->|LISTEN/NOTIFY| Postgres

    Collab --> Postgres
    Collab --> Redis[(Redis)]

Authentifizierung

Die Anwendung verwendet ein Access-/Refresh-Token-Modell:

POST /api/auth/login, register oder guest liefern ein accessToken
der Access Token wird im Frontend im Zustand gehalten
der Refresh Token wird serverseitig als HttpOnly-Cookie gesetzt
beim Start der App wird POST /api/auth/refresh aufgerufen
bei 401 versucht das Frontend automatisch genau einen Refresh und wiederholt den Request

Das bedeutet:

API-Aufrufe laufen mit Authorization: Bearer <token>
der Benutzer bleibt nach einem Reload eingeloggt, solange der Refresh-Token gültig ist
Logout widerruft den Refresh-Token und leert die Session im Frontend

Der Ablauf ist zusätzlich als Diagramm dokumentiert:

Fachmodell

Kurse / Environments

Ein Environment ist der übergeordnete Kursraum.

Ein Environment hat:

einen eindeutigen code
einen Titel
optionale Bild-URL
Rollen- und Join-Einstellungen
Mitglieder
Board-Templates
mehrere Sessions

Sessions

Eine Session ist eine konkrete Durchführung innerhalb eines Kurses.

Eine Session hat:

einen eindeutigen code
einen Status: OPEN, CLOSED, ENDED
Mitglieder
ein Host-Mitglied
optional ein aktives Mitglied
Spaces und Boards

Boards

Die Board-Struktur ist inzwischen deutlich größer als in der alten README:

pro Session gibt es Shared-Bereiche
Teilnehmer können persönliche Board-Kopien besitzen
Boards haben Metadaten wie:
- documentName
- orientation
- backgroundTemplate
- width
- height
innerhalb eines Boards existiert im Frontend ein Mehrseiten-Notizbuch
Y.js-Zustand wird in board_documents gespeichert
lesbare Projektionen liegen in relationalen Tabellen

Rechtemodell

Session-Schreibrechte

Im Shared-Bereich gilt aktuell:

die Session muss OPEN sein
der Host darf schreiben
optional darf genau ein aktives Session-Mitglied schreiben

Diese Regel wird doppelt abgesichert:

in der API für Status, Antwortdaten und UI
im Collab-Service direkt vor eingehenden Y.js-Updates

Persönliche Boards

Persönliche Boards sind an ein Session-Mitglied gekoppelt. Dort arbeitet der Besitzer in seinem eigenen Bereich. Shared Boards können außerdem als persönliche Kopie übernommen werden.

Realtime

Session-Realtime

Session-Daten laufen nicht über Y.js, sondern über einen API-Stream:

sequenceDiagram
    participant Browser
    participant API
    participant Postgres

    Browser->>API: GET /api/sessions/:code/stream
    API->>Browser: initiales Session-Snapshot
    API->>Postgres: LISTEN session_updates
    Postgres-->>API: NOTIFY
    API-->>Browser: neues Session-Snapshot

Board-Realtime

Das Whiteboard selbst läuft über Hocuspocus und Y.js:

sequenceDiagram
    participant Browser
    participant Collab
    participant Redis
    participant Postgres

    Browser->>Collab: WebSocket connect + JWT
    Collab->>Postgres: lade Snapshot aus board_documents
    Collab->>Redis: verteile Y.js-Updates
    Browser->>Collab: Zeichnen / Bild / Seiten-Änderung
    Collab->>Postgres: speichere Snapshot
    Collab->>Postgres: aktualisiere Projektion

Datenbank

Die alte Datenbankbeschreibung im README wurde ausgelagert, weil das Modell inzwischen deutlich umfangreicher ist.

Die aktuelle Dokumentation findest du hier:

Sie enthält:

alle Tabellen
Spalten
Enums
Foreign Keys
wichtige Constraints
Hinweise für UML / ERD

Zusätzlich gibt es eine visuelle Datenbankübersicht:

API-Überblick

Auth

POST /api/auth/login
POST /api/auth/register
POST /api/auth/guest
POST /api/auth/refresh
POST /api/auth/logout
GET /api/auth/me

Environments

GET /api/environments
POST /api/environments
POST /api/environments/join/:code
PATCH /api/environments/:environmentId
POST /api/environments/:environmentId/templates
PATCH /api/environments/:environmentId/templates/:templateId
PATCH /api/environments/:environmentId/members/:userId
DELETE /api/environments/:environmentId

Sessions

GET /api/sessions
POST /api/sessions
PATCH /api/sessions/:sessionId
POST /api/sessions/:sessionId/boards
PATCH /api/sessions/:sessionId/boards/:boardId
DELETE /api/sessions/:sessionId/boards/:boardId
GET /api/sessions/:code
GET /api/sessions/:code/stream
POST /api/sessions/:code/join
POST /api/sessions/:sessionId/boards/:boardId/copy-personal
POST /api/sessions/:sessionId/open
POST /api/sessions/:sessionId/close
POST /api/sessions/:sessionId/leave
DELETE /api/sessions/:code
POST /api/sessions/:sessionId/active-member

Frontend-Struktur

Die UI ist aktuell in drei Hauptseiten aufgeteilt:

apps/web/src/pages/
  LoginPage/
    LoginPage.jsx
    LoginPage.css
  DashboardPage/
    DashboardPage.jsx
    DashboardPage.css
  BoardPage/
    BoardPage.jsx
    BoardPage.css

Weitere wichtige Frontend-Dateien:

apps/web/src/App.jsx: Routing und Silent-Login beim Start
apps/web/src/store/authStore.js: Access Token und User-State
apps/web/src/lib/api.js: API-Wrapper mit Auto-Refresh bei 401
apps/web/src/hooks/useYjs.js: Y.js-Integration für Pages, Elemente, Undo/Redo und Sync

Wichtige Tabellen

Der aktuelle Kern der Datenbank besteht aus:

users
user_auth_providers
refresh_tokens
environments
environment_memberships
environment_board_templates
sessions
session_members
session_turn_history
session_events
spaces
boards
board_elements
board_write_access
board_events
board_documents

Entwicklungsnotizen

PostgreSQL ist die zentrale Persistenz für Fachdaten und Board-Snapshots.
Redis wird für den verteilten Y.js-/Hocuspocus-Teil verwendet.
Session-Realtime läuft über PostgreSQL LISTEN/NOTIFY.
Der Compose-Stack startet zwei API-Instanzen hinter Traefik.
Das Frontend wird als eigener Service gebaut und über Traefik ausgeliefert.