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 | | Lessons Learned | .claude/rules/LESSONS_LEARNED.md | | Setup-Dokument | .claude/docs/working/SHINKAN_PROJECT_SETUP.md | | Anforderungen | .claude/docs/functional/SHINKAN_REQUIREMENTS.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 · training_units · training_programs
    planning · import_wiki · admin · membership

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: v0.1.0 (Initial Setup)

Status: Initial Setup in Arbeit
Branch: develop
Nächster Schritt: Basis-Migrationen + Core-Router

Updates (21.04.2026 - Initial Setup)

• Repository: Erstellt auf Gitea
• Basis-Struktur: Verzeichnisse angelegt
• Von Mitai übernommen: auth.py, db.py, db_init.py
• Eigene Dateien: version.py, CLAUDE.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)

Trainingsplanung:

• training_templates - Vorlagen / Standards
• training_sections - Trainingsabschnitte
• section_exercises - Übungen in Abschnitten
• training_units - Konkrete Trainingseinheiten
• training_programs - Trainingsprogramme

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

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