2026-05-29 10:20:03 +02:00
# Hellth Hub - Projektreferenz
Ausführliches Nachschlagewerk. Die immer geltenden Regeln und der Schnellstart stehen in [`CLAUDE.md` ](../CLAUDE.md ) im Repo-Root.
2026-05-27 22:15:16 +02:00
## 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
2026-05-29 10:20:03 +02:00
## Seeds
2026-05-27 22:15:16 +02:00
```powershell
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`
2026-05-29 10:20:03 +02:00
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.
2026-05-27 22:15:16 +02:00
- `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
2026-05-29 10:20:03 +02:00
Pfad: `/aktivitaetsfeed`
2026-05-27 22:15:16 +02:00
2026-05-29 10:20:03 +02:00
Zeigt aktuell Rezeptvorschläge und Marktänderungsanträge. Marktänderungen können direkt übernommen oder abgelehnt werden.
2026-05-27 22:15:16 +02:00
### 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:
```powershell
pnpm --filter admin test
```
API-Tests:
```powershell
pnpm --filter @hellth/api test
```
API-Typecheck:
```powershell
pnpm exec tsc --noEmit --project packages/api/tsconfig.json
```
Admin-Build:
```powershell
$env:NEXT_PUBLIC_API_URL='http://localhost:3002'; pnpm --filter admin build
```
2026-05-29 10:20:03 +02:00
Zuletzt erfolgreich (Stand 2026-05-29):
2026-05-27 22:15:16 +02:00
2026-05-29 10:20:03 +02:00
- API-Tests: 38/38
2026-05-27 22:15:16 +02:00
- Admin-Tests: 10/10
2026-05-29 10:20:03 +02:00
- Typecheck: grün (alle Pakete)
- Lint: 0 Errors (react-hooks-Warnings = bestehendes Muster)
2026-05-27 22:15:16 +02:00
## Lokale Dev-Logs
Wenn die Prozesse im Hintergrund gestartet wurden, liegen Logs hier:
```text
.logs/api-dev.out.log
.logs/api-dev.err.log
.logs/admin-dev.out.log
.logs/admin-dev.err.log
```
2026-05-29 10:20:03 +02:00
## Repo-Konsistenz und Altlasten
2026-05-27 22:15:16 +02:00
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).
2026-05-29 10:20:03 +02:00
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.
