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:

```text
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:

```powershell
docker ps
```

Migrationen anwenden:

```powershell
pnpm --filter @hellth/db db:migrate
```

API starten:

```powershell
pnpm --filter @hellth/api dev
```

Admin starten:

```powershell
pnpm --filter admin dev
```

Seeds:

```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`  
  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:

```text
/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:

```text
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:

```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
```

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:

```text
.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:

```text
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.