shinkan-jinkendo/CLAUDE.md

Shinkan Jinkendo – Entwickler-Kontext für Claude Code

Pflicht-Lektüre für Claude Code

VOR jeder Implementierung lesen: | Architektur-Regeln | .claude/rules/ARCHITECTURE.md | | Coding-Regeln | .claude/rules/CODING_RULES.md | | Zugriffsschicht (Multi-Tenancy, Governance) | .claude/docs/technical/ACCESS_LAYER_AND_GOVERNANCE_PLAN.md | | Endpoint-Audit (Tenant/Governance) | .claude/docs/working/ACCESS_LAYER_ENDPOINT_AUDIT.md | | Cursor-Regel Zugriffsschicht | .cursor/rules/access-layer.mdc | | Lessons Learned | .claude/rules/LESSONS_LEARNED.md | | Setup-Dokument | .claude/docs/working/SHINKAN_PROJECT_SETUP.md | | Anforderungen | .claude/docs/functional/SHINKAN_REQUIREMENTS.md | | Medien-Archiv, Lifecycle, Inline (Plan §11) | .claude/docs/technical/MEDIA_ASSETS_AND_ARCHIVE_SPEC.md | | Handover / nächste Session | docs/HANDOVER.md | | Fachlicher Nutzerüberblick (Design/Product) | docs/FACHLICHE_NUTZERFUNKTIONEN.md | | Architektur-Zielbild, Refaktor-Roadmap, verbindliche Shinkan-Regeln | docs/architecture/README.md | | Performance-Baseline (Phase 0) | docs/architecture/BASELINE_SNAPSHOT.md |

Projekt-Übersicht

Shinkan Jinkendo (真観 Jinkendo) – Trainer- und Vereinsplattform für Kampfsport-Trainingsplanung. Teil der Jinkendo-App-Familie (人拳道). Domains: shinkan.jinkendo.de

WICHTIG: Shinkan ist KEINE persönliche Tracking-App!

Fachlicher Fokus:

• Übungsverwaltung und -suche
• Trainingsplanung für Gruppen
• Fähigkeiten- und Methodenkataloge
• Standardisierung und Wiederverwendung
• Freigabe und Governance von Inhalten

Primäre Nutzer: Trainer, Vereinsadmins, Redakteure
Nicht in MVP: Individuelle Sportler, persönliches Tracking

Tech-Stack

Komponente	Technologie
Frontend	React 18 + Vite + PWA (Node 20)
Backend	FastAPI Python 3.12
Datenbank	PostgreSQL 16 Alpine
Container	Docker + Docker Compose
Auth	Token-basiert + bcrypt
KI	OpenRouter API (optional, nicht MVP-kritisch)

Ports: Prod 3003/8003 · Dev 3098/8098 – nie ändern!

Verzeichnisstruktur

backend/
├── main.py          # App-Setup + Router-Registration
├── db.py            # PostgreSQL Connection Pool (von Mitai)
├── db_init.py       # DB-Init + Migrations-System (von Mitai)
├── auth.py          # Hash, Verify, Sessions (von Mitai)
├── models.py        # Pydantic Models
├── version.py       # Versionskontrolle
├── migrations/      # SQL-Migrationen (XXX_*.sql Pattern)
└── routers/         # Router-Module
    auth · profiles · clubs · groups · skills · methods
    exercises · exercise_progression_graphs · training_units · training_programs
    planning · import_wiki · admin · membership · media_assets

frontend/src/
├── App.jsx          # Root, Auth-Gates, Navigation
├── app.css          # CSS-Variablen + globale Styles
├── config/          # appNav.js · adminNav.js
├── layouts/         # AdminShell · RequireAdmin
├── context/         # AuthContext · ProfileContext
├── pages/           # Alle Screens
└── utils/
    api.js           # ALLE API-Calls

.claude/
├── commands/        # Slash-Commands
├── docs/
│   ├── functional/  # Fachliche Specs
│   ├── technical/   # Technische Specs
│   └── rules/       # Verbindliche Regeln
└── library/         # Auto-generierte Docs

Aktuelle Version

Siehe: backend/version.py (APP_VERSION, DB_SCHEMA_VERSION, MODULE_VERSIONS) und .claude/docs/PROJECT_STATUS.md.

