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)

# 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