Angular/NestJS Business Boilerplate

Production-ready npm-Workspace-Monorepo fuer interne Business-Anwendungen mit Angular 22, NestJS 11, Node.js 24.18 LTS, TypeORM, MySQL 8, OIDC, serverseitigen Sessions und Vitest.

Dieses Repository ist als Startpunkt fuer eigene Projekte gedacht. Es bringt die technischen Grundentscheidungen mit, die in internen Business-Anwendungen haeufig spaet und teuer nachgezogen werden: Backend-for-Frontend Authentifizierung, rollenbasierte Autorisierung, CSRF-Schutz, serverseitige Sessions, Migrationen, Docker-Auslieferung, Healthchecks und eine einfache Angular-Verwaltungsoberflaeche.

Was enthalten ist

• npm Workspaces ohne Nx: apps/frontend, apps/backend, packages/api-client
• Angular Standalone Components, mobile-first SCSS und keine UI-Library
• NestJS API mit modularen Features, Services, Repositories, Guards und DTOs
• OIDC Authorization Code Flow mit PKCE; Tokens bleiben ausschliesslich im Backend
• HttpOnly Session-Cookie plus CSRF-Cookie/Header fuer schreibende Requests
• konfigurierbares In-Memory Rate Limiting pro IP mit strengeren sensiblen Endpunkten
• MySQL-8-Persistenz mit TypeORM, Migrationen und Startpruefung auf fehlende Migrationen
• Code-definierte Permissions, Rollenverwaltung, Benutzerverwaltung, Audit-Log und Sessions
• In-App-Benachrichtigungen mit Polling, Badge, eigener Seite und Admin-Erzeugung
• Generierter API-Client fuer das Angular-Frontend
• Dockerfile und Compose-Beispiel fuer eine einzelne auslieferbare App

Schnellstart

npm ci
cp .env.example .env
npm run dev

Angular laeuft lokal auf http://localhost:4200 und proxyt /api an NestJS auf http://localhost:3000. Eine MySQL-8-Datenbank und ein OIDC Provider muessen konfiguriert sein; Compose startet bewusst keine lokale Datenbank.

Wichtige Befehle

npm run dev              # Frontend und Backend parallel starten
npm run lint             # ESLint fuer alle Workspaces
npm run format:check     # Prettier-Pruefung
npm run typecheck        # TypeScript-Pruefung aller Workspaces
npm test                 # Backend- und Frontend-Tests
npm run build            # API-Client, Backend, Frontend und Bundle bauen
npm run migration:status # offene TypeORM-Migrationen anzeigen
npm run migration:run    # Migrationen ausfuehren
npm run docker:build     # Docker-Image bauen

Vor einem Merge oder Release muessen npm run lint, npm run format:check, npm run typecheck, npm test, npm run build und docker build . erfolgreich laufen.

Dokumentation

• Getting Started: lokaler Start, Konfiguration und erster Login
• Als Projektvorlage verwenden: Umbenennen, Entfernen von Demo-Code und erste fachliche Erweiterung
• Architektur: Monorepo, Backend, Frontend, API-Client und Modulgrenzen
• Entwicklung: Workflows fuer Features, Migrationen, Tests und API-Client
• Security-Modell: OIDC, Sessions, CSRF, Rollen, Permissions und Logging
• OIDC-Administratoren: sichere Admin-Synchronisierung und Recovery
• Designsystem: Tokens, UI-Komponenten, responsive Regeln und Accessibility
• Adminbereich: Benutzer, Rollen, Sessions, Audit und letzter-Admin-Schutz
• Benachrichtigungen: Datenmodell, API, Permissions, Polling und Erweiterung
• Deployment und Betrieb: Build, Docker, Migrationen, Runtime-Konfiguration und Healthchecks
• Konfiguration: Umgebungsvariablen und Produktionshinweise
• Nginx-Beispiel: Reverse Proxy mit HTTPS-Terminierung

Repository-Struktur

apps/
  backend/      NestJS API, Auth, Sessions, Rollen, Fachmodule, Migrationen
  frontend/     Angular SPA, Shell, Feature Pages, Guards, Interceptor
packages/
  api-client/   generierter Angular API-Client
scripts/        Build- und Generator-Hilfsskripte
docs/           Betriebs-, Architektur- und Starter-Dokumentation

Auslieferungsmodell

Der Produktionsbuild erzeugt eine einzelne NestJS-Anwendung. Das Angular-Frontend wird nach apps/backend/dist/public kopiert und vom Backend unter / ausgeliefert. Die API liegt unter /api, Swagger optional unter /api/docs und Healthchecks unter /health/live sowie /health/ready.

Ein typisches Release:

npm ci
npm run lint
npm run format:check
npm run typecheck
npm test
npm run build
docker build -t registry.example.com/business-app:<tag> .
docker push registry.example.com/business-app:<tag>

Auf der Zielumgebung werden Migrationen einmalig mit demselben Image ausgefuehrt, danach wird der App-Container gestartet. Details stehen in Deployment und Betrieb.

Sicherheitsgrundsaetze

• OIDC-Tokens werden nur serverseitig gespeichert und verschluesselt.
• Der Browser erhaelt keine Access-, Refresh- oder ID-Tokens.
• Session-Cookies enthalten nur eine signierte Session-ID.
• Schreibende Requests brauchen ein gueltiges CSRF-Token.
• Permissions sind im Code definiert; Benutzer erhalten Rechte nur ueber Rollen.
• Migrationen laufen nie automatisch beim normalen App-Start.
• Secrets, Tokens, Cookies und Session-IDs duerfen nicht geloggt werden.

Lizenzierung fuer eigene Projekte

Das Root-package.json ist aktuell private und UNLICENSED. Wenn dieses Boilerplate als Open-Source-Startpunkt veroeffentlicht werden soll, muessen vor der Veroeffentlichung eine passende Lizenzdatei, Paketnamen, Repository-Links und Projektmetadaten bewusst gesetzt werden.