Als Projektvorlage Verwenden

Dieses Boilerplate ist bewusst nah an einer realen internen Business-Anwendung. Beim Start eines neuen Projekts solltest du zuerst Namen, Branding, Runtime-Konfiguration und Demo-Fachlichkeit ersetzen, aber die Sicherheits- und Betriebsentscheidungen beibehalten.

Empfohlener Start

Repository kopieren oder als Template verwenden.
Paketnamen und Beschreibungen in package.json, apps/*/package.json und packages/api-client/package.json anpassen.
UI-Name Business App in apps/frontend/src/app/layout/app-shell.ts ersetzen.
Swagger-Titel und Beschreibung in apps/backend/src/main.ts ersetzen.
Docker-Image-Namen in README, CI und Compose auf den Projektnamen aendern.
.env.example auf die Zielumgebung zuschneiden, aber keine Secrets eintragen.
Lizenz, Repository-URL, Ownership und Open-Source-Metadaten bewusst setzen.

Was du behalten solltest

Backend-for-Frontend Authentifizierung: OIDC-Tokens bleiben im Backend.
Server-seitige Sessions in MySQL.
CSRF-Schutz fuer alle schreibenden Requests.
TypeORM-Migrationen statt synchronize.
Controller delegieren an Services; Datenbankzugriff liegt in Repositories oder klar benannten Persistence-Services.
Permissions sind Code, Rollen sind Daten.
Keine UI-Library als versteckte Projektbindung.
Striktes TypeScript ohne any.

Demo-Fachlichkeit entfernen oder ersetzen

Das Modul items ist ein Beispiel fuer ein einfaches fachliches CRUD-Modul mit optimistischer Versionierung und Soft Delete. Fuer ein neues Projekt gibt es zwei saubere Optionen:

Behalten und in das erste echte Fachmodul umbenennen.
Entfernen und anhand der Struktur ein neues Modul erstellen.

Wenn du items entfernst, pruefe mindestens:

Backend-Import in apps/backend/src/app.module.ts
Entity-Export in apps/backend/src/database/entities.ts
Initiale Migration und neue Migration fuer Schema-Aenderungen
Permissions in apps/backend/src/roles/permissions.ts
Routen in apps/frontend/src/app/app.routes.ts
Navigation in apps/frontend/src/app/layout/app-shell.ts
API-Client-Generator in scripts/generate-api-client.mjs
Frontend-Pages und Tests unter apps/frontend/src/app/features/items

Ein neues Feature anlegen

Backend:

Feature-Ordner unter apps/backend/src/<feature> anlegen.
Entity, DTOs, Repository, Service, Controller und Module erstellen.
Controller nur mit Services verdrahten.
Datenbankzugriff im Repository kapseln.
Permissions in roles/permissions.ts ergaenzen.
Controller-Methoden mit @RequirePermissions(...) schuetzen.
Entity in database/entities.ts aufnehmen.
Migration erzeugen und pruefen.
Verhaltenstests fuer Service oder Controller schreiben.

Frontend:

Page unter apps/frontend/src/app/features/<feature> erstellen.
Route in app.routes.ts anlegen.
Navigation in app-shell.ts ergaenzen.
Permission im Route-data und in der Navigation konsistent setzen.
API-Client ueber packages/api-client verwenden.
Verhaltenstests fuer relevante UI-Logik schreiben.

API-Client:

Aktuell schreibt scripts/generate-api-client.mjs den Client reproduzierbar aus einer gepflegten Vorlage. Wenn die API waechst, muss der Generator erweitert oder durch eine echte OpenAPI-Codegenerierung ersetzt werden. Der Client selbst ist generierter Code und sollte nicht manuell editiert werden.

Open-Source-Veroeffentlichung

Vor einer Veroeffentlichung als Open-Source-Projekt:

license in package.json bewusst setzen.
LICENSE und optional NOTICE hinzufuegen.
Namen, Screenshots, Domaenen, Beispiel-Registry und interne Hinweise entfernen.
Beispiel-Secrets in .env.example nur als Platzhalter belassen.
Pruefen, ob alle Dependencies und generierten Artefakte lizenzkompatibel sind.
Sicherheitsmodell in README und docs/security.md aktuell halten.

Projektgrenzen

Dieses Boilerplate ist fuer eine einzelne deploybare Business-Anwendung gebaut. Es ist kein Microservice-Framework, kein Nx-Workspace und keine Multi-Tenant Plattform. Wenn ein Projekt diese Grenzen braucht, sollte die Architektur zuerst bewusst erweitert werden, statt sie indirekt ueber Feature-Code einzuschleppen.

4.1 KiB Raw Blame History