hellth-hub/claude-info.md

Hellth Hub Projektinfo

Kurzüberblick

Hellth Hub ist eine mobile-optimierte Web-App für persönliches Health-, Ernährungs-, Aktivitäts- und Einkaufs-Tracking im Home-Lab-Betrieb.

Das Projekt wurde technisch aus einem kopierten Naturfreunde-Hub-Grundgerüst entwickelt. Naturfreunde-Funktionen wurden weitgehend entfernt oder ersetzt. Das alte Projekt dient nur noch als historische/technische Vorlage, nicht als fachliche Grundlage.

Wichtig: In deutscher UI und Dokumentation immer echte Umlaute verwenden, also ä, ö, ü, ß statt ae, oe, ue, ss.

Arbeitsverzeichnis

Aktueller Projektpfad:

c:\EurOwiG\Entwicklung\forgejo\hellth-hub

Das Monorepo liegt direkt im Repo-Root (apps/, packages/, docker/ …). Der frühere nf-hub/-Unterordner wurde am 2026-05-27 entfernt und sein Inhalt nach oben gezogen.

Tech Stack

• Monorepo mit pnpm
• Frontend/Admin: Next.js 16, React 19, Tailwind
• API: Hono, tRPC, Better Auth
• DB: PostgreSQL, Drizzle ORM
• Docker: Postgres und pgAdmin, plus vorhandener App-Container
• Auth: Better Auth mit Login, 2FA, Passkeys

Wichtige Ports

• Admin-App lokal: http://localhost:3001
• API lokal: http://localhost:3002
• API Healthcheck: http://localhost:3002/api/health
• Docker-App: http://localhost:3000
• Postgres: localhost:5432
• pgAdmin: http://localhost:5050

Hinweis: http://localhost:3002 direkt kann 404 liefern. Das ist normal, weil die API unter /api/... hängt.

Lokaler Start

Docker/Postgres muss laufen:

docker ps

Migrationen anwenden:

pnpm --filter @hellth/db db:migrate

API starten:

pnpm --filter @hellth/api dev

Admin starten:

pnpm --filter admin dev

Seeds:

pnpm --filter @hellth/api seed:health
pnpm --filter @hellth/api seed:demo-recipes

Der Demo-Recipe-Seed erzeugt 50 öffentliche Testrezepte mit IDs demo-recipe-01 bis demo-recipe-50.

Relevante Dateien und Bereiche

Frontend

• apps/admin/app/(authed)/page.tsx
  Tagesansicht/Dashboard.

• apps/admin/app/(authed)/lebensmittel/page.tsx
  Lebensmittelkatalog, Suche, OCR/Barcode/Open Food Facts, Food-Votes.

• apps/admin/app/(authed)/rezepte/page.tsx
  Rezepte, private Rezepte, Rezeptvorschläge, Nährwert-Liveberechnung, persönliche Vorschläge.

• apps/admin/app/(authed)/rezepte/pruefung/page.tsx
  Admin-Prüfung von Rezeptvorschlägen.

• apps/admin/app/(authed)/planung/page.tsx
  Essensplanung.

• apps/admin/app/(authed)/einkaufsliste/page.tsx
  Einkaufslisten.

• apps/admin/app/(authed)/maerkte/page.tsx
  Märkte, Standort-Pins, Zonen/Laufwege, Änderungsanträge.

• apps/admin/app/(authed)/aktivitaetsfeed/page.tsx
  Admin Activity Feed für Rezeptvorschläge und Marktänderungen.

• apps/admin/app/(authed)/hellfireclub/page.tsx
  Community-/Aktivitätsbereich mit Punkten und gemeinsamer Aktivitätsplanung.

• apps/admin/app/(authed)/statistiken/page.tsx
  Statistiken, motivierende Auswertungen und Prognosen.

• apps/admin/app/(authed)/gewicht/page.tsx
  Gewichtshistorie.

• apps/admin/app/(authed)/wearables/page.tsx
  Wearables/Fitbit/Health-Connect-Vorbereitung.

• apps/admin/app/(authed)/einstellungen/page.tsx
  User-Profil, Sicherheit, 2FA, Passkeys, Rezept-/Ernährungspräferenzen.

• apps/admin/app/(authed)/einstellungen/punkte/page.tsx
  Globale Admin-Einstellung für Hellfireclub-/Aktivitätspunkte.

• apps/admin/app/_components/form-field.tsx
  Globales Formularfeld-Pattern für sichtbare Labels und konsistente Inputs. Neue Formulare sollen möglichst diese Komponente nutzen.

