ApiCore/CLAUDE.md

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. Projektstand, offene Punkte und Inhaber-Aufgaben: Gitea-Issues, Einstieg über das Übersichts-Issue (verlinkt in README.md).

Ordnerstruktur

ApiCore/
├── README.md                Einstieg: Zweck, Start, Prüfen, Betrieb, Doku-Landkarte, Projektstand
├── docs/lastenheft.md       Fachliches Lastenheft (verbindlich)
├── docs/pruefung-2026-09.md Prüfberichte, Sicherheitsaudit, Bestandsbuch, AuDHD-Regeln
├── docs/erp-inventar-export.md  Vertrag der Schnittstelle zu ERPNext
├── docs/superpowers/        specs/ (Designs je Teilprojekt) und plans/ (Umsetzungspläne mit Tasks, Rollout-Runbook)
├── ApiCore-Backend/         NestJS API (TypeScript, Prisma, PostgreSQL)
├── ApiCore-Frontend/        Next.js App Router (TypeScript, Tailwind, shadcn/ui)
├── deploy/k8s/              Kustomize: base/, components/, overlays/encry/, tests/, scripts/ (ARCHITECTURE.md Abschnitt 7)
├── .gitea/workflows/        CI: Backend-Image, Frontend-Image, Manifest-Prüfung
├── CLAUDE.md                Diese Datei
├── ARCHITECTURE.md          Modulschnitt, Auth-Flow, Entscheidungen/Abweichungen, Annahmen
└── TASKS.md                 Abhakbare Aufgabenliste (MVP / v1.x / Später / Fahrplan T3–T7 / Beute)

Ein Git-Repo für beide Projekte gemeinsam, Root ist ApiCore/. Gearbeitet wird direkt auf main; größere Vorhaben bekommen vorher eine Spec und einen Plan unter docs/superpowers/. Commits werden gebündelt gepusht, weil jeder Push auf main die Image-Builds startet. Ausrollen ins Cluster nur mit Freigabe des Inhabers.

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/base/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 nur mit ENABLE_SWAGGER=true

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