KompetenzHub – Benutzerhandbuch & Installationsanleitung für Schulen 🏫

Stand: Juli 2026 · Sprache: Deutsch Diese Anleitung richtet sich an Lehrpersonen, Schulleitungen und technisch interessierte Personen, die prüfen möchten, ob sich KompetenzHub für ihre Schule eignet – sowie an alle, die die Software selbst betreiben wollen.

Inhaltsverzeichnis

Was ist KompetenzHub?
Für wen ist die Software?
Rollen & Berechtigungen
Schnelleinstieg: Grundbegriffe
Anmeldung, Sprache & Anzeigemodus
Handbuch für Lehrpersonen
Handbuch für Lernende
KI-Funktionen im Detail
Handbuch für die Schuladministration
Installation & Betrieb (technisch)
Konfiguration: Umgebungsvariablen
Produktivbetrieb & Sicherheit
Backup & Wiederherstellung
Aktualisierung & Datenbankmigrationen
Datenschutz
Fehlerbehebung (FAQ)
Glossar
Lizenz
Plugins aktivierenz
Testing
Plugins selbst entwickeln
Mehrere Schulen in einer Instanz (Multi-Mandanten)

1. Was ist KompetenzHub?

KompetenzHub ist eine Web-Plattform zur kompetenzorientierten Beurteilung in der beruflichen Grundbildung (und vergleichbaren Schulformen). Sie bildet das didaktische Konzept einer Kompetenzmatrix digital ab:

