Lars
7043addd15
All checks were successful
Deploy Development / deploy (push) Successful in 42s
Test Suite / pytest-backend (push) Successful in 35s
Test Suite / lint-backend (push) Successful in 0s
Test Suite / build-frontend (push) Successful in 12s
Test Suite / playwright-tests (push) Successful in 57s
- 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>
79 lines
4.8 KiB
Markdown
79 lines
4.8 KiB
Markdown
# 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).
|