• apps/admin/lib/hellth-data.ts
  Frontend-nahe Health-Hilfslogik: Nährwertberechnung, Rezeptklassifizierung, Wochenbudget, Einkaufslisten, Statistiken.

API

• packages/api/src/trpc/routers/health.ts
  Zentrale Health API. Enthält Foods, Recipes, Recipe Submissions, Stores, Store Change Requests, Activity Feed, Planning, Shopping, Weight, Stats, Hellfireclub, Points.

• packages/api/src/trpc/routers/users.ts
  Benutzerverwaltung und Profil.

• packages/api/src/trpc/routers/security.ts
  2FA/Passkey/Sicherheitsstatus.

• packages/api/src/lib/auth.ts
  Better Auth Setup.

• packages/api/src/lib/health-coach.ts
  Regelbasierter Ernährungs-/Health-Coach.

• packages/api/src/scripts/seed-health.ts
  Basisdaten für Lebensmittel, Märkte, Aktivitäten, Coach-Prinzipien.

• packages/api/src/scripts/seed-demo-recipes.ts
  50 Demo-Rezepte zum manuellen Testen.

DB

• packages/db/src/schema/health.ts
  Zentrales Health-Schema.

• packages/db/src/schema/auth.ts
  Better-Auth-Tabellen.

• packages/db/drizzle/*.sql
  Migrationen.

Aktuell relevante neuere Migrationen:

• 0015_recipe_submissions.sql
• 0016_recipe_preferences.sql
• 0017_store_change_requests.sql

Aktuelle Kernfunktionen

Dashboard / Daily View

• Tagesansicht für Mahlzeiten, Getränke, Gewicht und Tagesziele.
• Zurückliegende Tage können ergänzt werden.
• Zukunftstage sind für Essenplanung relevant.

Lebensmittel

• Eigener Lebensmittelkatalog.
• Nährwerte pro 100 g.
• Portionsgrößen und Alltagseinheiten.
• Open Food Facts Import.
• Barcode-/Label-OCR-Vorbereitung.
• Food-Votes:
  • Mag ich
  • Nicht meins
• Food-Votes fließen in Rezeptvorschläge ein.

Rezepte

• Private Rezepte möglich.
• Rezeptvorschläge können zur Community/Admin-Prüfung eingereicht werden.
• Akzeptierte Vorschläge werden öffentliche Rezepte.
• Rezeptvorschläge bringen Hellfireclub-Punkte.
• Live-Berechnung von kcal, Kohlenhydraten, Fett, Eiweiß.
• Makroverteilung wird angezeigt.
• Autokategorisierung:
  • kein Fleisch/Fisch → vegetarisch
  • keine tierischen Produkte → vegan
  • weitere Tags wie proteinreich, kalorienbewusst usw.

Rezeptvorschläge

Vorschläge berücksichtigen vorrangig User-Profil:

• vegan/vegetarisch/Fleisch/Fisch Mehrfachauswahl
• Mealprep 2 oder 3 Tage
• 1x oder 2x kochen pro Tag
• Fleisch/Fisch nie, maximal 1x am Tag oder flexibel
• Food-Likes und Food-Dislikes
• Kalorien, Protein und weitere Nährwerte

Märkte und Einkauf

• User können Lebensmittelläden speichern.
• Adresse, Koordinaten und Google-Maps-Suche/Pin-Link.
• User kann Zonen/Abteilungen selbst sortieren.
• Eigene Märkte zählen zunächst als User-Daten.
• User kann Änderungen einreichen.
• Admin kann Änderungen übernehmen; dadurch werden sie globale Vorlage.
• Einkaufslisten nutzen Märkte und Abteilungen für bessere Laufweg-Sortierung.

Admin Activity Feed

Pfad:

/aktivitaetsfeed

Zeigt aktuell:

• Rezeptvorschläge
• Marktänderungsanträge

Marktänderungen können direkt übernommen oder abgelehnt werden.

Hellfireclub

• Aktivitätspunkte.
• Gemeinsame, getrennte Aktivitäten.
• Standort-/Bundesland-basierte Sichtbarkeit.
• Highscore.

Wochenbudget

• Tägliches Kalorienziel.
• Wochenbudget.
• Sportbonus.
• flexible Planung, nicht strafend.

Wearables

• Fitbit/Google Fit/Health Connect sind vorbereitet.
• Fitbit-Aktivitätskatalog ist vorhanden.
• Manuelle Aktivitäten sind möglich.

Auth/Admin

Admin-User:

admin@onl1.eu

Passwort steht nicht hier dokumentieren. Falls nötig über vorhandene Admin-/Seed-Skripte neu setzen.

Admin erzwingt 2FA. Es gibt zusätzliche Logs/Sicherheitsmechanik, falls 2FA-Status verloren geht.

Tests und Checks

Admin-Tests:

pnpm --filter admin test

API-Tests:

pnpm --filter @hellth/api test

API-Typecheck:

pnpm exec tsc --noEmit --project packages/api/tsconfig.json

Admin-Build:

$env:NEXT_PUBLIC_API_URL='http://localhost:3002'; pnpm --filter admin build

Zuletzt erfolgreich:

• API-Tests: 28/28
• Admin-Tests: 10/10
• API-Typecheck: grün
• Admin-Build: grün

Lokale Dev-Logs

Wenn die Prozesse im Hintergrund gestartet wurden, liegen Logs hier:

.logs/api-dev.out.log
.logs/api-dev.err.log
.logs/admin-dev.out.log
.logs/admin-dev.err.log

Wichtige Arbeitsregeln

• Bestehende User-Änderungen nicht zurücksetzen.
• Keine destruktiven Git-Befehle ohne ausdrückliche Anweisung.
• Für manuelle Code-Edits bevorzugt apply_patch verwenden.
• Bei Suche rg bevorzugen.
• UI mobile-first denken.
• Keine Naturfreunde-Fachlogik wieder einführen.
• Neue Formulare nach Möglichkeit mit FormField und inputClassName aus apps/admin/app/_components/form-field.tsx bauen.
• Bei neuen DB-Funktionen Schema, Migration, API und UI zusammen denken.
• Bei deutscher UI immer Umlaute korrekt schreiben.

Aktuelle bekannte Besonderheiten

• localhost:3002 direkt liefert 404; /api/health ist der richtige API-Test.
• Docker stellt primär DB/pgAdmin bereit; lokale Entwicklung läuft über pnpm --filter @hellth/api dev und pnpm --filter admin dev.
• Die Docker-App läuft zusätzlich auf localhost:3000, ist aber nicht der primäre lokale Dev-Workflow.

Wichtige Orientierung für Claude: Repo-Konsistenz

Das Hellth-Hub-Monorepo liegt direkt im Repo-Root. Aktuell relevant sind:

• apps/admin
• packages/api
• packages/db
• docker/docker-compose.yml
• Health-spezifische Dateien unter packages/api/src/trpc/routers/health.ts
• Health-Schema unter packages/db/src/schema/health.ts
• Health-UI unter apps/admin/app/(authed)/...
• UI-Referenzscreenshots unter docs/inspiration/bitepal/ (kein Projektname, nur Inspiration)

Bekannte Altlasten

Aufräum-Historie 2026-05-27:

• Phase-1/2-Demo im Root entfernt
• Nested nf-hub/-Ordner + separater Git-Verlauf (Remote github.com/b4tzd/nf-hub) entfernt
• Screenshots Bitepal/ → docs/inspiration/bitepal/ verschoben
• .claude/rules.md komplett neu geschrieben (vorher Naturfreunde-Portal-Regeln)
• .claude/settings.json Paketname @naturfreunde/db → @hellth/db
• turbo.json Tenant-/Member-Card-/Google-Wallet-Env-Vars entfernt
• .gitignore aufgeräumt, Live-Logs gelöscht
• scripts/export-alte-website.py gelöscht

Diese Altlast ist noch da und sollte nicht angepackt werden, weil sie die DB-State-Konsistenz brechen würde:

• packages/db/drizzle/*.sql und meta/*.json (Migrationen 0000-0008) enthalten noch Naturfreunde-Tabellen-DDL aus der Schema-Historie. Drizzle tracked sie per Datei + Hash - Umbenennen oder Löschen würde die DB inkonsistent machen. Wenn das stört, ist ein dedizierter "Schema-Reset" notwendig (alle Migrationen löschen, neue 0000_init.sql aus aktuellem Schema generieren, DB neu aufbauen).

Arbeitsregel für neue Aufgaben

Pfade in Antworten immer ohne nf-hub/-Präfix - das Monorepo liegt im Repo-Root:

apps/admin
packages/api
packages/db

Keine Naturfreunde-Funktionalität wiederbeleben. Wenn eine Altlast aus der obigen Liste auftaucht: höchstens kurz erwähnen, dann im aktuellen Hellth-Hub-Code weiterarbeiten. Cleanup nur nach ausdrücklicher Benutzerfreigabe.