Lars/shinkan-jinkendo
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 3 Wiki Activity
0d34c0a73d
shinkan-jinkendo/docs/architecture/ZIELBILD_ARCHITEKTUR.md
Lars 7043addd15
All checks were successful
Deploy Development / deploy (push) Successful in 42s
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 12s
Details
Test Suite / playwright-tests (push) Successful in 57s
Details
feat(docs): update architecture documentation references and enhance handover details 
- Added references to the architecture target image, refactor roadmap, and binding Shinkan rules in CLAUDE.md and HANDOVER.md for better project clarity.
- Updated the Dashboard component to improve user authentication handling and optimize data loading, enhancing overall performance and user experience.

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

4.8 KiB
Raw Blame History

Architektur-Zielbild – Shinkan Jinkendo

Geltungsbereich: Trainer-/Vereinsplattform, Multi-Tenancy und Governance nach bestehender Zugriffsschicht.
Ziele: dauerhaft tragfähig, performant bei vielen gleichzeitigen Nutzern, akzeptabel auf geringer Client-Leistung (wenig RAM/CPU), wartbar und so strukturiert, dass neue Features ohne neue Grosseinkaufe an technischer Schuld einbindbar sind.

1. Leitprinzipien

  1. API-first, Mandanten-sicher – Fachlogik und Sichtbarkeit serverseitig; das Frontend orchestriert und zeigt. Unverändert gemäss bestehender Regeln (ACCESS_LAYER, Governance-Helfer).
  2. Schlanke Client-Oberfläche – JavaScript pro Route begrenzen; schwere Abhängigkeiten nur bei Bedarf laden; Listen dort virtualisieren, wo Grössenordnungen wachsen.
  3. Explizite Lesepfade – Aggregation und Zusammenfassungen dort, wo mehrere fast gleiche Requests heute nötig sind (Dashboard, Badges), statt Chatty-Client-Muster.
  4. Vorhersehbarkeit für die DB – Listenqueries ohne unnötige O(n)·Subquery-Kosten pro Zeile; Indizes und Paginierungsstrategie sind Teil des Designs.
  5. Feature-Einbindung per Checkliste – Jedes neue Feature durchläuft die gleiche Architektur- und Performance-Checkliste (siehe Regeldokument), bevor es als „fertig“ gilt.

2. Zielbild Frontend

2.1 Struktur

  • Seiten (pages/) bleiben Routing-Einstiege und Komposition; keine Dauerlösung für Logikblöcke > ~400–500 Zeilen in einer Datei – Auslagerung in components/, hooks/, features/<name>/.
  • Feature-Ordner (Ziel): wo sinnvoll frontend/src/features/<domäne>/ mit klarer Grenze: UI + feature-spezifische Hooks; geteilte Helfer in utils/ nur wenn domänenübergreifend.
  • State: Server-State über API (keine Business-Duplikation); UI-State lokal oder in bestehenden Contexts nur, wenn mehrere Schichten der Shell betroffen sind.

2.2 Performance und schwache Endgeräte

  • Route-basiertes Code-Splitting bleibt Standard; zusätzlich innere dynamic import() für schwere Pakete (PDF, grosse Editoren), sobald eine Route sie braucht.
  • Lange Listen: Virtualisierung ab einer projektdefinierten Schwelle (siehe Regeln).
  • Globale Daten (Posteingang, Badges): bedarfsgesteuert oder mit klar dokumentiertem Cache/TTL, nicht pauschal jede Session mit voller Last – konkrete Strategie in Roadmap/Remediation.

2.3 API-Schicht im Client

  • Ziel: Aufteilung des heutigen utils/api.js-Monolithen in domänenspezifische Module (z. B. api/exercises, api/planning, api/media), mit einer dünnen Barrel- oder Facade-Export für Kompatibilität während der Migration.
  • Konstante: alle HTTP-Aufrufe mit Token/Mandanten-Headern zentral; kein Rohtransport aus Komponenten.

3. Zielbild Backend / API

  • Router-Disziplin unverändert: ein fachliches Modul, ein Router (bestehende Architekturregeln).
  • Read-Model / Summary-Endpoints für Dashboards und wiederkehrende Kacheln: eine abgestimmte Antwort pro Bildschirm, wo heute mehrere Listen parallel zusammengerechnet werden – unter strikt gleicher Sichtbarkeitslogik wie die Einzel-Endpoints.
  • Listen: sortierte Indizes passend zu WHERE + ORDER BY; für grosse Datenmengen langfristig Keyset-Pagination statt tiefer Offsets.
  • Schwere Queries: Korrelierte Subqueries pro Zeile nur, wenn messbar unkritisch; sonst JOIN-/Aggregate-Refactoring mit Review.

4. Zielbild Datenhaltung

  • PostgreSQL bleibt System der Wahrheit; Migrationen nummeriert, wie heute.
  • Kein Mandanten-Cache ohne expliziten Key und Invalidierungskonzept (Regeldokument).

5. Einbindung neuer Features (vereinbartes Muster)

  1. Fachliche Kurzspez (oder Ticket) mit Sichtbarkeit und Nutzungskontext (Mobile/Desktop, erwartete Listenlängen).
  2. API-Design: Endpoints, Payload-Grösse, Paginierung; Zugriffsschicht-Check.
  3. UI-Modul: Route lazy, Komponentengrösse, ggf. Virtualisierung.
  4. Messung: minimal Lighthouse/Netzwerk oder Server-Timing für den neuen Pfad.
  5. Audit-Eintrag bei neuen geschützten Endpoints (bestehendes Verfahren).

6. Nicht-Ziele dieses Zielbilds

  • Ersetzen der Zugriffsschicht oder der Medien-Spec.
  • Microservices oder zweite Schreib-Datenbank ohne ausdrücklichen Projektbeschluss.
  • „Framework-Wechsel“ (React bleibt, solange nicht separat entschieden).

7. Abnahme „Zielbild erreicht“ (high level)

  • Keine bekannten God-Pages oberhalb dokumentierter Schwellen ohne dokumentierte Ausnahme.
  • API-Client modularisiert oder klar phasierter Migrationsstand mit festem Enddatum.
  • Dashboard und vergleichbare Homescreens ohne redundante Mehrfach-Listen desselben Objekttyps (oder dokumentierte technische Begründung + Messung).
  • Datenbank-Lesepfade der Top-5-Listen unter definierter Latenz-Schwelle auf Referenz-Hardware in Lasttests (Werte in Roadmap festzulegen).