# Mitai Jinkendo – Entwickler-Kontext für Claude Code ## Projekt-Übersicht **Mitai Jinkendo** (身体 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:** mitai · miken · ikigai · shinkan · kenkou (alle unter jinkendo.de) ## Tech-Stack | Komponente | Technologie | Version | |-----------|-------------|---------| | Frontend | React 18 + Vite + PWA | Node 20 | | Backend | FastAPI (Python) | Python 3.12 | | Datenbank | SQLite (v9a) → PostgreSQL (v9b geplant) | - | | Container | Docker + Docker Compose | - | | Webserver | nginx (Reverse Proxy) | Alpine | | Auth | Token-basiert + bcrypt | - | | KI | OpenRouter API (claude-sonnet-4) | - | ## Ports | Service | Prod | Dev | |---------|------|-----| | Frontend | 3002 | 3099 | | Backend | 8002 | 8099 | ## Verzeichnisstruktur ``` mitai-jinkendo/ ├── backend/ │ ├── main.py # FastAPI App, alle Endpoints (~2000 Zeilen) │ ├── 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 automatisch) │ │ ├── calc.js # Körperfett-Formeln │ │ ├── interpret.js # Regelbasierte Auswertung │ │ ├── Markdown.jsx # Eigener MD-Renderer │ │ └── guideData.js # Messanleitungen │ └── public/ # Icons (Jinkendo Ensō-Logo) ├── .gitea/workflows/ │ ├── deploy-prod.yml # Auto-Deploy bei Push auf main │ ├── deploy-dev.yml # Auto-Deploy bei Push auf develop │ └── test.yml # Build-Test bei jedem Push ├── docker-compose.yml # Produktion (Ports 3002/8002) ├── docker-compose.dev-env.yml # Development (Ports 3099/8099) └── CLAUDE.md # Diese Datei ``` ## Aktuelle Version: v9a ### Was implementiert ist: - ✅ Multi-User mit E-Mail + Passwort Login (bcrypt) - ✅ Auth-Middleware auf ALLE Endpoints (44 Endpoints geschützt) - ✅ Rate Limiting (Login: 5/min, Reset: 3/min) - ✅ CORS konfigurierbar via ALLOWED_ORIGINS in .env - ✅ 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 Ensō-Logo - ✅ E-Mail (SMTP) für Password-Recovery - ✅ Admin-Panel: User verwalten, KI-Limits, E-Mail-Test - ✅ Multi-Environment: Prod (mitai.jinkendo.de) + Dev (dev.mitai.jinkendo.de) - ✅ Gitea CI/CD mit Auto-Deploy auf Raspberry Pi 5 ### Was in v9b kommt: - 🔲 PostgreSQL Migration (aktuell noch SQLite) - 🔲 Selbst-Registrierung mit E-Mail-Bestätigung - 🔲 Freemium Tier-System (free/basic/premium/selfhosted) - 🔲 14-Tage Trial automatisch - 🔲 Einladungslinks für Beta-Nutzer - 🔲 Admin kann Tiers manuell setzen ### Was in v9c kommt: - 🔲 OAuth2-Grundgerüst für Fitness-Connectoren - 🔲 Strava Connector - 🔲 Withings Connector (Waage) - 🔲 Garmin Connector ## Deployment ### Infrastruktur ``` Internet → privat.stommer.com (Fritz!Box DynDNS) → Synology NAS (Reverse Proxy + Let's Encrypt) → Raspberry Pi 5 (192.168.2.49, Docker) ``` ### Git Workflow ``` develop branch → Auto-Deploy → dev.mitai.jinkendo.de (Port 3099/8099) main branch → Auto-Deploy → mitai.jinkendo.de (Port 3002/8002) ``` ### Deployment-Befehle (manuell falls nötig) ```bash # Prod cd /home/lars/docker/bodytrack docker compose -f docker-compose.yml build --no-cache docker compose -f docker-compose.yml up -d # Dev cd /home/lars/docker/bodytrack-dev docker compose -f docker-compose.dev-env.yml build --no-cache docker compose -f docker-compose.dev-env.yml up -d ``` ## Datenbank-Schema (SQLite, v9a) ### Wichtige Tabellen: - `profiles` – Nutzer (role, pin_hash/bcrypt, email, auth_type, ai_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 (11 Prompts) - `ai_usage` – KI-Calls pro Tag pro Profil ## Auth-Flow (v9a) ``` Login-Screen → E-Mail + Passwort → Token im localStorage Token → X-Auth-Token Header → Backend require_auth() Profile-Id → aus Session (nicht aus Header!) SHA256 Passwörter → automatisch zu bcrypt migriert beim Login ``` ## API-Konventionen - Alle Endpoints: `/api/...` - Auth-Header: `X-Auth-Token: ` - Responses: immer JSON - Fehler: `{"detail": "Fehlermeldung"}` - Rate Limit überschritten: HTTP 429 ## Umgebungsvariablen (.env) ``` OPENROUTER_API_KEY= # KI-Calls OPENROUTER_MODEL=anthropic/claude-sonnet-4 SMTP_HOST= # E-Mail SMTP_PORT=587 SMTP_USER= SMTP_PASS= SMTP_FROM= APP_URL=https://mitai.jinkendo.de ALLOWED_ORIGINS=https://mitai.jinkendo.de DATA_DIR=/app/data PHOTOS_DIR=/app/photos ``` ## Wichtige Hinweise für Claude Code 1. **Ports immer 3002/8002 (Prod) oder 3099/8099 (Dev)** – nie ändern 2. **npm install** (nicht npm ci) – kein package-lock.json vorhanden 3. **SQLite safe_alters** – neue Spalten immer via safe_alters Liste 4. **Pipeline-Prompts** haben slug-Prefix `pipeline_` – nie als Einzelanalyse zeigen 5. **dayjs.week()** braucht Plugin – stattdessen native JS ISO-Wochenberechnung 6. **useNavigate()** nur in React-Komponenten, nicht in Helper-Functions 7. **api.js nutzen** für alle API-Calls – injiziert Token automatisch 8. **bcrypt** für alle neuen Passwort-Operationen verwenden 9. **session=Depends(require_auth)** als separater Parameter – nie in Header() einbetten ## 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 ## Design-System ### Farben (CSS-Variablen) ```css --accent: #1D9E75 /* Jinkendo Grün – Buttons, Links, Akzente */ --accent-dark: #085041 /* Dunkelgrün – Icon-Hintergrund, Header */ --accent-light: #E1F5EE /* Hellgrün – Hintergründe, Badges */ --bg: /* Seitenhintergrund (hell/dunkel auto) */ --surface: /* Card-Hintergrund */ --surface2: /* Sekundäre Fläche */ --border: /* Rahmen */ --text1: /* Primärer Text */ --text2: /* Sekundärer Text */ --text3: /* Muted Text, Labels */ --danger: #D85A30 /* Fehler, Warnungen */ ``` ### CSS-Klassen ```css .card /* Weißer Container, border-radius 12px, box-shadow */ .btn /* Basis-Button */ .btn-primary /* Grüner Button (#1D9E75) */ .btn-secondary /* Grauer Button */ .btn-full /* 100% Breite */ .form-input /* Eingabefeld, volle Breite */ .form-label /* Feldbezeichnung, klein, uppercase */ .form-row /* Label + Input + Unit nebeneinander */ .form-unit /* Einheit rechts (kg, cm, etc.) */ .section-gap /* margin-bottom zwischen Sektionen */ .spinner /* Ladekreis, animiert */ ``` ### Abstände & Größen ``` Seiten-Padding: 16px seitlich Card-Padding: 16-20px Border-Radius: 12px (Cards), 8px (Buttons/Inputs), 50% (Avatare) Icon-Größe: 16-20px inline, 24px standalone Font-Größe: 12px (Labels), 14px (Body), 16-18px (Subtitel), 20-24px (Titel) Font-Weight: 400 (normal), 600 (semi-bold), 700 (bold) Bottom-Padding: 80px (für Mobile-Navigation) ``` ### Komponenten-Muster **Titelzeile einer Seite:** ```jsx
Seitentitel
``` **Ladezustand:** ```jsx if (loading) return (
) ``` **Fehlerzustand:** ```jsx if (error) return (
{error}
) ``` **Leerer Zustand:** ```jsx {items.length === 0 && (
📭
Noch keine Einträge
)} ``` **Metric Card:** ```jsx
LABEL
{value}
Einheit
``` ### Jinkendo Logo-System ``` Grundelement: Ensō-Kreis (offen, Lücke 4-5 Uhr) Farbe Ensō: #1D9E75 Hintergrund: #085041 (dunkelgrün) Kern-Symbol: #5DCAA5 (mintgrün) Wortmarke: Jin(light) + ken(bold #1D9E75) + do(light) ``` ### Verfügbare Custom Commands ``` /deploy → Commit + Push vorbereiten /merge-to-prod → develop → main mergen /test → Manuelle Tests durchführen /new-feature → Neues Feature-Template /ui-component → Neue Komponente erstellen /ui-page → Neue Seite erstellen /fix-bug → Bug analysieren und beheben /add-endpoint → Neuen API-Endpoint hinzufügen /db-add-column → Neue DB-Spalte hinzufügen ```