Lars/shinkan-jinkendo
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 3 Wiki Activity
main
shinkan-jinkendo/docs/architecture/SCHULDEN_UND_REMEDIATION.md
Lars 4b2848c7c3
All checks were successful
Deploy Development / deploy (push) Successful in 41s
Details
Test Suite / pytest-backend (push) Successful in 35s
Details
Test Suite / lint-backend (push) Successful in 0s
Details
Test Suite / build-frontend (push) Successful in 11s
Details
Test Suite / playwright-tests (push) Successful in 57s
Details
feat(docs): add performance baseline documentation and update architecture references 
- Introduced a new section for the Performance-Baseline in CLAUDE.md and updated HANDOVER.md to include references to the new BASELINE_SNAPSHOT.md.
- Enhanced architecture documentation in README.md to clarify the purpose of the baseline snapshot and its relevance to the refactor roadmap.
- Refactored OrgInboxContext to implement a unified loading logic for join requests and content reports, improving code maintainability and performance.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-14 06:53:37 +02:00

5.2 KiB
Raw Permalink Blame History

Architekturschuld – Erfassung und Behebungsschritte

Dieses Dokument listet bewusst die aus MVP und Code-Review bekannten strukturellen Themen auf und ordnet konkrete Massnahmen zu. Reihenfolge ist an die Roadmap gekoppelt; hier die inhaltliche Detailierung.

A. Frontend

A1 – „God Pages“ (Training, Übungsformular, Vereine)

Schuld: Sehr grosse Dateien (tausende Zeilen) mit viel State, vielen Effekten und eingebetteten Modals.

Risiko: Hohe Re-Render-Kosten, schwerer zu testen, hoher RAM auf schwachen Geräten, neue Features vergrössern die Datei weiter.

Behebungsschritte:

  1. Inventar: pro Page kurze Gliederung (Abschnitte) und Ziel-Komponenten benennen.
  2. Extrahieren: Zuerst isolierbare Blöcke (Listen, Modals, Sidebar, Form-Sektionen) in Unterkomponenten; Props/Oberfläche dokumentieren.
  3. Hooks: wiederkehrende Logik (useEffect-Ketten, Filter-State) in useXxx-Hooks pro Domäne.
  4. Optional features/training/ o. ä.: wenn 3+ zusammengehörige Komponenten entstehen.

Erfolgskriterium: Page-Datei unter dem in VERBINDLICHE_REGELN_SHINKAN.md genannten Soft-Limit oder dokumentierte Ausnahme.

A2 – Monolithischer API-Client (utils/api.js)

Schuld: Eine Datei bündelt alle Endpoints; erschwert Tree-Shaking, Navigation und domänenweise Ownership.

Behebungsschritte:

  1. Verzeichnisstruktur festlegen, z. B. frontend/src/api/ mit client.js (Token, request), exercises.js, planning.js, …
  2. Bestehende api.js schrittweise zur Facade (export * from …) degradieren oder re-exportieren.
  3. Neue Features nur in domänenspezifischen Dateien implementieren.

Erfolgskriterium: Kein Wachstum des Monolithen über bestehende Endpoint-Anzahl hinaus; mittelfristig dominieren kleine Module.

A3 – Redundante und „chatty“ Client-Requests

Schuld (Beispiele): Dashboard lädt Profil erneut trotz Auth; mehrere nahezu gleiche listTrainingUnits-Aufrufe; doppelte listExercises für KPIs.

Risiko: Mehr Last auf API/DB, schlechtere UX auf langsamen Geräten.

Behebungsschritte:

  1. Profil: eine kanonische Quelle (Auth-Profil reicht für Anzeige; fehlende Felder gezielt nachladen oder Auth-Check erweitern – fachlich klären).
  2. Dashboard: einen Summary-Endpoint spezifizieren und implementieren (siehe Backend B1) oder Client auf einen aggregierten Aufruf reduzieren.
  3. Org-Inbox / globale Fetches: Ladestrategie definieren (on-demand vs. TTL vs. sichtbarkeitsabhängig) und OrgInboxContext entsprechend umbauen.

Stand Umsetzung: Gemeinsame Funktion fetchOrgInboxSnapshot für Mount und refreshOrgInbox (ein Codepfad, gleiche API-Calls). Optionales verzögertes Laden / TTL weiterhin offen.

Erfolgskriterium: Dashboard-Initialisierung ohne redundanten getCurrentProfile; ohne drei parallele fast gleiche Trainingslisten (oder dokumentierte Ausnahme).

A4 – Schwere Abhängigkeiten

Schuld: PDF/Markdown/Canvas-Pfade ziehen grosse Chunks.

Behebungsschritte: Strikte import() an Nutzeraktion; keine statischen Top-Level-Imports schwerer Libs in gemeinsamen Einstiegspfaden.

Erfolgskriterium: Lighthouse / Bundle-Analyse zeigt schwere Libs nur auf betroffenen Routen.

B. Backend

B1 – Aggregations- und Summary-APIs

Schuld: Bildschirme holen mehrere Listen und aggregieren im Client.

Behebungsschritte:

  1. Endpoint(s) z. B. GET /api/dashboard/summary oder domänenspezifisch mit gleicher Sichtbarkeitslogik wie Einzel-Listen.
  2. Tests oder manuelle Checkliste gegen Tenant-Leaks (nur eigene/sehbare Daten).
  3. Versionierung in version.py bei neuem Router-Block oder signifikantem Modul-Update.

Erfolgskriterium: Fertigest Dashboard mit einer serverseitigen Zusammenfassung (oder festgelegte Client-Reduktion mit Messung).

B2 – Listenqueries (z. B. Übungsliste)

Schuld: Korrelierte Subqueries pro Zeile können bei Wachstum teuer werden.

Behebungsschritte:

  1. EXPLAIN (ANALYZE, BUFFERS) auf Produktions-näher Konfiguration mit realistischem limit.
  2. Indizes für Filter und Sortierung ergänzen.
  3. Refactoring: JOINs/LATERAL statt N-facher Subquery, wo messbar besser.

Erfolgskriterium: Dokumentierte p95-Zielwerte erreicht oder Trend verbessert (siehe Roadmap).

B3 – Pagination

Schuld: Tiefe OFFSET-Werte skalieren schlecht.

Behebungsschritte: Keyset-Pagination für grosse Listen in späteren Phasen einführen; API-Vertrag dokumentieren.

C. Querschnitt

C1 – Messbarkeit

Schuld: Optimierung ohne Baseline.

Behebungsschritte: Einmalig Baseline (API p95, Bundle-Grössen Haupt-Route, ein Lasttest-Szenario) festhalten; wiederholen nach grossen Phasen.

C2 – Dokumentation und Audit

Schuld: Wissen nur in Chats.

Behebungsschritte: HANDOVER.md und ACCESS_LAYER_ENDPOINT_AUDIT.md bei jedem grösseren API-Block aktualisieren; Roadmap-Phase abhaken.

Mapping: Schuld → Regel

Schuld Primär-Regel (Shinkan)
God Pages S1, S2
API-Monolith S3
Globale Fetches S4
Chatty API S5
Caching-Ideen S6
Grössere Features ohne Messung S7, S8