Kurz (Stand 2026-05-12): App 0.8.96, DB‑Schema‑Version siehe backend/version.py; Kern: Übungen, Varianten, Medien-Archiv & Bibliothek (/media), Inline-Medien im Rich-Text, Inhaltsmeldungen (P-13) im Posteingang, Mandanten-Sync aktiver Verein, Planung mit Sektionen, Trainingsrahmen Bibliothek + Slot‑Blueprint (036–037), Progressionsgraph, Reifegrad/Matrix‑Stack — Details PROJECT_STATUS.md, docs/HANDOVER.md, Nutzerüberblick docs/FACHLICHE_NUTZERFUNKTIONEN.md, MEDIA_ASSETS_AND_ARCHIVE_SPEC.md (Abschnitt 11 umgesetzt).

Log (Auszug)

• 2026-05-07: Medien — zentrales Archiv (media_assets), Bibliothek-UI, Lifecycle/Papierkorb, from-asset, Speicherpfade library/…, Governance official/Copyright; 0.8.59 aktiver Verein UI/API-Sync — siehe .claude/docs/library/FEATURES_DELIVERED_2026-Q2.md §12, docs/HANDOVER.md.
• 2026-05-05: Rahmen nur Bibliothek (036), Slot‑Ablauf = training_units + Sektionen (037), POST /api/training-units/from-framework-slot, keine training_framework_slot_exercises mehr — siehe DATABASE_SCHEMA.md / FEATURES_DELIVERED_2026-Q2.md.
• 2026-04-27: Übungsvarianten API/UI, Migration 030, Listen-UX-Suche, Admin-Upload-Limits — siehe PROJECT_STATUS.md und docs/library/FEATURES_DELIVERED_2026-Q2.md.

Domänenmodell (MVP Core)

Kern-Objekte

Organisation:

• clubs - Vereine
• divisions - Sparten (optional)
• training_groups - Trainingsgruppen

Kataloge:

• skills - Fähigkeiten (global)
• training_methods - Trainingsmethoden (global)

Übungen:

• exercises - Übungen (Kernobjekt)
• exercise_variants - Übungsvarianten
• exercise_skills - M:N Übung ↔ Fähigkeit
• exercise_media - Medien (Bilder, Videos); Zielbild Archiv & Lifecycle: MEDIA_ASSETS_AND_ARCHIVE_SPEC.md. Inline im Fließtext (Übungstexte) ist implementiert (Spec §11): Anker exercise_media.id, einheitlicher Render-Pfad.

Trainingsplanung / Rahmen:

• training_plan_templates + Sektionsvorlagen — Mikrovorlage pro Einheit (Migration 031)
• training_units — Kalender‑Instanzen und Rahmen‑Slot‑Blueprints (framework_slot_id ab 037)
• training_framework_programs + Ziele + Slots (Migration 035–036) — Bibliotheks‑Rahmen
• Legacy: training_templates / section_exercises o. ä. — in älteren Skizzen; produktiver Pfad siehe Migrationen 006/031

Governance:

• content_change_requests - Änderungsanfragen

Import:

• wiki_import_log - Import-Tracking
• wiki_import_references - Duplikat-Erkennung

Deployment

Internet → Fritz!Box (privat.stommer.com) → Synology NAS → Raspberry Pi 5 (192.168.2.49)

Git Workflow:
  develop → Auto-Deploy → dev.shinkan.jinkendo.de  (shinkan-dev/, Port 3098/8098)
  main    → Auto-Deploy → shinkan.jinkendo.de       (shinkan/, Port 3003/8003)

Gitea: http://192.168.2.144:3000/Lars/shinkan-jinkendo
Runner: Raspberry Pi (/home/lars/gitea-runner/)

Manuell:
  cd /home/lars/docker/shinkan[-dev]
  docker compose -f docker-compose[.dev-env].yml build --no-cache && up -d

Migrations:
  Werden automatisch beim Container-Start ausgeführt (db_init.py)
  Nur nummerierte Dateien: backend/migrations/XXX_*.sql

Datenbank-Schema (PostgreSQL 16)

-- Von Mitai übernommen
profiles          – Nutzer (role, pin_hash/bcrypt, email, tier)
sessions          – Auth-Tokens
features          – Feature-Definitionen
tier_limits       – Limits pro Tier
subscriptions     – Nutzer-Subscriptions

