Architektur

Das Repository ist ein modularer Monolith mit getrennten Workspaces fuer Frontend, Backend und API-Client. Ausgeliefert wird eine einzelne Node.js-App, die die gebaute Angular-Anwendung statisch mitliefert.

Workspaces

apps/frontend
apps/backend
packages/api-client

Es wird bewusst kein Nx eingesetzt. Workspace-Grenzen bleiben durch npm-Scripts, TypeScript-Projekte und klare Importpfade nachvollziehbar.

Backend

Das Backend liegt in apps/backend und basiert auf NestJS. Es ist nach Features geschnitten:

auth: OIDC Login, Callback, Logout und Authentifizierung
sessions: serverseitige Sessions, CSRF-Token und Session-Listen
roles: Code-definierte Permissions und rollenbasierte Rechteverwaltung
users: lokale Benutzerprofile und Einstellungen
admin: Angular-Routen unter /admin fuer Benutzer-, Rollen-, Session- und Audit-Verwaltung
items: Beispiel-Fachmodul
notifications: persoenliche In-App-Benachrichtigungen, Admin-Erzeugung und interner Service
audit: Audit-Log fuer administrative Nachvollziehbarkeit
health: Liveness- und Readiness-Endpunkte
database: TypeORM-Konfiguration, Entities und Migrationen
common: Fehlerformat, Request Context, Validierung und HTTP-Helfer

Controller enthalten keine Datenbanklogik. Sie validieren den HTTP-Rand, deklarieren Permissions und delegieren an Services. Services enthalten Fachlogik. Datenbankzugriffe laufen ueber Repository-Klassen oder klar benannte Persistence-Services.

Globale Backend-Bausteine:

ApiExceptionFilter normalisiert Fehlerantworten.
ThrottlerGuard setzt Rate Limits.
CsrfGuard schuetzt schreibende Requests.
PermissionsGuard prueft Rollen und Permissions.
RequestIdMiddleware setzt Request-Korrelation.
helmet setzt Security Header.
pino-http loggt mit Redaction fuer Cookies, Tokens und Secrets.

Frontend

Das Frontend liegt in apps/frontend und nutzt Angular Standalone Components. Der Shell-Aufbau steckt in src/app/layout/app-shell.ts. Feature-Seiten liegen unter src/app/features.

Design- und Implementierungsregeln:

mobile-first HTML und SCSS
keine UI-Komponentenbibliothek
Signals fuer lokalen UI-State
RxJS fuer HTTP- und API-Flows
Angular Permissions nur fuer Darstellung und Navigation, nicht als Sicherheitsgrenze

Der permissionGuard verhindert unpassende Navigation im Frontend. Die verbindliche Autorisierung findet immer im Backend statt.

API-Client

packages/api-client enthaelt den vom Frontend genutzten Angular-Service und die DTO-Typen. Der Code ist als generiert markiert. Er wird mit folgendem Befehl neu geschrieben:

npm run api:generate

Der Produktionsbuild ruft diesen Schritt vor Backend- und Frontend-Builds auf. Bei API-Aenderungen muss der Generator synchron zur Backend-API angepasst werden.

Runtime-Aufbau

Im Produktionsbuild entsteht:

apps/backend/dist/main.js
apps/backend/dist/public/index.html
apps/backend/dist/public/assets...

NestJS liefert:

/api/* als JSON API
/api/docs als Swagger UI, wenn aktiviert
/health/live fuer Liveness
/health/ready fuer Readiness inklusive Datenbank- und Migrationspruefung
alle anderen Pfade als Angular SPA Fallback

Datenmodell und Migrationen

TypeORM laeuft mit:

synchronize: false
migrationsRun: false
expliziten Migrationen unter apps/backend/src/database/migrations

Der normale App-Start fuehrt keine Migrationen aus. Stattdessen prueft MigrationHealthService, ob Migrationen fehlen. Dadurch wird verhindert, dass ein App-Rollout unbemerkt ein Schema veraendert.

Autorisierung

Permissions werden in apps/backend/src/roles/permissions.ts definiert. Rollen sind Datenbankdaten, Benutzer erhalten Permissions nur ueber Rollen.

Systemrollen:

admin: alle Permissions
user: Basisrechte fuer Items-Lesen und eigene Sessions

Die Standardrolle user enthaelt ausserdem notifications.readOwn und notifications.updateOwn, damit angemeldete Benutzer ihre eigenen In-App-Benachrichtigungen verwalten koennen.

Der erste erfolgreich angemeldete Benutzer wird automatisch Admin. Danach erhalten neue Benutzer initial die Rolle user.

Details zu Admin-Endpunkten, Systemrollen und dem transaktionalen Schutz des letzten aktiven Administrators stehen in Adminbereich.

4.2 KiB Raw Permalink Blame History