# 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

```bash
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

```bash
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](docs/getting-started.md): lokaler Start, Konfiguration und erster Login
- [Als Projektvorlage verwenden](docs/using-as-template.md): Umbenennen, Entfernen von Demo-Code und erste fachliche Erweiterung
- [Architektur](docs/architecture.md): Monorepo, Backend, Frontend, API-Client und Modulgrenzen
- [Entwicklung](docs/development.md): Workflows fuer Features, Migrationen, Tests und API-Client
- [Security-Modell](docs/security.md): OIDC, Sessions, CSRF, Rollen, Permissions und Logging
- [Designsystem](docs/design-system.md): Tokens, UI-Komponenten, responsive Regeln und Accessibility
- [Adminbereich](docs/admin.md): Benutzer, Rollen, Sessions, Audit und letzter-Admin-Schutz
- [Benachrichtigungen](docs/notifications.md): Datenmodell, API, Permissions, Polling und Erweiterung
- [Deployment und Betrieb](docs/deployment.md): Build, Docker, Migrationen, Runtime-Konfiguration und Healthchecks
- [Konfiguration](docs/configuration.md): Umgebungsvariablen und Produktionshinweise
- [Nginx-Beispiel](docs/nginx-example.conf): Reverse Proxy mit HTTPS-Terminierung

## Repository-Struktur

```text
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:

```bash
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](docs/deployment.md).

## 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.