-- Shinkan-spezifisch
clubs                    – Vereine
divisions                – Sparten
training_groups          – Trainingsgruppen
skills                   – Fähigkeiten-Katalog
training_methods         – Methoden-Katalog
exercises                – Übungen (Kernobjekt)
exercise_variants        – Übungsvarianten
exercise_skills          – M:N Übung ↔ Fähigkeit
exercise_media           – Medien
training_templates       – Vorlagen / Standards
training_sections        – Trainingsabschnitte
section_exercises        – Übungen in Abschnitten
training_units           – Trainingseinheiten
training_programs        – Trainingsprogramme
program_units            – Programm-Einheiten
content_change_requests  – Änderungsanfragen
wiki_import_log          – Import-Tracking
wiki_import_references   – Duplikat-Erkennung

Schema-Datei: backend/schema.sql (später)
Migrationen: backend/migrations/*.sql (automatisch beim Start)

API & Auth

Alle Endpoints:     /api/...
Auth-Header:        X-Auth-Token: <token>
Fehler:             {"detail": "Fehlermeldung"}

Auth-Flow:
  Login → E-Mail + Passwort → Token in localStorage
  Token → X-Auth-Token Header → require_auth()
  Profile-Id → immer aus Session, nie aus Header!

Umgebungsvariablen (.env)

DB_HOST/PORT/NAME/USER/PASSWORD  # PostgreSQL
OPENROUTER_API_KEY               # KI (optional)
OPENROUTER_MODEL=anthropic/claude-sonnet-4
SMTP_HOST/PORT/USER/PASS/FROM    # E-Mail
APP_URL=https://shinkan.jinkendo.de
ALLOWED_ORIGINS=https://shinkan.jinkendo.de
MEDIA_DIR=/app/media

Produktions-/Sicherheitsaudit (Drift vermeiden)

Aktuelle Befunde und Umsetzungsstände: .claude/docs/working/PRODUCTION_READINESS_AUDIT_2026-05.md (Fortlaufend pflegen.)

Kritische Regeln für Claude Code

Must-Do:

1. api.js für ALLE API-Calls nutzen – nie direktes fetch() ohne Token
2. session: dict = Depends(require_auth) als separater Parameter
3. bcrypt für alle Passwort-Operationen
4. Neue DB-Spalten nur via Schema-Migration
5. npm install (nicht npm ci) – kein package-lock.json

Bekannte Fallstricke:

# ❌ FALSCH – führt zu ungeschütztem Endpoint:
def endpoint(x: str = Header(default=None, session=Depends(require_auth))):

# ✅ RICHTIG:
def endpoint(x: str = Header(default=None), session: dict = Depends(require_auth)):

# PostgreSQL Boolean (nicht SQLite 0/1):
WHERE active = true   # ✅
WHERE active = 1      # ❌

Design-System (Kurzreferenz)

/* Farben */
--accent: #1D9E75    --accent-dark: #085041    --danger: #D85A30
--bg · --surface · --surface2 · --border · --text1 · --text2 · --text3

/* Klassen */
.card · .btn · .btn-primary · .btn-secondary · .btn-full
.form-input · .form-label · .form-row · .spinner

/* Abstände */
Seiten-Padding: 16px · Card-Padding: 16-20px · Border-Radius: 12px/8px
Bottom-Padding Mobile: 80px (Navigation)

Dokumentations-Struktur

.claude/
├── docs/
│   ├── functional/         ← Fachliche Specs (WAS soll gebaut werden)
│   ├── technical/          ← Technische Specs (WIE wird es gebaut)
│   ├── working/            ← Arbeitspapiere / Analysen
│   └── rules/              ← Verbindliche Regeln
└── library/                ← Ergebnis-Dokumentation (WAS wurde gebaut)

Abgrenzung zu Mitai

Mitai (身体):

• Persönliches Körper- und Trainings-Tracking
• Gewicht, Umfänge, Ernährung, Aktivität
• Individuelle Ziele und Fortschritte
• KI-Analysen für persönliche Entwicklung

Shinkan (真観):

• Trainer- und Vereinsarbeit
• Übungsverwaltung und -suche
• Trainingsplanung für Gruppen
• Fähigkeiten- und Methodenkataloge
• Standardisierung und Wiederverwendung

Technisch gemeinsam:

• Auth-System
• Membership-Basis
• Design-System
• Docker/Deployment-Infrastruktur

Jinkendo App-Familie

mitai.jinkendo.de    → Körper-Tracker (身体)
shinkan.jinkendo.de  → Trainingsplanung (真観)
miken.jinkendo.de    → Meditation (眉間)
ikigai.jinkendo.de   → Lebenssinn (生き甲斐)

---

Version: 0.1.0
Stand: 21.04.2026
Autor: Claude Code