mitai-jinkendo/CLAUDE.md

# Mitai Jinkendo – Entwickler-Kontext für Claude Code

## Projekt-Übersicht
**Mitai Jinkendo** ist eine selbst-gehostete PWA für Körper-Tracking (Gewicht, Körperfett, Umfänge, Ernährung, Aktivität) mit KI-Auswertung. Teil der **Jinkendo**-App-Familie (人拳道 – Der menschliche Weg der Kampfkunst).

**Produktfamilie:** body · fight · guard · train · mind (alle unter jinkendo.de)

## Tech-Stack
| Komponente | Technologie | Version |
|-----------|-------------|---------|
| Frontend  | React 18 + Vite + PWA | Node 20 |
| Backend   | FastAPI (Python) | Python 3.12 |
| Datenbank | PostgreSQL | 16 (Ziel: v9) / SQLite (aktuell: v8) |
| Container | Docker + Docker Compose | - |
| Webserver | nginx (Reverse Proxy + HTTPS) | Alpine |
| Auth      | Token-basiert (eigene Impl.) | - |
| KI        | OpenRouter API (claude-sonnet-4) | - |

## Ports
| Service | Intern | Extern (Dev) |
|---------|--------|-------------|
| Frontend | 80 (nginx) | 3002 |
| Backend  | 8000 (uvicorn) | 8002 |
| PostgreSQL | 5432 | nicht exponiert |

## Verzeichnisstruktur
```
mitai-jinkendo/
├── backend/
│   ├── main.py          # FastAPI App, alle Endpoints
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── App.jsx      # Root, Auth-Gates, Navigation
│   │   ├── app.css      # Globale Styles, CSS-Variablen
│   │   ├── context/
│   │   │   ├── AuthContext.jsx    # Session, Login, Logout
│   │   │   └── ProfileContext.jsx # Aktives Profil
│   │   ├── pages/       # Alle Screens
│   │   ├── utils/
│   │   │   ├── api.js   # Alle API-Calls (injiziert Token + ProfileId)
│   │   │   ├── calc.js  # Körperfett-Formeln
│   │   │   ├── interpret.js # Regelbasierte Auswertung
│   │   │   ├── Markdown.jsx # Eigener MD-Renderer
│   │   │   └── guideData.js # Messanleitungen
│   │   └── main.jsx
│   ├── public/          # Icons (Jinkendo Ensō-Logo)
│   ├── index.html
│   ├── vite.config.js
│   └── Dockerfile
├── nginx/
│   └── nginx.conf
├── docker-compose.yml        # Produktion
├── docker-compose.dev.yml    # Entwicklung (Hot-Reload)
├── .env.example
└── CLAUDE.md                 # Diese Datei
```

## Aktuelle Version: v8
### Was implementiert ist:
- ✅ Multi-User mit PIN/Passwort-Auth + Token-Sessions
- ✅ Admin/User Rollen, KI-Limits, Export-Berechtigungen
- ✅ Gewicht, Umfänge, Caliper (4 Formeln), Ernährung, Aktivität
- ✅ FDDB CSV-Import (Ernährung), Apple Health CSV-Import (Aktivität)
- ✅ KI-Analyse: 6 Einzel-Prompts + 3-stufige Pipeline (parallel)
- ✅ Konfigurierbare Prompts mit Template-Variablen
- ✅ Verlauf mit 5 Tabs + Zeitraumfilter + KI pro Sektion
- ✅ Dashboard mit Kennzahlen, Zielfortschritt, Combo-Chart
- ✅ Assistent-Modus (Schritt-für-Schritt Messung)
- ✅ PWA (iPhone Home Screen), Jinkendo-Icon
- ✅ E-Mail (SMTP) für Password-Recovery
- ✅ Admin-Panel: User verwalten, KI-Limits, E-Mail-Test

