# Mitai Jinkendo – Dokumentations-Index

Willkommen zur Entwicklerdokumentation von **Mitai Jinkendo** (身体 Jinkendo).

**Parallel im Repository:** Issue-Epics und Placeholder-Governance im Projekt-[`docs/`](../../docs/) · siehe [`docs/README.md`](../../docs/README.md).

**Ablage-Regeln:** [`.claude/rules/DOCUMENTATION.md`](../rules/DOCUMENTATION.md) · **Issue-Landkarte:** [`GITEA_ISSUES_INDEX.md`](./GITEA_ISSUES_INDEX.md).

_Dieser Ordner `.claude/docs/` ist per `.gitignore`-Ausnahme **versioniert** (Specs + Regeln)._

---

## Dokumentationsstruktur (Ist-Stand)

```
.claude/docs/
├── README.md                 ← Index (diese Datei)
├── GITEA_ISSUES_INDEX.md    ← Themen-Landkarte zu Gitea (lokal gepflegt)
├── BACKLOG.md                ← Feature-Katalog nach Versionen
├── ROADMAP.md                ← Strategische Phasen (0–3)
├── CLEANUP_PLAN.md           ← Historie Bereinigung März 2026
├── prompts/                  ← Exportierte Prompt-Artefakte (JSON)
├── functional/               ← Fachliche Spezifikationen (WAS)
├── technical/                ← Technische Spezifikationen & Referenz (WIE)
├── working/                  ← Arbeitspapiere, Analysen, Session-Snapshots
├── architecture/             ← Querschnitt: Backend/Frontend/Enforcement (kompakt)
└── audit/                    ← Audits, Matrizen, Gitea-Vorlagen
```

