Architektur

Aufbau

Fachliche Struktur

Der Service ist in folgende fachliche Pakete gegliedert:

• clients: Integration von Fremd-APIs, bislang nur BerufeNet.
• config: Funktionalität zur Konfigurierbarkeit.
• events: Event-System, um auf Ereignisse in MLS zu reagieren.
• feedback: Für User-Feedbacks
• learningPath: Zur Erstellung von vordefinierten Lernpfaden durch Lehrkräfte. Bietet Funktionen wie Hinzufügen, Statusänderung, Validierung, Löschen.
• learningUnit: Für das Management (CRUD) von Lern-Einheiten basierend auf Tasks, erweitert um Skill-basierten Lernansatz.
• logger: Logger-Funktionalität
• pathFinder: Funktionalität zum Einschreiben in durch Lehrkräfte vordefinierte / durch Lernende selbstdefinierte Lernkurse und einer (insofern möglich) Individualsierung dieser Kurse. Verwendet nm-skill-lib.
• skills: Für das Management (CRUD) von Skills.
• user: User-Profile, weiter gegliedert in:
  • CareerProfile: Bisheriger beruflicher Werdegang
  • LernHistorie: Gelernte Lerneinheiten / Skills
  • LearningProfile: Konfiguration der persönlichen Lernpräferenzen (z.B. Density/Gravity), wird innerhalb des Services bislang nicht weiter verwendet.

Zudem befindet sich auf der obersten Ebene im Projekt (nicht in src) der Ordner prisma. Dieser enthält die schema.prisma die Datenbank-Struktur und die Datenbank Zugriffsfunktionalitäten definiert. Im Unterordner migrations werden Datenbank-Migrationen abgelegt, um (idealerweise) ohne Datenverlust die Datenbank bei Änderungen anpassen zu können.

Aufbau der Features

In der Regel bestehen die Pakete aus den folgenden Bestandteilen:

• dto: Dieser Ordner enthält für das Feature notwendige DTO-Objekte. Mittels Barrel Export wird über die index.ts ein zentraler Export angeboten. Die DTOs bieten:
  • Eine explizite und von Prisma unabhängige Definition der Import-/Export-Schnittstellen, was auch bei Datenbankänderungen potentiell eine Beibehaltung der Schnittstellen ermöglicht.
  • Swagger/OpenAI-Unterstützung (siehe "Swagger CLI Plugin" weiter unten). Dazu müssen die Properties der DTOs mit Hilfe des Class-Validators semantisch annotiert werden. Dadurch können zum einen Schnittstellen generiert werden, aber auch Daten aus den Request hinsichtlich gültiger Wertebereich überprüft werden.
  • Die DTOs können in zwei Kategorien unterschieden werden:
    • Import-DTOs: Werden in Form eines Request von außen gesendet und benötigen daher keinen Konstruktor oder dergleichen. Ggf. sind verpflichtende Properties mit einer Non-null Assertion versehen, um fehlerhafte Type-Checks zu vermeiden. In diesem Fall stellt Swagger anhand der dann benötigten @IsDefined()Annotation sicher, dass die Werte gesetzt werden.
    • Export-DTOs: Werden in Form einer Response versendet. Oftmals werden die Daten aus der Datenbank (in Form eines Data Access Objects, kurz DAO) direkt in ein DTO überführt. Daher haben wir in der Regel eine Funktion dafür geschrieben um Code-Duplizierung zu vermeiden und den Code in den Services schlanker halten zu können. Um Probleme bzgl. von Vererbung und dynamischen Typdefinitionen zu vermeiden, sind wir davon abgerückt Konstruktoren zu definieren und verwenden stattdessen in der Regel eine statische createFromDao Funktion.
• *.controller.ts: Realisierung des REST Controllers und der damit verbundenen Endpoints. Die Implementierung ist an dieser Stelle bewusst sehr einfach gehalten und verweist für die Funktionalität auf die zugehörigen Services.
  • *.controller.e2e.spec.ts: End-2-End Testfälle für die REST Endpunkte. Dabei werden DTOs an die entsprechenden Endpunkte gesendet und für den Response die folgenden Parameter getestet: HTTP-Code, Response DTO, Inhalt/Werte der Antwort.
• *.service.ts: Implementierung der eigentlichen Logik.
  • *.service.spec.ts: Unit-Tests für die Logik. Ermöglichen eine gezieltere Synopsis, können aber gerade im Umgang mit dem Framework/HTTP-Zugriffe nicht alle Fehler-Typen identifizieren.
• *.module.ts: Modul-Spezifikation (Meta-Daten) für die Realisierung eines Features.

Frameworks

• NestJS basierend auf Express als REST-Framework.
  • Swagger CLI Plugin zur automatisierten Generierung einer Swagger Seite (http://:/api) und einer OpenAPI Spezifikation, die zu Generierung eines Clients in beliebigen Programmiersprachen genutzt werden kann (http://:/api-json). Das CLI Plugin wertet automatisch alle *.dto.ts Dateien aus und erzeugt daraus DTOs samt Schemata-Spezifikation.
  • Jest: Test-Framework, sowohl für Unit-Tests als auch für E2E-Tests.
• Prisma: Typsicheres ORM-Framework für Typescript.
• Pino als Logging-Framework
• nm-skill-lib: Von uns entwickelte Library zur Pfadplanung/Validierung. Derzeit noch als Git Submodule eingebunden und muss daher immer auf bestimmte Git Revisionen geupdatet werden. Zukünftig als NPM Library geplant. Dieses benötigt zwar einen Access-Token um die Library von GitHub beziehen zu können, bietet aber mehr Kontrolle bei API Änderungen.
• Docker um Anwendung als Docker Container zu verpacken und somit keine unnötigen Abhängigkeiten zum Zielsystem zu erzeugen (installierte Frameworks, Libraries, Datenbanken, etc.).