ApiCore – Projektkontext für Claude Code

Digitale Imkereiverwaltung für Wabenhain. Fachliche Quelle der Wahrheit: docs/lastenheft.md. Architektur- und Modulschnitt: ARCHITECTURE.md. Fortschritt/Aufgaben: 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).

# 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):

# 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.

3.5 KiB Raw Blame History Unescape Escape