**Externes Tracking:** [Gitea Issues](http://192.168.2.144:3000/Lars/mitai-jinkendo/issues)

**Erzeugte Library (Kurzreferenz, ggf. `/document`):** `.claude/library/` – API-, DB- und Architektur-Übersichten; bei Abweichungen gewinnt der **Code**, dann **`technical/`** bzw. **`functional/`**.

---

## Rollen der Ordner

| Ordner | Zweck | Pflege |
|--------|--------|--------|
| `functional/` | Domäne, UX, fachliche Datenflüsse | Bei Feature-Änderungen / Abnahme |
| `technical/` | APIs, Migrationen, Implementierungsmuster, Agent-Guides | Nach größeren Code-Änderungen |
| `architecture/` | Kompakte Architektur-Snippets (z. B. Frontend-Struktur, Backend-Überblick) | Bei strukturellen Umbauten |
| `audit/` | Snapshots (Code-Audit, Platzhalter-Reconciliation) – **nicht** normative Spec | Nur bei neuen Audits erweitern |
| `working/` | Zwischenstände (Migration, Goals-Analysen, STATUS, NEXT_STEPS, PHASE_0C_TASKS, …) | Archivarisch; keine alleinige Norm |
| Root (`ROADMAP`, `BACKLOG`, `GITEA_ISSUES_INDEX`) | Planung, Katalog, Issue-Landkarte | Mit Gitea / `working/` abstimmen |

---

## Abgleich „Dokument ↔ Code“ (Orientierung)

| Thema | Dokument(e) | Prüfpunkt im Repo |
|--------|-------------|-------------------|
| Data Layer / Charts (Phase 0c) | `functional/DATA_ARCHITECTURE.md`, `technical/DATA_LAYER_EXTENSION_GUIDE.md` | `backend/data_layer/`, `backend/routers/charts.py` |
| Platzhalter / Registry | `technical/PLACEHOLDER_REGISTRY_FRAMEWORK.md`, `technical/PLACEHOLDER_DEVELOPMENT_GUIDE.md` | `backend/placeholder_registrations/`, `backend/placeholder_resolver.py` |
| Dashboard-Widgets | `technical/DASHBOARD_WIDGETS_AGENT_GUIDE.md` | Widget-Katalog + Registrierung (siehe Guide) |
| Training Profiler / Resolver | `technical/TRAINING_PROFILE_RESOLVER_LAYER1.md`, `functional/TRAINING_TYPE_PROFILES.md` | Resolver-Module wie im Guide genannt |
| Universal CSV Import | `technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md` | `backend/csv_parser/`, `routers/csv_import.py`, `routers/admin_csv_templates.py` |
| Aktivität Produktionsreife | `technical/ACTIVITY_PRODUCTION_ARCHITECTURE_AND_PHASES.md` (+ EAV-Guide) | `backend/data_layer/activity_session_metrics.py`, `activity_metrics.py`, CSV-Orchestrierung |
| Mitgliedschaft / Features | `technical/MEMBERSHIP_SYSTEM.md`, `architecture/FEATURE_ENFORCEMENT.md` | `backend/auth.py`, Feature-Logging, Router mit Enforcement |

---

## Projekt-Übersicht & Regeln (außerhalb dieses Ordners)

| Dokument | Inhalt |
|----------|--------|
| `CLAUDE.md` (Root) | Agent-Kontext, Tech-Stack, kritische Regeln |
| `.claude/rules/ARCHITECTURE.md` | Verbindliche Architektur-Regeln |
| `.claude/rules/CODING_RULES.md` | Code-Standards |
| `.claude/rules/LESSONS_LEARNED.md` | Wiederkehrende Fehler vermeiden |

---

## Fachliche Spezifikationen (`functional/`)

| Dokument | Thema | Hinweis |
|----------|--------|---------|
| `ACTIVITY_QUALITY_GATES.md` | Qualitäts-Gates Aktivität | |
| `AI_PROMPTS.md` | KI-Prompts, Pipeline, Platzhalter (fachlich) | |
| `DATA_ARCHITECTURE.md` | **Fachliche** Datenarchitektur, Domänenflüsse | Schema-Details → `.claude/library/DATABASE.md` |
| `DEVELOPMENT_ROUTES.md` | Entwicklungsrouten (Roadmap-Thema) | |
| `GOALS_VITALS.md` | Ziele & Vitalwerte (fachlich) | |
| `mitai_jinkendo_konzept_diagramme_auswertungen.md` | Konzept Diagramme (ältere Linie) | |
| `mitai_jinkendo_konzept_diagramme_auswertungen_v2.md` | Konzept Diagramme v2 | |
| `PHASE_0B_IMPROVEMENTS.md` | Phase-0b-Verbesserungen | |
| `RESPONSIVE_UI.md` | Responsive Layout-Spec | siehe auch `docs/issues/PHASE_PLAN_RESPONSIVE_UI.md` |
| `SLEEP_MODULE.md` | Schlaf-Modul | |
| `TRAINING_TYPES.md` | Trainingstypen, Mapping | |
| `TRAINING_TYPE_PROFILES.md` | Trainings-Profile (fachlich) | Techn. Ergänzung: `technical/TRAINING_TYPE_PROFILES_TECHNICAL.md` |

---

## Technische Spezifikationen (`technical/`)

| Dokument | Thema |
|----------|--------|
| `AGGREGATION_METHODS.md` | Aggregation |
| `API_REFERENCE.md` | HTTP-API-Katalog |
| `ARCHITECTURE.md` | System-Architektur |
| `AUTH.md` | Authentifizierung |
| `CENTRAL_SUBSCRIPTION_SYSTEM.md` | Abo-Zentralismus |
| `DASHBOARD_WIDGETS_AGENT_GUIDE.md` | Dashboard-Widgets für Agents |
| `DATABASE.md` | DB-Referenz (docs-Kopie; Library kann aktueller sein) |
| `DATABASE_MODEL_COMPLETE.md` | Vollständiges Modell (Referenz) |
| `DATA_LAYER_EXTENSION_GUIDE.md` | Erweiterung Data Layer |
| `FEATURE_ENFORCEMENT_MAPPING.md` | Feature-IDs / Mapping |
| `FRONTEND.md` | Frontend ausführlich (Seiten, Patterns) |
| `INTERNAL_API_REFERENCE.md` | Interne APIs |
| `MEMBERSHIP_SYSTEM.md` | Tiers, Grants, Enforcement-Details |
| `MIGRATIONS.md` | Migrations-Prozess |
| `PLACEHOLDER_DEVELOPMENT_GUIDE.md` | Platzhalter entwickeln |
| `PLACEHOLDER_REGISTRY_FRAMEWORK.md` | Registry-Pflicht, Metadaten |
| `PROFILE_REFERENCE_VALUES.md` | Profil-Referenzwerte |
| `TRAINING_PROFILE_RESOLVER_LAYER1.md` | Training-Resolver Schicht 1 |
| `TRAINING_TYPE_PROFILES_TECHNICAL.md` | Trainingsprofile technisch |
| `UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md` | Universal CSV: Registry, Executor, Vorlagen, Agent-Checkliste |
| `ACTIVITY_SESSION_METRICS_EAV_AGENT_GUIDE.md` | Session-Metriken EAV, Attributprofile, Layer-1, Prod-Migration |
| `ACTIVITY_COMPOSITE_METRICS_IMPLEMENTATION_CONCEPT.md` | Composite-Metriken in EAV (JSONB), Archetypen, CSV-Slots, Layer-1-Expand, Migration/Test-Checkliste |
| `ACTIVITY_PRODUCTION_ARCHITECTURE_AND_PHASES.md` | **Zielarchitektur** Aktivität (Spine/EAV/Composites/Import/Layer 1–2) + **Phasenplan A–F** Produktionsreife |
| `ACTIVITY_LAYER2A_PLACEHOLDER_AUDIT.md` | Issue #53: Aktivitäts-Platzhalter Layer 1 ↔ 2a (Audit Schritt 1) |
| `ACTIVITY_SCALAR_KANON_TABLE.md` | **Skalar-Kanon** Aktivität (eine Semantik → eine Quelle); Phase A |
| *(Code)* `backend/data_layer/activity_data_canon.py` | **Kanon** activity CSV-Modul vs. EAV-primär; Legacy-Lesefallback |
| `V9D_PHASE2_VITALS_SLEEP.md` | v9d Vitalwerte/Schlaf (Release-Bezug) |

---

## Architektur-Kurzdoks (`architecture/`)

| Dokument | Inhalt |
|----------|--------|
| `BACKEND.md` | Backend-Querschnitt |
| `FEATURE_ENFORCEMENT.md` | 4-Phasen Enforcement |
| `FRONTEND.md` | Strukturbaum `frontend/src` (kompakt) |

*Hinweis:* `architecture/FRONTEND.md` ist die **kurze** Strukturübersicht; Details und Seitenliste stehen in `technical/FRONTEND.md`.

---

## Audit (`audit/`)

Siehe [`audit/README.md`](./audit/README.md).

---

## Gitea vs. Docs

**Prinzip:** Gitea für **Tracking**, Docs für **Spezifikationen** und **Referenz**.

### Gehört in Gitea Issues
- Konkrete Tasks (typisch ≤ wenige Tage), Bugs, Quick Wins, Technical Debt

### Gehört in `functional/`
- Größere Feature-Pakete, Domänenanforderungen, Use Cases, Konzeptdiagramme

### Gehört in `technical/`
- API-, DB- und Implementierungsreferenz, Agent-Leitfäden, Migrations-Details

### Gehört in `ROADMAP.md` / `BACKLOG.md`
- Strategische Phasen bzw. Versions-Katalog mit Links auf Specs und Issues

### Nicht dauerhaft in Docs
- Temporäre To-do-Listen ohne Kontext (→ Issue); reine Duplikate anderer Dateien

---

## Workflow nach Feature-Abschluss

1. Gitea Issue schließen (Commit-Referenz).
2. `BACKLOG.md` / `ROADMAP.md` bei Meilensteinen anpassen.
3. Betroffene `functional/` / `technical/` / `.claude/library/`-Dateien aktualisieren.
4. Bei sichtbaren Agent-Regeln: `CLAUDE.md` ergänzen.

---

## Deployment (Kurzreferenz)

| Umgebung | Frontend | Backend |
|----------|----------|---------|
| Production | Port 3002 | Port 8002 |
| Development | Port 3099 | Port 8099 |

**Gitea:** http://192.168.2.144:3000/Lars/mitai-jinkendo  

---

**Letzte Aktualisierung:** 9. April 2026 (Universal CSV Agent-Guide, Abgleich-Tabelle)