### Was in v9 kommt:
- 🔲 PostgreSQL Migration (aktuell: SQLite)
- 🔲 Auth-Middleware auf ALLE Endpoints
- 🔲 bcrypt statt SHA256
- 🔲 Rate Limiting
- 🔲 CORS auf Domain beschränken
- 🔲 Selbst-Registrierung mit E-Mail-Bestätigung
- 🔲 Freemium Tier-System (free/basic/premium/selfhosted)
- 🔲 Login via E-Mail statt Profil-Liste
- 🔲 nginx + Let's Encrypt

## Datenbank-Schema (SQLite, v8)
### Wichtige Tabellen:
- `profiles` – Nutzer mit Auth (role, pin_hash, auth_type, ai_enabled, export_enabled)
- `sessions` – Auth-Tokens mit Ablaufdatum
- `weight_log` – Gewichtseinträge (profile_id, date, weight)
- `circumference_log` – 8 Umfangspunkte
- `caliper_log` – Hautfaltenmessung, 4 Methoden
- `nutrition_log` – Kalorien + Makros (aus FDDB-CSV)
- `activity_log` – Training (aus Apple Health oder manuell)
- `ai_insights` – KI-Auswertungen (scope = prompt-slug)
- `ai_prompts` – Konfigurierbare Prompts mit Templates
- `ai_usage` – KI-Calls pro Tag pro Profil

## Auth-Flow (aktuell v8)
```
Login-Screen → Profil-Liste → PIN/Passwort → Token im localStorage
Token → X-Auth-Token Header → Backend require_auth()
Profile-Id → aus Session (nicht aus Header!)
```

## API-Konventionen
- Alle Endpoints: `/api/...`
- Auth-Header: `X-Auth-Token: <token>`
- Profile-Header: `X-Profile-Id: <uuid>` (nur wo noch nicht migriert)
- Responses: immer JSON
- Fehler: `{"detail": "Fehlermeldung"}`

## Umgebungsvariablen (.env)
```
OPENROUTER_API_KEY=   # KI-Calls
OPENROUTER_MODEL=anthropic/claude-sonnet-4
ANTHROPIC_API_KEY=    # Alternative zu OpenRouter
SMTP_HOST=            # E-Mail
SMTP_PORT=587
SMTP_USER=
SMTP_PASS=
SMTP_FROM=
APP_URL=              # Für Links in E-Mails
DATA_DIR=/app/data    # SQLite-Pfad (v8)
PHOTOS_DIR=/app/photos
# v9 (PostgreSQL):
DATABASE_URL=postgresql://jinkendo:password@db/jinkendo
DB_PASSWORD=
```

## Deployment (aktuell)
```bash
# Heimserver (Raspberry Pi 5, lars@raspberrypi5)
cd /home/lars/docker/bodytrack
docker compose build --no-cache [frontend|backend]
docker compose up -d
docker logs mitai-api --tail 30
```

## Wichtige Hinweise für Claude Code
1. **Ports immer 3002/8002** – nie ändern
2. **npm install** (nicht npm ci) – kein package-lock.json vorhanden
3. **SQLite safe_alters** – neue Spalten immer via _safe_alters() hinzufügen
4. **Pipeline-Prompts** haben slug-Prefix `pipeline_` – nie als Einzelanalyse zeigen
5. **dayjs.week()** braucht Plugin – stattdessen native JS Wochenberechnung
6. **useNavigate()** nur in React-Komponenten (Großbuchstabe), nicht in Helper-Functions
7. **Bar fill=function** in Recharts nicht unterstützt – nur statische Farben

## Code-Style
- React: Functional Components, Hooks
- CSS: Inline-Styles + globale CSS-Variablen (var(--accent), var(--text1), etc.)
- API-Calls: immer über `api.js` (injiziert Token automatisch)
- Kein TypeScript (bewusst, für Einfachheit)
- Python: keine Type-Hints Pflicht, aber bei neuen Funktionen erwünscht