77 lines
3.5 KiB
Markdown
77 lines
3.5 KiB
Markdown
# ApiCore – Projektkontext für Claude Code
|
||
|
||
Digitale Imkereiverwaltung für Wabenhain. Fachliche Quelle der Wahrheit: [`docs/lastenheft.md`](docs/lastenheft.md). Architektur- und Modulschnitt: [`ARCHITECTURE.md`](ARCHITECTURE.md). Fortschritt/Aufgaben: [`TASKS.md`](TASKS.md).
|
||
|
||
## Ordnerstruktur
|
||
|
||
```
|
||
ApiCore/
|
||
├── docs/lastenheft.md Fachliches Lastenheft (verbindlich)
|
||
├── ApiCore-Backend/ NestJS API (TypeScript, Prisma, PostgreSQL)
|
||
├── ApiCore-Frontend/ Next.js App Router (TypeScript, Tailwind, shadcn/ui)
|
||
├── deploy/k8s/ Kubernetes-Manifeste (Deployment, Service, Ingress, ConfigMap/Secret-Vorlagen)
|
||
├── CLAUDE.md Diese Datei
|
||
├── ARCHITECTURE.md Modulschnitt, Auth-Flow, Entscheidungen/Abweichungen
|
||
└── TASKS.md Abhakbare Aufgabenliste (MVP / v1.x / Später)
|
||
```
|
||
|
||
Ein Git-Repo für beide Projekte gemeinsam, Root ist `ApiCore/`. Feature-Branches pro Modul, siehe TASKS.md.
|
||
|
||
## Tech-Stack
|
||
|
||
**Backend** (`ApiCore-Backend/`): Node.js, TypeScript, NestJS, Prisma ORM gegen PostgreSQL (`DATABASE_URL` aus Environment), class-validator/class-transformer für Validierung, @nestjs/swagger für OpenAPI unter `/api/v1/...`, JWT-Auth (Access + Refresh, Passport), Jest für Tests.
|
||
|
||
**Frontend** (`ApiCore-Frontend/`): Next.js (App Router), TypeScript, Tailwind CSS, shadcn/ui, TanStack Query, Vitest + React Testing Library für Tests. Mobile-first, PWA-Manifest von Anfang an.
|
||
|
||
**Betrieb**: Beide Projekte containerisiert, bestehendes Kubernetes-Cluster. PostgreSQL läuft selbst im Cluster als `StatefulSet` (`deploy/k8s/postgres/`, kein externer Managed-Service) – Backup-Verantwortung liegt damit bei diesem Projekt, siehe ARCHITECTURE.md Abschnitt 8.
|
||
|
||
## Lokal starten
|
||
|
||
Voraussetzung Backend: laufende PostgreSQL-Instanz, `.env` mit `DATABASE_URL` (siehe `.env.example`).
|
||
|
||
```bash
|
||
# Backend
|
||
cd ApiCore-Backend
|
||
npm install
|
||
npx prisma migrate dev # Schema anwenden
|
||
npm run start:dev # http://localhost:3001, Swagger unter /api/v1/docs
|
||
|
||
# Frontend
|
||
cd ApiCore-Frontend
|
||
npm install
|
||
npm run dev # http://localhost:3000, erwartet Backend unter API_URL (Laufzeit-Env, siehe .env.example)
|
||
```
|
||
|
||
## Lint / Typecheck / Tests / Build
|
||
|
||
Pro Projekt einzeln ausführen (eigenes `package.json`):
|
||
|
||
```bash
|
||
# Backend (in ApiCore-Backend/)
|
||
npm run lint
|
||
npm run typecheck # tsc --noEmit
|
||
npm run test # Jest unit
|
||
npm run test:e2e # Jest e2e (gegen Test-DB)
|
||
npm run build
|
||
|
||
# Frontend (in ApiCore-Frontend/)
|
||
npm run lint
|
||
npm run typecheck
|
||
npm run test
|
||
npm run build
|
||
```
|
||
|
||
**Regel:** Nach jedem abgeschlossenen Modul müssen Lint, Typecheck, Tests und Build für das betroffene Projekt grün sein, bevor in TASKS.md ein Haken gesetzt und committet wird.
|
||
|
||
## Kernprinzipien (siehe ARCHITECTURE.md für Details)
|
||
|
||
- API-first: jede fachliche Funktion über `/api/v1/...` erreichbar, nicht nur UI-seitig.
|
||
- Historie statt Löschen: fachliche Objekte werden nie hart gelöscht, nur deaktiviert/aufgelöst.
|
||
- Rollen serverseitig in jedem Endpunkt geprüft (Guards/Decorators), nicht nur UI-seitig ausgeblendet.
|
||
- Rückverfolgbarkeitskette Volk → Durchsicht → Behandlung → Ernte → Schleuderung → Honigcharge → Lagerbehälter muss relational abfragbar sein.
|
||
- Audit-Log-Grundstruktur ist Fundament, wird früh angelegt (Users/Auth-Modul), bevor die restliche MUSS-Liste folgt.
|
||
|
||
## Bekannte Annahmen
|
||
|
||
Fachliche Annahmen, die während der Umsetzung getroffen wurden, stehen in ARCHITECTURE.md unter "Annahmen & offene Fragen". Dort nachsehen, bevor eine neue Annahme getroffen wird.
|