generated from bastian/boilerplate
124 lines
5.5 KiB
Markdown
124 lines
5.5 KiB
Markdown
# 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
|
|
- [OIDC-Administratoren](docs/oidc-administrator.md): sichere Admin-Synchronisierung und Recovery
|
|
- [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.
|