hellth-hub/.claude/rules.md

Claude Project Rules - Hellth Hub

1. Type Safety

• TypeScript strict mode
• Kein any
• Keine unsicheren Type Assertions (as X)
• Drizzle-Query-Builder-Typen nutzen statt eigene Interfaces dupliziert beschreiben

2. Trennung der Verantwortlichkeiten

Business-Logik  → packages/api  (tRPC Router, Coach, Domain-Helper)
DB-Logik        → packages/db   (Drizzle-Schema, Migrationen)
Apps            → apps/admin    (nur UI + dünner Glue zur API)

Die Admin-App enthält keine Business-Logik. Wenn Berechnung in beiden Seiten gebraucht wird (z. B. Nährwerte), gehört der Kanon in packages/api/src/lib/; das Frontend bekommt ihn über tRPC oder dupliziert nur die UI-nahe Anzeige-Variante in apps/admin/lib/hellth-data.ts.

3. Domäne

Hellth Hub ist eine Single-User-Health-App pro Benutzer-Account. Datenmodell siehe packages/db/src/schema/health.ts (Foods, Recipes, MealLogs, ShoppingLists, Stores, ActivityLogs, Wearables, ClubActivities, Coach …).

Keine Naturfreunde-Begriffe wiederbeleben (News, Events, Fachgruppen, Mandanten, Häuser, Buchungen, tenantId, verband_admin, haus_admin, Mitgliedsausweise, Google-Wallet).

4. Rollen

• user (default) - normaler Benutzer
• admin - Plattform-Admin (z. B. admin@onl1.eu)
• Admins haben Pflicht-2FA (siehe enforceTwoFactorForPrivilegedUsers in packages/api/src/trpc/init.ts)

Rechte immer serverseitig prüfen (tRPC-Procedure-Auswahl: protectedProcedure für eingeloggte User, platformProcedure für Admins).

5. Performance

• Keine N+1-Queries (Drizzle .with() / Joins / inArray für Batch-Loads nutzen)
• Listen-Endpoints mit Suche: Filterung auf DB-Seite (ilike), nicht in-Memory
• Index-Pfade respektieren (siehe Index-Definitionen in schema/health.ts)

6. Sicherheit

• Auth-Pflicht für alle Routen außer Login / Health-Check
• Keine Secrets im Repo - nur .env (in .gitignore)
• 2FA-Recovery nur für Admins (platformProcedure)
• Bei twoFactorRecoveryRequired = true muss 2FA-Neueinrichtung erzwungen werden
• Login auf /login/otp muss sowohl TOTP-Code als auch Backup-Code unterstützen
• Better-Auth-Konfiguration (packages/api/src/lib/auth.ts) ist Single Source of Truth für Auth-Optionen
• CSP / Security-Headers in apps/admin/next.config.ts und packages/api/src/app.ts synchron halten

User-Security-Felder (aktiv)

twoFactorEnabled
twoFactorRecoveryRequired
twoFactorRecoveryStartedAt
twoFactorRecoveryStartedBy

7. UI-Regeln

• Mobile-first - Hellth Hub wird primär am Handy benutzt
• Klar, modern, funktional - keine visuellen Spielereien
• Bottom-Navigation auf Mobile, Sidebar auf Desktop (apps/admin/app/_components/)
• Neue Formulare über FormField und inputClassName aus apps/admin/app/_components/form-field.tsx
• Deutsche UI: echte Umlaute (ä, ö, ü, ß)
• UI-Inspiration siehe docs/inspiration/bitepal/

8. DB-Änderungen

• Schema-Änderung, Migration, API-Endpoint und UI immer zusammen denken
• pnpm --filter @hellth/db db:generate für Migrationen
• Migrationen nicht nachträglich umbenennen oder löschen (Drizzle tracked sie per Datei + Hash)
• Neue Tabellen brauchen passende Indizes für die Haupt-Queries

9. Tests

Mindestens absichern:

• Auth- und 2FA-Pfade
• Nährwert- / Kalorien- / Wochenbudget-Berechnung
• Hellfireclub-Punkte-Logik

Vor PR / größerer Änderung lokal grün:

pnpm --filter @hellth/api test
pnpm --filter admin test
pnpm exec tsc --noEmit --project packages/api/tsconfig.json
$env:NEXT_PUBLIC_API_URL='http://localhost:3002'; pnpm --filter admin build

10. Arbeitsweise mit Claude

• Bestehende User-Änderungen nicht zurücksetzen
• Keine destruktiven Git-Befehle ohne ausdrückliche Anweisung
• Cleanup an Altlasten nur nach expliziter Freigabe (siehe claude-info.md Abschnitt "Bekannte Altlasten")