hellth-hub/docs/projektreferenz.md

Hellth Hub - Projektreferenz

Ausführliches Nachschlagewerk. Die immer geltenden Regeln und der Schnellstart stehen in CLAUDE.md im Repo-Root.

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.

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

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. Aufgeteilt in Tabs (_components/settings-tabs.tsx, section-card.tsx, status-banner.tsx), Tab-Auswahl über ?tab=-Query.

• 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 und 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.

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 (Stand 2026-05-29):

• API-Tests: 38/38
• Admin-Tests: 10/10
• Typecheck: grün (alle Pakete)
• Lint: 0 Errors (react-hooks-Warnings = bestehendes Muster)

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

Repo-Konsistenz und Altlasten

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

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