Technische Dokumentation
Betriebshandbuch.
Technische Dokumentation, Architektur & Betriebsprozesse der IT42 E-Learning-Plattform (TrainingsPower).
Version 1.0 · Stand: 19.10.2026
1. Architektur-Übersicht
TrainingsPower ist eine mandantenfähige E-Learning- und Zertifizierungsplattform. Das System basiert auf einer Single-Page-Application (React) im Browser und einem serverlosen Backend (Base44 BaaS) für Datenhaltung, Authentifizierung und sicherheitskritische Geschäftslogik.
Technologie-Stack
Frontend
React 18 (SPA), React Router für das Routing, Tailwind CSS für das IT42-Design-System, Vite als Build-Tool. Datenabruf & Cache über TanStack Query, Animationen über Framer Motion.
Backend / BaaS
Base44 – serverlose Deno-Funktionen (base44/functions), Entity-Datenbank mit JSON-Schema, integrierte Authentifizierung sowie Row-Level-Security (RLS).
Authentifizierung
Base44 Auth: Registrierung mit E-Mail/Passwort, Verifizierung per 6-stelligem OTP-Code, Passwort-Reset. Rollenmodell: superadmin, company_admin, employee.
E-Mail-Versand
Microsoft Graph API (Office 365) über den authorisierten Outlook-Connector. Versand von Willkommens- und Prüfungs-Code-Mails aus dem eigenen IT42-Postfach (SMTP ist plattformseitig blockiert, daher HTTPS/Graph).
Zertifikats-Sicherheit
HMAC-SHA256-Siegel mit serverseitigem Geheimnis (IT42_SEAL_SECRET). Öffentliche Verifizierung über eine dedizierte Prüfseite inkl. QR-Code.
KI-Vertiefungs-Mentor
Optionaler AI-Assistent je Schulung (Enterprise). Kontext wird serverseitig über mentorContext bereitgestellt und ist strikt auf die jeweilige Schulung beschränkt. Die Konversation läuft über den Base44-Agenten training_mentor; der Zugriff ist an den aktiven Lizenzstatus der Firma gebunden.
Hosting / Auslieferung
Auslieferung als statische SPA über die Base44-Plattform. Aus demselben Code sind native iOS-/Android-Builds möglich (Mobile-First, Safe-Area, Bottom-Tab-Bar).
Schichten
Präsentationsschicht (Browser)
Öffentliche Seiten (Landing, Login, Registrierung, Hilfe, Zertifikats-Verifizierung) und geschützte Bereiche (Mitarbeiter-Dashboard, Admin-Konsole). Gerendert clientseitig, geschützte Routen liegen im gemeinsamen Layout.
Logikschicht (Backend-Funktionen)
Sicherheitskritische Abläufe laufen ausschließlich serverseitig: Prüfungscode-Versand & -Verifizierung, Prüfungsabgabe samt Bewertung, Zertifikatssiegelung, Firmen-/Nutzerverwaltung. Der Client kann Ergebnisse nicht manipulieren.
Datenschicht (Entities)
Persistente Speicherung in Entities mit JSON-Schema und RLS. Zugriff wird pro Mandant (Firma) und Rolle eingeschränkt.
Datenfluss (Beispiel Prüfung)
Beispiel Prüfung: Der Client fordert über sendExamCode einen Code an → Server prüft Lizenz/Demo, erzeugt eine ExamSession (Code nur als Hash gespeichert) und versendet den Code per Graph API. Nach Eingabe verifiziert verifyExamCode serverseitig. Die Abgabe über submitExam bewertet die Antworten gegen die Server-Daten, erstellt TestAttempt und – bei Bestehen – ein gesiegeltes Certificate. Kein Score und kein Zertifikat entsteht clientseitig.
Datenfluss (Beispiel KI-Mentor)
Beispiel KI-Mentor: In der Schulungsansicht prüft die Komponente TrainingMentor über mentorContext, ob die Firma des Nutzers aktiv (Enterprise) ist – nur dann erscheint der schwebende Button. Beim Öffnen liefert mentorContext den auf die Schulung beschränkten Kontext, der als verstecktes Start-Prompt an eine neue training_mentor-Konversation übergeben wird. Der Agent bleibt strikt beim Schulungsthema und schlägt aktiv Vertiefungsthemen vor. Ohne aktive Lizenz antwortet mentorContext mit HTTP 402 (no_license) und der Mentor bleibt verborgen.
2. Datenmodell (Entities)
Die folgenden Kern-Entities bilden das Datenmodell. Jede Entity besitzt zusätzlich die System-Attribute id, created_date, updated_date und created_by_id. Die vollständigen JSON-Schemata inkl. RLS-Regeln liegen unter base44/entities/ und sind im Anhang exportierbar.
Kern-Entities
Company
Mandant / Firma. Felder u. a. name, logo_url, contact_email, active. Lizenzsteuerung über access_status (active = Schulungen freigeschaltet, suspended = nur Demo) und access_note (Agreement-Notiz).
User (integriert)
Nutzerkonto. Rolle über role (superadmin / company_admin / employee), Zuordnung über company_id, optional employee_id und display_name. full_name/email sind schreibgeschützte Built-ins.
Training
Schulung mit Lernmodulen (modules → pages → blocks), Fragen-Pool-Steuerung (questions_per_test), Bestehensgrenze (passing_score), Mehrsprachigkeit (translations/languages), Aktiv-Status (active) und Demo-Flag (is_demo).
Question
Prüfungsfrage je Schulung (training_id). Typ single/multi, Antwortoptionen mit is_correct, optionale Erklärung. Bildet den Pool, aus dem pro Versuch zufällig gezogen wird.
TrainingAssignment
Zuweisung einer Schulung an eine Firma (company_id, training_id, due_date). Steuert, welche Schulungen den Mitarbeitern einer Firma erscheinen.
ExamSession
Serverseitige Prüfungs-Session. Speichert den Prüfungscode nur als code_hash, dazu expires_at, verified, consumed und declaration_accepted. Verhindert Client-seitige OTP-Manipulation.
TestAttempt
Protokoll eines Prüfungsversuchs: score, passed, attempt_number, answers. Serverseitig erzeugt, Grundlage für Fortschritts- und Ergebnisauswertungen.
Certificate
Ausgestelltes Zertifikat mit certificate_id, Personen-/Firmen-/Schulungsdaten, score, Prüf-Metadaten (started_at, duration_seconds, email_verified, declaration_accepted) und dem elektronischen seal (HMAC-SHA256).
Beziehungen
- Company 1—n User (company_id): eine Firma hat viele Mitarbeiter/Firmen-Admins.
- Company n—m Training über TrainingAssignment: Firmen erhalten Zugriff auf zugewiesene Schulungen.
- Training 1—n Question: jede Schulung besitzt ihren eigenen Fragen-Pool.
- User + Training → ExamSession → TestAttempt → Certificate: die Prüfungskette pro Versuch.
3. Sicherheitsmodell
Sicherheit wird konsequent serverseitig durchgesetzt. Der Client kann weder Prüfungsergebnisse noch Zertifikate fälschen, da alle sensiblen Entscheidungen im Backend getroffen werden.
Maßnahmen
Row-Level-Security (RLS)
Auf den Kern-Entities (Certificate, TestAttempt, Company, Training u. a.) sind RLS-Regeln aktiv. Mitarbeiter sehen nur ihre eigenen Daten bzw. Daten ihrer Firma; Schreib-/Löschrechte sind auf superadmin beschränkt.
Rollenbasierter Zugriff
superadmin (gesamte Plattform), company_admin (auf eine Firma beschränkt), employee (nur eigene Schulungen). Backend-Funktionen prüfen die Rolle und den Firmen-Scope bei jeder Aktion.
Serverseitige Prüfungslogik
sendExamCode, verifyExamCode und submitExam laufen ausschließlich serverseitig. Codes werden nur als Hash gespeichert, Sessions haben Ablauf (expires_at) und Einmal-Einlösung (consumed). Bewertung erfolgt gegen Server-Daten.
Lizenz-/Demo-Durchsetzung
Vor Prüfungsstart und -abgabe prüft der Server access_status der Firma bzw. das is_demo-Flag der Schulung. Ohne Freischaltung wird mit HTTP 402 (no_license) abgewiesen. Der KI-Vertiefungs-Mentor ist ebenfalls an eine aktive Lizenz gebunden – mentorContext gibt ohne Freischaltung 402 zurück, sodass der Mentor gar nicht erst erscheint.
KI-Kontext-Isolierung
Der Vertiefungs-Mentor erhält seinen Kontext ausschließlich serverseitig über mentorContext und ist strikt auf die jeweilige Schulung beschränkt. Der Agent training_mentor besitzt keine Entity-Rechte und kann daher keine fremden Daten abrufen.
Zertifikats-Integrität
Jedes Zertifikat trägt ein HMAC-SHA256-Siegel (Geheimnis IT42_SEAL_SECRET). Manipulierte Daten führen bei der öffentlichen Verifizierung zu einem ungültigen Siegel.
E-Mail- & Injection-Schutz
E-Mail-Adressen werden validiert, dynamische Werte in E-Mail-Templates werden HTML-escaped, um HTML-/Script-Injection zu verhindern.
Clickjacking-Schutz
Das Einbetten der Anwendung in fremde iframes wird global unterbunden.
Secrets & Connector
IT42_SEAL_SECRET
Geheimer Schlüssel für das HMAC-SHA256-Zertifikatssiegel.
O365_SMTP_USER / O365_SMTP_PASSWORD / O365_SMTP_FROM
Zugangs- und Absenderdaten für den O365-/Graph-basierten E-Mail-Versand.
Outlook-Connector
Autorisierter OAuth-Connector (Scopes: Mail.Send, offline_access, User.Read) für den Versand über Microsoft Graph.
WICHTIG: Secrets werden ausschließlich als Umgebungsvariablen in der Plattform hinterlegt. Echte Schlüssel oder Passwörter dürfen niemals in diesem Handbuch, im Code oder in Tickets erscheinen.
4. Betriebs- & Wartungsprozesse
Mandanten- & Nutzerverwaltung
- Neue Firma: Super-Admin legt sie unter „Firmen" an und setzt den Lizenzstatus (Freischalten/Sperren) gemäß Agreement.
- Firmen-Admin einladen: unter „Firmen-Admins" per E-Mail; er verwaltet fortan eigenständig seine Firma.
- Mitarbeiter einladen: per E-Mail unter „Mitarbeiter"; die Einladung löst automatisch eine gebrandete IT42-Willkommens-Mail aus (Graph API).
- Verwaltung läuft zentral über die Backend-Funktion manageCompanies mit strikter Rollen- und Firmen-Scope-Prüfung.
Schulungs-Management
- Neue Schulung anlegen, Lernmodule (Text, Bild, interaktive Blöcke) befüllen und den Fragen-Pool pflegen.
- Zufallsfragen pro Versuch (questions_per_test) und Bestehensgrenze (passing_score) festlegen.
- Umfangreiche Kurse über die Import-Funktion strukturiert anlegen.
- Sichtbarkeit steuern: Aktiv/Inaktiv-Status je Schulung; is_demo für frei zugängliche Demo-Schulungen.
- Schulung einer Firma zuweisen (TrainingAssignment), damit sie deren Mitarbeitern erscheint.
Support & Monitoring
- Zertifikatsprüfung: Echtheit über die öffentliche /verify-Seite (Kennung + Siegel + QR-Code) validieren.
- Fortschritt & Ergebnisse: Lernstand und Testversuche pro Firma/Schulung im Admin-Bereich auswerten.
- Zertifikats-Register: zentrale Übersicht aller Zertifikate mit Suche, Firmenfilter, CSV-Export und PDF-Download.
- Backend-Fehler sind über die Funktions-Logs der Plattform (Code → Functions) einsehbar.
Notfall- & Incident-Management
- Passwort vergessen: Mitarbeiter nutzen „Passwort vergessen"; der Reset-Link kommt per E-Mail.
- OTP-Probleme bei der Registrierung: Code über „Code erneut senden" neu anfordern; Codes sind zeitlich begrenzt gültig.
- Prüfungscode kommt nicht an: Spam-Ordner prüfen, ggf. E-Mail-Adresse verifizieren; der Versand läuft über den O365-/Graph-Connector.
- Zugriff blockiert / „no_license": Firma unter „Firmen" auf Lizenzstatus prüfen und ggf. freischalten.
- Konto-Löschung: Nutzer können ihr Konto selbst löschen (App-Store-Konformität) – Aktion deleteOwnAccount.
5. Technische Referenz (Backend-Funktionen)
Übersicht der serverlosen Backend-Funktionen und ihrer Aufgaben.
manageCompanies
Zentrale Verwaltung von Firmen, Mitarbeitern, Firmen-Admins, Zuweisungen und Auswertungsdaten; setzt Rollen- und Firmen-Scope durch.
sendExamCode
Prüft Lizenz/Demo, erzeugt eine ExamSession und versendet den 6-stelligen Prüfungscode per Graph API.
verifyExamCode
Verifiziert den eingegebenen Code serverseitig gegen den gespeicherten Hash und markiert die Session als verifiziert.
submitExam
Bewertet die Prüfungsabgabe serverseitig, erstellt TestAttempt und – bei Bestehen – ein gesiegeltes Certificate.
sealCertificate
Erzeugt/prüft das HMAC-SHA256-Siegel eines Zertifikats.
verifyCertificate
Öffentliche Verifizierung eines Zertifikats über seine Kennung und das Siegel.
mentorContext
Prüft die Enterprise-Lizenz der Firma und liefert den auf eine Schulung beschränkten Kontext für den KI-Vertiefungs-Mentor. Ohne aktive Lizenz Antwort mit HTTP 402 (no_license).
notifyNewUser
Benachrichtigungslogik rund um neu angelegte Nutzer.
sendSmtpEmail
E-Mail-Versand-Hilfsfunktion (O365/Graph).
extractTrainingContent
KI-Extraktion strukturierter Schulungsinhalte für den Admin-Import. Nur Super-Admins; der LLM-Aufruf läuft serverseitig (asServiceRole).