# 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

1. Repository kopieren oder als Template verwenden.
2. Paketnamen und Beschreibungen in `package.json`, `apps/*/package.json` und
   `packages/api-client/package.json` anpassen.
3. UI-Name `Business App` in `apps/frontend/src/app/layout/app-shell.ts` ersetzen.
4. Swagger-Titel und Beschreibung in `apps/backend/src/main.ts` ersetzen.
5. Docker-Image-Namen in README, CI und Compose auf den Projektnamen aendern.
6. `.env.example` auf die Zielumgebung zuschneiden, aber keine Secrets eintragen.
7. 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:

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

Frontend:

1. Page unter `apps/frontend/src/app/features/<feature>` erstellen.
2. Route in `app.routes.ts` anlegen.
3. Navigation in `app-shell.ts` ergaenzen.
4. Permission im Route-`data` und in der Navigation konsistent setzen.
5. API-Client ueber `packages/api-client` verwenden.
6. 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.