Ein Modul (z. B. „Modul 293") besitzt eine Kompetenzmatrix.
Die Matrix besteht aus Kompetenzbändern (Zeilen) und Gütestufen (Spalten: Beginner, Intermediate, Advanced).
Jede Zelle (= Kompetenzfeld) enthält einen Deskriptor im „Ich kann …"-Format.
Zu jedem Feld können Kompetenznachweise hinterlegt werden, die Lernende einreichen (Datei, Link, Text, Screenshot oder ein KI-gestütztes Fachgespräch).
Lehrpersonen bewerten die Einreichungen; ein Dashboard zeigt den Lernfortschritt der Klasse.

Zusätzlich bietet KompetenzHub Lernpfade (empfohlene Reihenfolge), KI-Unterstützung (Bewertungsvorschläge, Feedbacktexte, Übungs-Fachgespräche), Export/Import von Modulen und Klassen sowie ein Schuladmin-Dashboard für die zentrale Verwaltung.

Die Oberfläche ist vollständig mehrsprachig (Deutsch, Französisch, Italienisch, Englisch).

InfoWebseite 🌐

kompetenzhub.ch Hier findest du Infos zu dieser Software

Demoseite 👩🏻‍💻

Demo! Keine persönlichen Daten hochladen ⚠️ Hier gibt es eine Demo welche immer zur vollen Stunde zurückgesetzt wird.

2. Für wen ist die Software?

Zielgruppe	Nutzen
Lehrpersonen 👩‍🏫	Eigene Kompetenzraster erstellen, Nachweise definieren, Einreichungen bewerten, Lernfortschritt im Blick behalten, KI als Assistenz nutzen.
Lernende 👩‍🎓	Übersicht über alle zu erbringenden Nachweise, einfache Einreichung, transparentes Feedback, Üben mit KI.
Schulleitung / Schuladmin 🦸🏻	Zentrale Steuerung: wer darf sich als Lehrperson anmelden, Branding (Logo/Farbe), Sprache, Betrieb/Auslastung, Backups.
IT / Betrieb 🧑‍💻	Selbst-Hosting auf eigener Infrastruktur (Docker), volle Datenhoheit, Standard-Technologien. Optional mehrere Schulen/Abteilungen in einer Instanz (Kapitel 22).

3. Rollen & Berechtigungen

KompetenzHub kennt drei Rollen. Jede Person hat genau eine aktive Rolle pro Schule.

Rolle	Darf …
Lernende:r (LEARNER)	Modulanlässen beitreten, Kompetenzmatrix der eigenen Module ansehen, Nachweise einreichen, Lernpfad verfolgen, mit KI üben, eigene Sprache/Anzeige & optional eigene KI konfigurieren.
Lehrperson (TEACHER)	Module & Matrizen erstellen/bearbeiten, Nachweise definieren, Modulanlässe (Klassen) führen, Einreichungen bewerten, Lernpfade pflegen, KI konfigurieren, Module/Klassen exportieren/importieren. Sieht die eigenen Module/Modulanlässe sowie Modulanlässe, bei denen sie als Co-Leitung eingetragen ist.
Schuladmin (ADMIN)	Alles rund um die Verwaltung: Personen (Lehrpersonen & Lernende), Einladungen/Zugänge, Schul-Einstellungen (Branding, Sprache, Anmelde-Anbieter), Betrieb/Gesundheit, Audit-Log, Backup.

Wichtig (Zugangssteuerung): Wer sich neu anmeldet, wird standardmässig Lernende:r. Lehrpersonen- und Admin-Rechte vergibt ausschliesslich die Schuladmin – über Einladung oder Beförderung (siehe Kapitel 9).

4. Schnelleinstieg: Grundbegriffe

Begriff	Bedeutung
Modul	Fachliche Einheit mit einer Kompetenzmatrix (z. B. „Modul 293 – Webauftritt erstellen").
Kompetenzmatrix	Raster aus Bändern × Gütestufen.
Handlungsziel (HZ)	Lernziel; jedes Band referenziert mind. ein Handlungsziel.
Kompetenzband	Zeile der Matrix (thematischer Strang).
Gütestufe	Spalte: Beginner (B), Intermediate (I), Advanced (A).
Kompetenzfeld	Schnittpunkt Band × Gütestufe.
Deskriptor	„Ich kann …"-Beschreibung eines Feldes.
Kompetenznachweis	Auftrag, den Lernende zu einem Feld einreichen.
Modulanlass	Durchführung eines Moduls mit einer konkreten Klasse (inkl. Beitrittscode).
Co-Leitung	Weitere Lehrperson, die einen Modulanlass mitführt und mitbewertet.
Lernpfad	Empfohlene Reihenfolge der Kompetenzfelder.

5. Anmeldung, Sprache & Anzeigemodus

Anmelden

KompetenzHub wird im Webbrowser geöffnet (Standard-Adresse im Betrieb: die URL Ihrer Schule, lokal http://localhost:3000).

Produktiv: Anmeldung über Microsoft oder Google (Single Sign-On). Welche Anbieter verfügbar sind, legt die Schuladmin fest.
Eigenes KompetenzHub-Konto: Für Personen ohne Microsoft-/Google-Konto kann die Schule einen eigenen Anmelde-Anbieter betreiben (Self-Service-Registrierung mit E-Mail/Passwort). Auf der Anmeldeseite erscheinen dann der Knopf „Mit KompetenzHub-Konto anmelden" und der Link „Jetzt registrieren". Einrichtung siehe Kapitel 10.8.
Entwicklung/Test: ein Dev-Login mit Rollenwahl (Lehrperson / Lernende / Administration) steht zur Verfügung, sofern aktiviert.

Nach der Anmeldung werden Sie automatisch auf die zu Ihrer Rolle passende Startseite geleitet.

📷 _Screenshot: Anmeldeseite mit Microsoft/Google und Dev-Login.

Sprache umstellen

Oben rechts in der Kopfzeile befindet sich ein Sprachauswahl-Menü (DE · FR · IT · EN). Die Wahl wird dauerhaft im Konto gespeichert und bleibt nach dem Abmelden erhalten.

Anzeigemodus (Theme)

Neben der Sprachauswahl lässt sich der Anzeigemodus umschalten: Hell, Dunkel oder Grau. Auch diese Einstellung wird pro Konto gespeichert.

📷 _Screenshot: Kopfzeile mit Sprach- und Theme-Auswahl sowie Nutzer-Menü.

6. Handbuch für Lehrpersonen 👩‍🏫

Nach der Anmeldung als Lehrperson sehen Sie links die Navigation: Dashboard, Module & Matrizen, Modulanlässe, Bewerten, KI-Einstellungen.

6.1 Dashboard

Das Dashboard zeigt pro Modulanlass den Lernfortschritt der Klasse als Heatmap (Lernende × Kompetenzfelder) sowie Kennzahlen (Anzahl Lernende, „zu bewerten", „bewertet", Durchschnittsfortschritt). Ein Klick auf eine Zelle führt direkt zur Bewertung. Zusätzlich zeigt ein kompaktes Diagramm den eigenen Speicherverbrauch – bei gesetzter persönlicher Quota inkl. Fortschrittsbalken (denselben Wert finden Sie auch unter KI-Einstellungen).

📷 _Screenshot: Lehrer-Dashboard mit Fortschritts-Heatmap.

6.2 Module & Matrizen anlegen

Module & Matrizen öffnen → „+ Neues Modul".
Modulnummer und Titel erfassen (optional Beschreibung). Das Modul wird als Entwurf angelegt.
Modul öffnen, um die Matrix zu bearbeiten.

📷 _Screenshot: Modul-Liste mit Kennzahlen.

Handlungsziele

Im Modul-Editor zunächst Handlungsziele anlegen (Code + Beschreibung). Sie lassen sich umsortieren, bearbeiten und löschen. Jedes Kompetenzband muss mindestens ein Handlungsziel referenzieren.

Kompetenzbänder & Deskriptoren

„+ Band hinzufügen": Code (z. B. „A1"), optionale Beschreibung und die referenzierten Handlungsziele wählen. Beim Anlegen entstehen automatisch die drei Felder (B/I/A).
In jeder Zelle auf den Deskriptor klicken und im „Ich kann …"-Format formulieren.
Bänder lassen sich umsortieren und bearbeiten.

📷 _Screenshot: Matrix-Editor mit Bändern, Feldern und Deskriptoren.

Kompetenznachweise definieren

Über die Schaltfläche „+ Nachweis" in einem Kompetenzfeld öffnet sich der Nachweis-Dialog:

Titel und Beschreibung (Rich-Text mit Bildern/Links).
Einreichungsarten für Lernende: Datei, Link, Text, Screenshot, Fachgespräch/Präsentation.
Optionen: erlaubte Dateitypen, max. Grösse, Einfügen (Paste) im Textfeld erlauben/sperren, max. Punkte, Fälligkeitsdatum, Sichtbarkeit.
Optionaler Anhang zum Download (z. B. Aufgabenblatt).

📷 Screenshot: Nachweis-Konfiguration mit Einreichungsarten.

6.3 Lernpfade

Im Modul können Sie unter „Lernpfade" eine empfohlene Reihenfolge der Kompetenzfelder definieren (Felder links hinzufügen, rechts in Reihenfolge bringen). Ein Pfad lässt sich aktiv schalten; Lernende sehen dann eine Zeitachse statt der reinen Matrix.

📷 _Screenshot: Lernpfad-Editor (verfügbare Felder ↔ Reihenfolge).

📷 Screenshot: Lernpfad-Editor (verfügbare Felder ↔ Reihenfolge).

6.4 Modulanlässe (Klassen) führen

Unter Modulanlässe:

Neuen Modulanlass anlegen, einem Modul zuordnen und benennen.
Einen Beitrittscode (bzw. Beitrittslink) erzeugen und an die Klasse weitergeben.
Lernende treten mit dem Code bei und sehen sofort die Matrix und die Nachweise.

Sie sehen Ihre eigenen sowie die Modulanlässe, bei denen Sie als Co-Leitung eingetragen sind (entsprechend markiert), und jeweils nur die zugeordneten Lernenden. Modulanlässe können archiviert (schreibgeschützt) und als ZIP exportiert/importiert werden (inkl. aller Einreichungen, Bewertungen und Zeitstempel).

📷 Screenshot: Modulanlass mit Beitrittscode.

6.5 Co-Leitung (Co-Teaching) 👨‍💼👩‍💼

Ein Modulanlass kann von mehreren Lehrpersonen gemeinsam geführt werden. Im Detailbereich eines Modulanlasses gibt es dafür den Abschnitt „Co-Leitung":

E-Mail-Adresse der gewünschten Lehrperson eingeben und Hinzufügen.
Die Person muss bereits als Lehrperson (oder Schuladmin) an der Schule angemeldet/eingeladen sein.
Die Co-Leitung sieht den Modulanlass ab sofort in ihrem Login (mit der Markierung „Co-Leitung") und kann dessen Einreichungen bewerten, den Fortschritt einsehen, Mitglieder und Beitrittscode verwalten.

Rechteabgrenzung: Nur die besitzende Lehrperson (die den Modulanlass erstellt hat) kann die Co-Leitung verwalten (hinzufügen/entfernen) und den Modulanlass löschen. Co-Leitungen können den Anlass weder löschen noch weitere Co-Leitungen ernennen.

📷 _Screenshot: Abschnitt „Co-Leitung" im Modulanlass.

6.6 Bewerten

Unter Bewerten sehen Sie alle offenen Einreichungen Ihrer Modulanlässe – auch jener, bei denen Sie als Co-Leitung mitwirken:

Einreichung öffnen (Text/Link/Datei/Screenshot ansehen).
Gütestufe, Punkte und Feedback erfassen oder die Einreichung zurückweisen (mit Begründung → Lernende:r kann erneut einreichen).
Eine Historie dokumentiert jede Bewertungsaktion (inkl. der bewertenden Person).
Optional: KI-Bewertungsvorschlag und KI-Feedbacktext als Entwurf erzeugen (Sie entscheiden, ob Sie ihn übernehmen).

📷 Screenshot: Bewertungsansicht mit KI-Vorschlag.

6.7 Export / Import von Modulen

In der Modul-Detailansicht:

Export: Lädt das Modul samt Matrix und Assets (Bilder, Anhänge) als ZIP herunter.
Import (in der Modul-Liste): entpackt ein ZIP und legt ein neues Modul an. Existiert das Original noch, entsteht eine Kopie mit dem Zusatz „(Importiert)".

So lassen sich Module zwischen Lehrpersonen oder Schulen austauschen.

6.8 KI-Einstellungen 🤖 (Lehrperson)

Unter KI-Einstellungen hinterlegen Sie Ihre eigene KI-Anbindung (Provider/Endpoint und API-Schlüssel). Der Schlüssel wird verschlüsselt gespeichert und nie im Klartext angezeigt. Optional können Sie Ihre KI für Ihre Lernenden freigeben, damit diese die Übungs-Funktionen nutzen können.

📷 Screenshot: KI-Einstellungen der Lehrperson.

7. Handbuch für Lernende 👨‍🎓

Navigation: Meine Matrix, Lernpfad, Meine Nachweise, Modul mit KI üben, Einstellungen.

7.1 Einem Modulanlass beitreten

Auf Meine Matrix den Beitrittscode der Lehrperson eingeben (oder den Beitrittslink öffnen). Danach erscheint die Kompetenzmatrix des Moduls.

📷 Screenshot: Beitritt mit Code.

7.2 Matrix ansehen & Nachweise einreichen

In der Matrix sind die einreichbaren Nachweise als anklickbare Chips im jeweiligen Feld sichtbar (mit Status-Symbol). Ein Klick öffnet den Einreichungs-Dialog.

Je nach Vorgabe der Lehrperson stehen zur Verfügung:

Datei hochladen, Link angeben, Text schreiben, Screenshot aufnehmen (vor dem Absenden ansehbar) oder ein Fachgespräch/Präsentation.
Ein einziger Knopf reicht alle vorhandenen Teile gemeinsam ein.

Nach der Einreichung sehen Sie den Status (eingereicht / bewertet / zurückgewiesen) sowie ggf. Punkte und Feedback.

📷 Screenshot: Einreichungs-Dialog mit den verschiedenen Einreichungsarten.

7.3 Meine Nachweise

Die Seite Meine Nachweise bündelt alle Aufträge in „zu erledigen" und „erledigt" – unabhängig vom Modul. So sehen Sie auf einen Blick, was noch offen ist.

7.4 Lernpfad

Hat die Lehrperson einen Lernpfad aktiviert, zeigt Lernpfad die empfohlene Reihenfolge als Zeitachse. Die jeweils nächsten Nachweise sind direkt anklick- und einreichbar.

📷 Screenshot: Lernpfad-Zeitachse.

7.5 Modul mit KI üben 🤖

Unter Modul mit KI üben führt die KI ein Fachgespräch und prüft verschiedene Themen ab. Als Kontext dienen alle Kompetenzen der Matrix. Die KI gibt Lernhinweise und Rückmeldung zur Qualität Ihrer Antworten. Das Üben ist unverbindlich und fliesst nicht in die Bewertung ein.

📷 Screenshot: KI-Übungs-Chat.

7.6 Einstellungen (Lernende)

Unter Einstellungen können Sie Sprache/Anzeige festlegen und – falls gewünscht – eine eigene KI konfigurieren. Ist eine eigene KI hinterlegt, wird diese verwendet; andernfalls die von der Lehrperson freigegebene.

8. KI-Funktionen im Detail 🤖

KompetenzHub nutzt KI assistierend – nie automatisch entscheidend:

Funktion	Für wen	Zweck
Bewertungsvorschlag	Lehrperson	Entwurf für Gütestufe/Punkte zu einer Einreichung.
Feedbacktext	Lehrperson	Formulierungsvorschlag für die Rückmeldung.
Fachgespräch (Übung)	Lernende	KI stellt Fragen zum Modul, gibt Lernhinweise und Qualitätsfeedback.

Datenschutz/Sicherheit: API-Schlüssel werden mit AES-256-GCM verschlüsselt gespeichert und nie zurückgegeben. Die KI-Anbindung ist pro Lehrperson konfigurierbar; Lernende können eigene Schlüssel hinterlegen. Ob eine Lehrperson-KI für Lernende nutzbar ist, steuert die Lehrperson per Freigabe.

9. Handbuch für die Schuladministration 📔

Die Schuladmin meldet sich an und gelangt zum Schuladmin-Dashboard mit der Navigation: Übersicht, Personen, Einladungen, Betrieb, Audit-Log, Schul-Einstellungen.

Wie man die erste Schuladmin einrichtet, steht in Kapitel 10.6.

9.1 Übersicht

Kennzahlen auf einen Blick: Anzahl Lehrpersonen, Lernende, Admins, offene Einladungen, gesperrte Konten, Module und Modulanlässe. Ist eine Schulquota hinterlegt, zeigt ein Balken zusätzlich den Gesamtspeicher gegen die gekaufte Quota.

📷 Screenshot: Admin-Übersicht.

9.2 Personen verwalten

Liste aller Personen der Schule. Möglich sind:

Rolle ändern (Lernende:r ↔ Lehrperson ↔ Schuladmin).
Anzeigename bearbeiten.
Sperren / Entsperren (gesperrte Konten können sich nicht mehr anmelden).
Entfernen (Zugang zur Schule entziehen).

Schutzmechanismen: Man kann sich nicht selbst sperren/entfernen, und die letzte aktive Schuladmin kann nicht entfernt/degradiert werden.

📷 Screenshot: Personenverwaltung mit Rollen-Auswahl und Aktionen.

9.3 Einladungen (wer darf Lehrperson werden?)

Da neue Anmeldungen standardmässig Lernende werden, steuert die Schuladmin den Lehrpersonen-Zugang über Einladungen:

E-Mail-Adresse erfassen, Rolle (Lehrperson oder Schuladmin) wählen, Einladen.
Beim ersten Login mit dieser E-Mail erhält die Person automatisch die eingeladene Rolle; die Einladung gilt als eingelöst.
Offene Einladungen lassen sich jederzeit zurückziehen.

Bereits vorhandene Personen werden nicht eingeladen, sondern direkt in der Personenverwaltung befördert.

📷 Screenshot: Einladungen anlegen und Liste offener Einladungen.

9.4 Schul-Einstellungen 🏫

Schulname (erscheint im Kontext der App).
Standardsprache: Sprache, die neue Konten beim ersten Login erhalten.
Logo hochladen: erscheint oben links in der Kopfzeile neben dem Schriftzug. Empfohlen: PNG/SVG mit transparentem Hintergrund.
Akzentfarbe: Primärfarbe der App – 7 Vorschläge oder eigener Hex-Wert, mit Live-Vorschau. Statusfarben (grün/orange/grau) bleiben für die Lesbarkeit unverändert.
Anmelde-Anbieter: Microsoft, Google, GitHub und/oder das eigene KompetenzHub-Konto (Logto) aktivieren/deaktivieren. Ein deaktivierter Anbieter wird beim Login abgewiesen.
Erlaubte Registrierungs-Domains: Beschränkt die Selbstregistrierung Lernender auf bestimmte E-Mail-Domains (z. B. stud.gibb.ch). Mehrere Domains möglich. Ohne Eintrag darf sich jede:r registrieren; per Einladung aufgenommene Personen sind von der Einschränkung nie betroffen. Greift nur beim eigenen KompetenzHub-Konto/OIDC-Selbstregistrierung.
Statusanzeige: ob Dev-Login aktiv ist und ob der Bootstrap-Admin (ADMIN_EMAILS) konfiguriert ist.

📷 Screenshot: Schul-Einstellungen mit Akzentfarben-Auswahl und Logo.

9.5 Betrieb & Gesundheit

Gesundheits-Ampel: Zustand von Datenbank, Redis und Objektspeicher sowie Software-Version.
Auslastung: Anzahl Lehrpersonen/Lernende, Module, Modulanlässe, Einreichungen, belegter Speicher sowie Anmeldungen der letzten 7 / 30 Tage.
Speicher je Lehrperson & Quota: Aufschlüsselung des Verbrauchs pro Lehrperson (Einreichungen der eigenen Modulanlässe zzgl. selbst hochgeladener Anhänge/Bilder) mit Fortschrittsbalken. Hier lässt sich je Lehrperson eine persönliche Speicherquota (in GB) setzen. Steht für die Schule eine gekaufte Schulquota bereit, wird der Gesamtverbrauch dagegen angezeigt. Die Summe der Lehrpersonen-Quotas darf die Schulquota bewusst übersteigen (nicht jede:r nutzt sein Kontingent aus). Bei erschöpfter Quota werden weitere Uploads abgewiesen. Die Schulquota selbst wird von der Plattform-Administration vergeben (siehe Kapitel 22.3).

📷 Screenshot: Betriebs-Seite mit Health-Ampel und Kennzahlen.

9.6 Audit-Log 👁️‍🗨️

Chronologische Liste sicherheitsrelevanter Ereignisse (Anmeldungen, abgewiesene Anmeldungen, Abmeldungen) mit Zeitpunkt, Aktion und Person.

9.7 Backup (Beta)

Per Knopfdruck erzeugt die Schuladmin ein Voll-Backup als ZIP: die Schuldaten als backup.json (Personen, Module, Matrizen, Modulanlässe, Einreichungen, Bewertungen, Audit-Log, Einstellungen) plus alle Dateien aus dem Objektspeicher (Logos, Bilder, Anhänge, Belege). Details siehe Kapitel 13.

📷 Screenshot: Backup-Schaltfläche auf der Betriebs-Seite.

10. Installation & Betrieb (technisch)

Dieser Teil richtet sich an Personen mit IT-Kenntnissen, die KompetenzHub selbst betreiben möchten.

10.1 Architektur im Überblick

KompetenzHub ist ein Monorepo mit zwei Anwendungen:

Teil	Technologie	Aufgabe
API (`apps/api`)	NestJS 10, Prisma, REST unter `/api/v1`	Geschäftslogik, Authentifizierung, Datenzugriff.
Web (`apps/web`)	Next.js 14 (App Router, React)	Benutzeroberfläche.

Abhängige Dienste (per Docker):

Dienst	Zweck
PostgreSQL 16	Hauptdatenbank.
Redis 7	Hintergrund-Jobs / Caching.
MinIO (S3-kompatibel)	Objektspeicher für Dateien (Bilder, Anhänge, Belege, Logos).

10.2 Systemvoraussetzungen

Node.js ≥ 20 und npm
Docker und Docker Compose (für PostgreSQL, Redis, MinIO)
ca. 2 GB freier Arbeitsspeicher für die Dienste
Betriebssystem: Linux, macOS oder Windows

10.3 Schnellstart

Zum Ausprobieren in Docker nicht als Produktivumgebung gedacht!

# 1) Repository holen
git clone https://github.com/staubthom/KompetenzHub.git
cd KompetenzHub

# 2) Umgebungsdatei anlegen und bei Bedarf anpassen
cp .env.example-dev .env

# 3) Infrastruktur starten (PostgreSQL, Redis, MinIO)
docker compose -f docker-compose_dev.yaml --profile  app up -d --build

Im Ordner Vorlagen finden Sie ein Demomodul zum Importieren

Für lokale Entwicklung

# 1) Repository holen
git clone https://github.com/staubthom/KompetenzHub.git
cd KompetenzHub

# 2) Umgebungsdatei anlegen und bei Bedarf anpassen
cp .env.example .env

# 3) Infrastruktur starten (PostgreSQL, Redis, MinIO)
docker compose up -d

# 4) Abhängigkeiten installieren
npm install

# 5) Datenbankschema anlegen (Migrationen) + Prisma-Client generieren
npm run prisma:migrate
npm run prisma:generate

# 6) API und Web gemeinsam starten
npm run dev

Danach erreichbar:

Weboberfläche: http://localhost:3000
API: http://localhost:3001 (Health-Check: http://localhost:3001/api/v1/health)
MinIO-Konsole: http://localhost:9001 (Standard-Zugang minioadmin / minioadmin)

Die API und Web können auch einzeln gestartet werden: npm run dev:api bzw. npm run dev:web.

Optional – eigenes KompetenzHub-Konto mit Registrierung: Wer Anmeldung/Registrierung ohne Microsoft-/Google-Konto anbieten möchte, richtet zusätzlich den mitgelieferten Identity-Provider (Logto) ein – siehe Kapitel 10.8.

10.4 Produktions-Build

npm run build           # baut API und Web
# API starten:
npm run start --workspace apps/api      # bedient Port 3001 (API_PORT)
# Web starten:
npm run start --workspace apps/web      # bedient Port 3000 (WEB_PORT)

Betreiben Sie beide Prozesse dauerhaft (z. B. via systemd, PM2 oder Container) und stellen Sie sie hinter einen Reverse Proxy mit HTTPS (z. B. Nginx/Caddy/Traefik).

10.5 Deployment per Docker Compose (Voll-Stack)

Am einfachsten lässt sich KompetenzHub komplett mit Docker betreiben. Das docker-compose.yml enthält neben der Infrastruktur (PostgreSQL, Redis, MinIO) auch API und Web – diese liegen im Profil app und starten nur bei Bedarf:

cp .env.example .env          # danach BEARBEITEN (siehe unten)
docker compose --profile app up -d --build

Das startet alle fünf Container; die API wendet beim Start automatisch die Datenbank-Migrationen an. Erreichbar (Standard): Web http://localhost:3000, API http://localhost:3001, MinIO-Konsole http://localhost:9001.

Ohne Profil – docker compose up -d – startet wie bisher nur die Infrastruktur (für die lokale Entwicklung mit npm run dev).

Zwingend in der .env setzen (sonst startet die API bewusst nicht):

Variable	Bedeutung
`JWT_SIGNING_KEY`	starker, geheimer Schlüssel für die API-Tokens
`AI_CONFIG_ENC_KEY`	starker, geheimer Schlüssel für die KI-Schlüssel-Verschlüsselung
`AUTH_EXCHANGE_SECRET`	Schutz des `/auth/exchange`-Endpunkts (min. 24 Zeichen). API und Web müssen denselben Wert haben. In Produktion Pflicht – ohne ihn startet die API nicht.
`ADMIN_EMAILS`	E-Mail(s) der ersten Schuladmin(s)

Öffentliche URLs (browser-erreichbar – nicht die internen Container-Namen):

Variable	Lokal	Produktiv
`API_PUBLIC_URL`	`http://localhost:3001`	z. B. `https://kompetenzhub.schule.ch/api`
`WEB_PUBLIC_URL`	`http://localhost:3000`	z. B. `https://kompetenzhub.schule.ch`
`S3_PUBLIC_URL`	`http://localhost:9000`	öffentlich erreichbare MinIO-/Storage-URL

API_PUBLIC_URL wird beim Web-Build ins Bundle gebacken – nach Änderung das Web-Image neu bauen (--build).

Produktiv empfiehlt sich ein vorgelagerter Reverse Proxy mit HTTPS, der eine Domain auf Web, API (/api) und – für Datei-Downloads – den Objektspeicher routet. So sind alle URLs same-origin und konsistent. Logos/Bilder funktionieren bereits über S3_PUBLIC_URL; private Datei-Downloads (Einreichungen, Anhänge) benötigen, dass der Objektspeicher unter derselben Adresse für API und Browser erreichbar ist.

10.6 Health-Check

Der Endpunkt GET /api/v1/health liefert den Zustand der abhängigen Dienste:

{ "status": "ok", "db": "up", "redis": "up", "s3": "up", "version": "…" }

Eignet sich für Monitoring/Uptime-Checks. status: "degraded" signalisiert, dass mindestens ein Dienst nicht erreichbar ist.

10.7 Erste Schuladmin einrichten

Damit überhaupt jemand das Admin-Dashboard öffnen kann, wird die erste Schuladmin über eine Umgebungsvariable festgelegt:

In der .env die gewünschten E-Mail-Adressen eintragen:
```
ADMIN_EMAILS=schulleitung@schule.ch,ict@schule.ch
```
API neu starten.
Wer sich anschliessend mit einer dieser E-Mails anmeldet, erhält automatisch Admin-Rechte.

Ab dann können weitere Admins/Lehrpersonen bequem über das Dashboard (Einladungen/Beförderung) verwaltet werden.

Für lokale Tests genügt der Dev-Login mit Rollenwahl „Administration".

10.8 Eigener Anmelde-Anbieter mit Selbstregistrierung (Logto)

Optional. Microsoft- und Google-Login decken nicht alle ab: Manche Lernende/Lehrpersonen haben kein solches Konto oder wollen es nicht nutzen. Für diesen Fall kann KompetenzHub einen eigenen Identity-Provider betreiben, bei dem sich Nutzer:innen direkt mit E-Mail und Passwort registrieren. Dafür wird der schlanke, quelloffene IdP Logto als eigener Docker-Container mitgeliefert (Service logto in docker-compose_dev.yaml). Es muss nichts selbst an OAuth/OIDC programmiert werden.

KompetenzHub bleibt dabei die „interne Währung": Logto übernimmt nur Anmeldung/Registrierung, das eigentliche API-Token und die Rollen (RBAC, Zugangs-Gate) vergibt weiterhin KompetenzHub. Logto ist damit nur eine weitere Login-Quelle neben Microsoft/Google.

Wichtig – E-Mail ist Pflicht: KompetenzHub identifiziert Personen über ihre E-Mail-Adresse. Logtos Standard-Registrierung verlangt aber nur einen Benutzernamen – ein so angelegtes Konto hätte keine E-Mail, und die Anmeldung an KompetenzHub würde mit „Konto wurde beim Server nicht akzeptiert" abgewiesen. Damit das nicht passiert, stellt der mitgelieferte Init-Service logto-init die Registrierung automatisch auf E-Mail + Passwort um (ohne E-Mail-Verifikation, da Logto sonst einen SMTP-Server bräuchte). Es ist also kein manueller Schritt in Logto nötig.

Einrichtung Schritt für Schritt:

Container starten (nutzt denselben PostgreSQL, aber eine eigene Datenbank logto). Der Service logto-init wartet, bis Logto bereit ist, und stellt die Registrierung auf E-Mail + Passwort um:
```
docker compose -f docker-compose_dev.yaml up -d logto logto-init
```
Läuft PostgreSQL bereits mit Daten aus einem früheren Start, fehlt evtl. die logto-Datenbank. Dann einmalig anlegen: docker compose -f docker-compose_dev.yaml exec postgres createdb -U kompetenzhub logto (Bei einem frischen Daten-Volume geschieht das automatisch über infra/postgres-init/.)
Admin-Konsole öffnen: http://localhost:3012 → beim ersten Aufruf ein Logto-Admin-Konto anlegen.
Anwendung registrieren: Applications → Create application → „Traditional Web", Name z. B. „KompetenzHub Web". Folgende Werte eintragen:
- Redirect URI: http://localhost:3000/api/auth/callback/kompetenzhub
- Post sign-out redirect URI: http://localhost:3000/login

In die .env übertragen (App-Id/-Secret stehen in der Logto-App-Detailansicht):

KOMPETENZHUB_OIDC_ISSUER=http://localhost:3011/oidc
KOMPETENZHUB_OIDC_CLIENT_ID=<App ID aus Logto>
KOMPETENZHUB_OIDC_CLIENT_SECRET=<App Secret aus Logto>

API und Web neu starten. Sobald die drei Werte gesetzt sind, erscheinen auf der Anmeldeseite automatisch der Knopf „Mit KompetenzHub-Konto anmelden" und der „Jetzt registrieren"-Link. Neu registrierte Personen werden – wie alle Neuanmeldungen – standardmässig Lernende (Zugangs-Gate, siehe Kapitel 3).

Registrierung lieber manuell konfigurieren? Der Init-Service ändert die Einstellung nur, solange noch der unveränderte Logto-Standard aktiv ist – passt die Schuladmin sie später unter Sign-in experience selbst an, bleibt das bei Neustarts erhalten. Wichtig ist nur, dass E-Mail als Identifier aktiv ist (sonst entstehen Konten ohne E-Mail). Soll Logto Registrierungs-E-Mails verifizieren, dann zusätzlich einen SMTP-Connector in Logto einrichten.

Container-Modus (--profile app): Wenn auch Web/API in Containern laufen, muss der Issuer eine URL sein, die sowohl der Browser als auch der web-Container gleich erreichen – z. B. http://host.docker.internal:3011/oidc – und mit Logtos ENDPOINT (KOMPETENZHUB_OIDC_ENDPOINT) übereinstimmen. Für den üblichen npm run dev-Betrieb auf dem Host genügt http://localhost:3011/oidc. Die API braucht den Issuer nur zur Anzeige („Anbieter konfiguriert"); sie ruft Logto nicht auf.

Admin-Konsole: http://localhost:3012 · OIDC-Endpoint (Login/Registrierung): http://localhost:3011

11. Konfiguration: Umgebungsvariablen

Alle Einstellungen liegen in der zentralen Datei .env (Vorlage: .env.example).

Datenbank / Dienste

Variable	Bedeutung	Beispiel/Default
`DATABASE_URL`	PostgreSQL-Verbindungs-URL	`postgresql://kompetenzhub:kompetenzhub@localhost:5432/kompetenzhub?schema=public`
`POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB`	DB-Zugang (für Docker)	`kompetenzhub`
`REDIS_URL`	Redis-Verbindung	`redis://localhost:6379`
`S3_ENDPOINT`	Objektspeicher-Adresse	`http://localhost:9000`
`S3_BUCKET`	Bucket-Name	`kompetenzhub`
`S3_ACCESS_KEY` / `S3_SECRET_KEY`	Objektspeicher-Zugang	`minioadmin`

Anwendung

Variable	Bedeutung	Default
`API_PORT`	Port der API	`3001`
`WEB_PORT`	Port der Weboberfläche	`3000`
`NEXT_PUBLIC_API_URL`	API-Adresse für das Frontend	`http://localhost:3001`
`NEXT_PUBLIC_WEB_URL`	erlaubte Web-Origin (CORS/Cookies)	`http://localhost:3000`

Authentifizierung & Sicherheit

Variable	Bedeutung	Hinweis
`JWT_SIGNING_KEY`	Signaturschlüssel für API-Tokens	In Produktion zwingend ändern!
`JWT_TTL_SECONDS`	Token-Lebensdauer	Default `900` (15 min)
`DEV_LOGIN_ENABLED`	Dev-Login-Endpunkt aktiv	In Produktion auf `false` (sonst Startabbruch)
`AUTH_EXCHANGE_SECRET`	Schutz des `/auth/exchange`-Endpunkts (BFF)	In Produktion zwingend, min. 24 Zeichen – bei Web und API identisch setzen. Ohne ihn startet die API nicht; der Endpunkt vertraut sonst dem übergebenen Profil und Anmeldungen könnten gefälscht werden.
`ADMIN_EMAILS`	Bootstrap-Admins (kommagetrennt)	siehe 10.6
`DEFAULT_TENANT_ID`	Standard-Mandant	vorbelegt

Multi-Mandanten (mehrere Schulen in einer Instanz) – optional

Nur nötig, wenn eine Instanz mehrere Schulen/Abteilungen bedienen soll (siehe Kapitel 22). Bleiben die Basisdomain-Variablen leer, läuft die Instanz wie bisher als Einzel-Schule (Default-Mandant).

Variable	Bedeutung	Beispiel/Default
`TENANT_BASE_DOMAIN`	Basisdomain, um die Subdomain abzuschneiden (API-seitig)	`kompetenzhub.ch`
`NEXT_PUBLIC_TENANT_BASE_DOMAIN`	dieselbe Basisdomain für den Browser (Web)	`kompetenzhub.ch`
`DEFAULT_TENANT_SLUG`	Fallback-Mandant, wenn keine Subdomain ableitbar ist (z. B. lokal)	`default`
`SUPERADMIN_EMAILS`	Plattform-Admins, die Schulen anlegen/verwalten dürfen (kommagetrennt)	–

KI

Variable	Bedeutung	Hinweis
`AI_CONFIG_ENC_KEY`	Schlüssel zur Verschlüsselung gespeicherter KI-API-Keys	In Produktion zwingend stark/geheim setzen!
`AI_STUB_MODE`	deterministische KI-Antworten ohne externen Aufruf	nur für Tests; in Produktion nicht setzen

OIDC (Microsoft/Google) – optional

AUTH_MICROSOFT_CLIENT_ID/SECRET, AUTH_GOOGLE_CLIENT_ID/SECRET, NEXTAUTH_SECRET, NEXTAUTH_URL – für die produktive Single-Sign-On-Anbindung.

Eigener Anmelde-Anbieter / Selbstregistrierung (Logto) – optional

Aktiviert den Knopf „Mit KompetenzHub-Konto anmelden" samt Registrierung (siehe Kapitel 10.8). Der Provider erscheint nur, wenn alle drei Pflichtwerte gesetzt sind.

Variable	Bedeutung	Beispiel/Default
`KOMPETENZHUB_OIDC_ISSUER`	OIDC-Issuer des Logto-Containers (`ENDPOINT` + `/oidc`)	`http://localhost:3011/oidc`
`KOMPETENZHUB_OIDC_CLIENT_ID`	App-Id der in Logto angelegten „Traditional Web"-App	–
`KOMPETENZHUB_OIDC_CLIENT_SECRET`	App-Secret derselben App	–
`KOMPETENZHUB_OIDC_ENDPOINT`	Browser-erreichbare URL des Logto-OIDC-Endpoints	`http://localhost:3011`
`KOMPETENZHUB_ADMIN_ENDPOINT`	Browser-erreichbare URL der Logto-Admin-Konsole	`http://localhost:3012`

12. Produktivbetrieb & Sicherheit

Checkliste vor dem produktiven Einsatz:

In Produktion (NODE_ENV=production) erzwingt die API einen Teil dieser Punkte beim Start: fehlt/zu schwach ein Pflicht-Secret (JWT_SIGNING_KEY, AI_CONFIG_ENC_KEY, AUTH_EXCHANGE_SECRET) oder ist DEV_LOGIN_ENABLED nicht false, bricht der Start bewusst ab.

Sicherheitsmerkmale ab Werk: rollenbasierte Zugriffskontrolle (RBAC), strikte Mandanten-/Eigentümer-Trennung (Lehrpersonen sehen nur eigene Module/Modulanlässe), Token an die Schul-Subdomain gebunden, verschlüsselte KI-Schlüssel, Audit-Log für Anmelde-/Sicherheitsereignisse, Zugangs-Gate (neue Konten werden nicht automatisch Lehrpersonen), optionale Beschränkung der Selbstregistrierung auf erlaubte E-Mail-Domains, Rate-Limiting sowie erzwungener Download hochgeladener SVG-Dateien (Content-Disposition: attachment) gegen Inline-XSS.

13. Backup & Wiederherstellung

Anwendungs-Backup (Schuladmin)

Im Schuladmin-Dashboard unter Betrieb → Backup lässt sich ein Voll-Backup als ZIP herunterladen:

backup.json – alle Schuldaten (Personen, Module, Matrizen, Modulanlässe, Einreichungen, Bewertungen, Audit-Log, Einstellungen, Branding).
files/… – alle Dateien aus dem Objektspeicher (Logos, Bilder, Anhänge, Belege).

Empfehlung: regelmässig (z. B. wöchentlich) herunterladen und sicher ablegen.

Infrastruktur-Backup (IT)

==Für ein vollständiges, wiederherstellbares Backup zusätzlich auf Infrastruktur-Ebene sichern:==

PostgreSQL: pg_dump (bzw. das Docker-Volume postgres-data).
MinIO: das Docker-Volume minio-data bzw. den Bucket spiegeln.

Hinweis: Eine automatische Rück-Einspielung des Anwendungs-ZIP über die Oberfläche ist derzeit nicht vorgesehen; das ZIP dient der Datensicherung und -portabilität. Module und Modulanlässe lassen sich zusätzlich gezielt über die jeweiligen Export/Import-Funktionen übertragen.

14. Aktualisierung & Datenbankmigrationen

git pull
npm install
npm run prisma:migrate     # wendet neue Datenbankmigrationen an
npm run prisma:generate
npm run build
# Dienste neu starten

Migrationen liegen versioniert unter apps/api/prisma/migrations. Vor einem Update in Produktion ein Datenbank-Backup erstellen.

15. Datenschutz

Beim Self-Hosting bleiben alle Daten auf Ihrer Infrastruktur.
Personenbezogene Daten beschränken sich im Kern auf Konto (Name, E-Mail) sowie Einreichungen/Bewertungen.
KI-Aufrufe erfolgen nur, wenn eine KI konfiguriert ist; dabei werden die zur Bewertung/Übung nötigen Inhalte an den gewählten KI-Anbieter übermittelt. Die Wahl des Anbieters und damit der Datenverarbeitung liegt bei der Schule/Lehrperson/Lernenden.
Beim Export von Modulen werden bewusst keine personenbezogenen Daten mitgegeben; beim Modulanlass-Export hingegen schon (inkl. Einreichungen) – entsprechend vertraulich behandeln.

Diese Anleitung ersetzt keine rechtliche Beratung. Klären Sie den Einsatz mit der/dem Datenschutzverantwortlichen Ihrer Schule.

16. Fehlerbehebung (FAQ)

Ich werde nach dem Login als „Lernende:r" eingestuft, obwohl ich Lehrperson bin. Das ist beabsichtigt: neue Konten sind standardmässig Lernende. Die Schuladmin muss Sie einladen oder befördern (Kapitel 9.2/9.3).

Niemand kommt ins Admin-Dashboard. Stellen Sie sicher, dass Ihre E-Mail in ADMIN_EMAILS steht und die API danach neu gestartet wurde (Kapitel 10.6).

„Dieser Anmelde-Anbieter ist deaktiviert." Die Schuladmin hat Microsoft bzw. Google unter Schul-Einstellungen deaktiviert. Anbieter wieder aktivieren.

„Dieses Konto ist deaktiviert." Das Konto wurde gesperrt. Die Schuladmin kann es unter Personen wieder entsperren.

Logo/Bilder werden nicht angezeigt. Prüfen Sie, ob der Objektspeicher (MinIO) läuft und S3_ENDPOINT für Browser erreichbar ist. Health-Check beachten.

Health zeigt degraded. Mindestens einer der Dienste DB/Redis/S3 ist nicht erreichbar – Container-Status mit docker compose ps prüfen.

Migrationsfehler beim Start. npm run prisma:migrate ausführen; sicherstellen, dass DATABASE_URL korrekt ist und PostgreSQL läuft.

17. Glossar

Begriff	Erläuterung
RBAC	Rollenbasierte Zugriffskontrolle.
JWT	Signiertes Anmelde-Token der API.
OIDC / SSO	Single Sign-On über Microsoft/Google.
Tenant / Mandant	Eine Schule als abgegrenzter Datenraum.
S3 / MinIO	Objektspeicher für Dateien.
Stub-Modus	KI liefert Testantworten ohne externen Aufruf.
Modulanlass	Durchführung eines Moduls mit einer Klasse.

Glossar (ICT-BBCH-Begriffe)

Begriff	Bedeutung
Modul	Inhaltliche Einheit der Grundbildung (z.B. Modul 293). Grundlage ist die Modulidentifikation aus dem Modulbaukasten.
Modulidentifikation	Offizielle Beschreibung eines Moduls inkl. Handlungsziele. Quelle: modulbaukasten.ch.
Handlungsziel (HZ)	Beschreibung dessen, was in einer beruflichen Handlungssituation erreicht werden soll. Grundlage der Kompetenzen.
Kompetenzmatrix	Tabellarische Überführung der Handlungsziele in Kompetenzen. National i.d.R. eine pro Modulidentifikation.
Kompetenzband	Thematisch zusammenhängende Gruppe von Kompetenzen (z.B. A1, B1, C1). Referenziert 1–n Handlungsziele.
Gütestufe	Niveaustufe der Kompetenz: Beginner, Intermediate, Advanced, (nicht erfüllt).
Kompetenzfeld	Schnittpunkt von Kompetenzband × Gütestufe in der Matrix.
Deskriptor	„Ich kann …"-Beschreibung einer Kompetenz in einem Kompetenzfeld.
Bewertungsraster	Konkretes Beurteilungsinstrument je Lernsituation/Leistungsnachweis: Kriterien + Indikatoren je Gütestufe.
Kriterium	Kurzbeschreibung der Zielhandlung im Bewertungsraster (z.B. „Container-Umgebung definieren").
Indikator	Beobachtbare Beschreibung der erwarteten Leistung je Gütestufe.
Leistungsbeurteilung (LB)	Überprüfung des Kompetenzerwerbs anhand der Kompetenzmatrix als Referenz.
Kompetenznachweis	In dieser App: konkrete Lernaufgabe, mit der eine Kompetenz belegt wird (Upload, Quiz, Fachgespräch …).
Lernpfad	Alternative, didaktisch sinnvollere Reihenfolge der Kompetenzen durch die Matrix.
MLP	Modullehrplan der Berufsfachschule.
üK	Überbetrieblicher Kurs.
EFZ	Eidgenössisches Fähigkeitszeugnis.

Gütestufen & Noten-Richtwerte

Gütestufe	Kürzel	Note (Richtwert)	Beschreibung (verkürzt)
Beginner	B	3.0	Kann Teile der geforderten Kompetenzen anwenden.
Intermediate	I	4.5	Beherrscht die selbständige Anwendung.
Advanced	A	6.0	Beherrscht die fachgerechte Anwendung.
Nicht erfüllt	0	–	Kompetenzband nicht bearbeitet (nur im Bewertungsraster vermerkt).

⚠️ Die Gewichtung der Kompetenzbänder und die Notenvergabe je Gütestufe wird durch den Lernort (die Lehrperson/Schule) festgelegt. Die App stellt die Richtwerte als Default bereit, erlaubt aber lernortspezifische Anpassung.

18 Lizenz

Dieses Projekt steht unter der GNU Affero General Public License v3.0 (AGPLv3). Details findest du in der Datei LICENSE.

Wichtig (AGPL §13 – Netzwerk-Nutzung): Wird eine modifizierte Version über ein Netzwerk betrieben, muss den Nutzer:innen der Quellcode zugänglich gemacht werden. In der App ist dafür ein „Quellcode"-Link im Seitenmenü hinterlegt; beim Self-Hosting einer angepassten Variante diesen auf das eigene Repository setzen.

Wenn du Funktionen erweiterst oder Fehler behebst, freuen wir uns über einen Pull Request hier im Haupt-Repository!

19 Plugins aktivieren

KompetenzHub ist so entwickelt, dass die Community selber Plugins erstellen kann. Diese müssen aber bereits im Build Prozess vorhanden sein. Im AnminPanel können diese Plugins aktiviert und deaktiviert werden.

📷 Screenshot: Aktivierung der Plugins.

Hier ist ersichtlich was als Plugin alles möglich ist. Das Memo Plugin dient als Schulungsplugin für Lehrersonen die gerne selber Plugins entwickeln wollen. 📷 Screenshot: Aktivierung der Plugins.

20. Testing

KompetenzHub verfügt über zwei Teststufen, die sich ergänzen: Smoke-Tests prüfen die API direkt auf HTTP-Ebene, Playwright-Tests testen die Benutzeroberfläche im echten Browser.

Für beide Teststufen müssen API (localhost:3001) und – bei Playwright – auch die Web-App (localhost:3000) laufen.

20.1 Smoke-Tests (API)

Smoke-Tests senden echte HTTP-Anfragen an die laufende API und geben pro Prüfpunkt OK oder FAIL aus. Sie decken alle wichtigen Backend-Flows ab: Authentifizierung, RBAC, Einladungen, Bewertungen, KI-Konfiguration, Sicherheits-Header u.v.m.

# Alle Smoke-Tests auf einmal
node --test apps/api/scripts/*.mjs

# Einzelner Test
node apps/api/scripts/smoke-auth.mjs

Für die KI-Tests (smoke-ai-grading.mjs, smoke-expert-talk.mjs) muss die API mit AI_STUB_MODE=1 gestartet sein.

Vollständige Dokumentation: apps/api/scripts/Readme.md

20.2 Playwright E2E-Tests (UI)

Playwright-Tests steuern einen echten Chromium-Browser und testen die vollständigen Benutzer-Journeys durch die Oberfläche – vom Login über die Nachweis-Einreichung bis zur Bewertung durch die Lehrperson.

# Einmalig: Browser installieren
cd apps/web && npx playwright install chromium

# Alle E2E-Tests ausführen
npm run test:e2e --workspace apps/web

# Mit interaktivem UI (Zeitreise, Schritt-für-Schritt)
npm run test:e2e:ui --workspace apps/web

Abgedeckte Flows:

Datei	Was wird getestet
`auth.spec.ts`	Dev-Login UI, rollenbasierte Weiterleitung, Logout
`admin-dashboard.spec.ts`	Einladungen erstellen/zurückziehen, Sperren/Entsperren, Rollenänderung
`evidence-submission.spec.ts`	Nachweis einreichen (Student) und bewerten (Lehrperson)
`matrix-editor.spec.ts`	Modul, Handlungsziel, Band und Deskriptor erstellen und löschen

Vollständige Dokumentation: apps/web/e2e/Readme.md

21 Plugins selbst entwickeln

KompetenzHub ist durch ein Plugin-System erweiterbar. Lehrpersonen, Schulentwickler und Drittanbieter können neue Funktionen als isolierte Pakete beisteuern, ohne den Kern der Anwendung anzutasten. Die vollständige Entwickleranleitung befindet sich in docs/pluginanleitung.md. Dieses Kapitel gibt einen kompakten Überblick.

21.1 Grundprinzip

Ein Plugin darf keine Datei in apps/api oder apps/web verändern. Jede Interaktion mit dem Kern läuft ausschliesslich über drei Verträge:

manifest.json – deklariert Routen, UI-Beiträge, Rechte und Ressourcen.
server/index.ts – Backend-Logik über eine gescopte Kontext-API.
web/*.tsx – UI-Komponenten, die an festen Erweiterungspunkten (Slots) injiziert werden.

Als Lernbeispiel ist das Plugin memo (Dossier- & Memo-Assistent) unter plugins/packages/memo/ mitgeliefert. Es zeigt alle Konzepte in der Praxis.

21.2 Dateistruktur

Jedes Plugin liegt unter plugins/packages/<pluginId>/ und folgt dieser Struktur:

plugins/packages/<pluginId>/
├── manifest.json          # Pflicht – Vertrags- und Sicherheitsbasis
├── package.json           # Name: @kompetenzhub/plugin-<id>
├── server/
│   └── index.ts           # Backend via definePlugin({ routes })
├── web/
│   └── <Komponente>.tsx   # UI-Komponenten (Name exakt wie im Manifest)
└── i18n/
    ├── de.json            # Flache Schlüssel: plugin.<id>.*
    ├── fr.json
    ├── it.json
    └── en.json

Eine leere Vorlage steht unter plugins/packages/_example bereit.

22. Mehrere Schulen in einer Instanz (Multi-Mandanten)

KompetenzHub kann eine einzelne Installation für mehrere Schulen oder Abteilungen betreiben. Jede Schule ist ein eigener Mandant (Tenant) mit vollständig getrennten Daten (Module, Klassen, Personen, Nachweise, Branding). Alternativ lässt sich weiterhin eine Instanz pro Schule betreiben – beide Betriebsarten werden unterstützt.

Ausführliche Betriebsanleitung (DNS, TLS, Reverse-Proxy, OAuth): docs/multi-tenant.md.

22.1 Wie wird eine Schule angesprochen?

Über ihre Subdomain. Die Subdomain (der „Slug") bestimmt, welche Schule geladen wird:

Adresse	Mandant
`schule-a.kompetenzhub.ch`	`schule-a`
`schule-b.kompetenzhub.ch`	`schule-b`
`informatik.kompetenzhub.ch`	`informatik` (z. B. eine Abteilung)

Anmeldung, Branding und alle Inhalte richten sich automatisch nach der aufgerufenen Subdomain.
Ein Anmelde-Token gilt nur auf der Subdomain seiner Schule – ein versehentlicher oder böswilliger Zugriff über eine fremde Subdomain wird abgewiesen.
Eine unbekannte Subdomain führt zu „Unbekannte Schule".

Lokal / ohne Subdomain: Bleiben TENANT_BASE_DOMAIN und NEXT_PUBLIC_TENANT_BASE_DOMAIN leer, verhält sich die Instanz wie eine Einzel-Schule und nutzt den Default-Mandanten (http://localhost:3000). So bleibt der bisherige Betrieb unverändert.

22.2 Voraussetzungen (Betrieb)

Wildcard-DNS: *.kompetenzhub.ch zeigt auf die Instanz.
Wildcard-TLS-Zertifikat: *.kompetenzhub.ch (Let's Encrypt via DNS-01).
Reverse-Proxy, der Host/X-Forwarded-Host durchreicht (Beispiel Caddy in docs/multi-tenant.md).
In der .env: TENANT_BASE_DOMAIN, NEXT_PUBLIC_TENANT_BASE_DOMAIN und SUPERADMIN_EMAILS setzen (siehe Kapitel 11).

22.3 Eine neue Schule anlegen (Plattform-Admin)

„Plattform-Admins" (in SUPERADMIN_EMAILS eingetragen) verwalten die Schulen mandantenübergreifend – im Unterschied zur Schuladmin, die nur die eigene Schule verwaltet.

Als Plattform-Admin anmelden. In der Navigation erscheint der Punkt „Schulen" (/platform).
Neue Schule mit Slug (wird zur Subdomain), Name und optionaler Admin-E-Mail anlegen.
Die angegebene Admin-E-Mail erhält beim ersten Login automatisch Schuladmin-Rechte und richtet danach ihre Schule selbst ein (Personen, Branding, Anmelde-Anbieter …).
Dank Wildcard-DNS ist die neue Subdomain sofort erreichbar – kein erneutes Deployment nötig.

Alternativ per API:

POST /api/v1/platform/tenants
{ "slug": "schule-a", "name": "Schule A", "adminEmail": "admin@schule-a.ch" }

Schuladmin bearbeiten: Über den Knopf „Admins" je Schule lässt sich der/die Schuladmin verwalten – weitere Admins per E-Mail hinzufügen (bestehende Konten werden sofort befördert, sonst wird eine Einladung erstellt) sowie Admins entfernen bzw. Einladungen widerrufen. Die Schule behält immer mindestens eine:n aktive:n Admin.

Speicherquota je Schule: In der Schulliste lässt sich pro Schule über „Quota" die gekaufte Speicherquota (in GB, leer = unbegrenzt) setzen. Sie begrenzt den Gesamtverbrauch der Schule; die Schuladmin verteilt daraus persönliche Quotas an die Lehrpersonen (siehe Kapitel 9.5). Ist die Quota erschöpft, werden weitere Uploads dieser Schule abgewiesen.

Schule deaktivieren/löschen: Schulen lassen sich deaktivieren (Zugriff gesperrt, Daten bleiben) oder endgültig löschen – beim Löschen werden alle Daten der Schule (Personen, Module, Klassen, Nachweise, Fachgespräche, Plugin-/KI-Daten) unwiderruflich entfernt. Der Default-Mandant kann nicht gelöscht werden.

22.4 Datentrennung & Sicherheit

Jeder Datensatz ist fest an eine Schule gebunden; eine zentrale Scoping-Schicht verhindert schulübergreifende Zugriffe.
Personen können grundsätzlich Mitglied mehrerer Schulen sein (getrennte Rollen je Schule); der Zugriff erfolgt jeweils über die passende Subdomain.
Für strikt getrennte Trägerschaften bleibt die Einzelinstanz pro Schule möglich (Basisdomain-Variablen leer lassen).

KompetenzHub · Benutzerhandbuch · weitere technische Dokumentation siehe Ordner docs/.

Name		Name	Last commit message	Last commit date
Latest commit History 123 Commits
.github		.github
apps		apps
docs		docs
infra		infra
maintenance		maintenance
planung		planung
plugins		plugins
scripts		scripts
vorlagen		vorlagen
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.nojekyll		.nojekyll
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
docker-compose_dev.yaml		docker-compose_dev.yaml
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.base.json		tsconfig.base.json

Folders and files

Latest commit

History

Repository files navigation