initial

README.md

@@ -0,0 +1,118 @@
+# 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
+- 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
+- [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.