Lars/shinkan-jinkendo
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 3 Wiki Activity
main
shinkan-jinkendo/docs/architecture/VERBINDLICHE_REGELN_SHINKAN.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.3 KiB
Raw Permalink Blame History

Verbindliche Architekturregeln – Shinkan (Ergänzung)

Status: verbindlich für die Shinkan-Codebasis, ergänzend zu:

  • .claude/rules/ARCHITECTURE.md
  • .claude/rules/CODING_RULES.md
  • .claude/docs/technical/ACCESS_LAYER_AND_GOVERNANCE_PLAN.md
  • .claude/docs/technical/MEDIA_ASSETS_AND_ARCHIVE_SPEC.md

Bei Widerspruch gewinnt die spezifischere Regel zur Zugriffsschicht und Governance (Sicherheit vor Komfort). Bei Widerspruch zwischen diesem Dokument und allgemeinen Mitai-Template-Resten in ARCHITECTURE.md gilt für Shinkan dieses Dokument und die Shinkan-Pflichtlektüre in CLAUDE.md.

S1 – Frontend: Grösse und Zerlegung von Seiten

  1. Soft-Limit: Neue oder stark erweiterte Seiten sollen unter ~500 Zeilen im Page-File bleiben. Darüber: Auslagern in Komponenten/Hooks/Feature-Module mit klaren Namen.
  2. Ausnahmen nur mit Kurzbegründung im PR und Verweis auf Messung (Bundle/Performance) oder fachliche Unteilbarkeit.
  3. Wiederkehrende UI-Blöcke nicht per Copy-Paste über Seiten hinweg duplizieren; extrahieren in components/ oder features/.

S2 – Frontend: Listen und Speicher

  1. Listen, die typischerweise > 100 sichtbare oder gehaltene Einträge im DOM ermöglichen, müssen virtualisiert werden (oder serverseitig strikt begrenzt + „mehr laden“ mit dokumentiertem UX – nicht beides unbegründet ignorieren).
  2. Modals und zweite Raster gleichzeitig zum Hauptbaum nur laden, wenn geöffnet (lazy mount), wo technisch machbar ohne UX-Bruch.

S3 – Frontend: API-Zugriff

  1. Alle API-Aufrufe über die zentrale Schicht (utils/api bzw. nach Modularisierung dessen Module). Kein fetch('/api/...') ohne diese Schicht.
  2. Während der Migration vom API-Monolithen: neue Endpoints ausschliesslich im domänenspezifischen Modul anlegen; nur bei Bedarf Re-Export über die Facade.

S4 – Frontend: Globale Daten und Context

  1. Neue global geladene Daten (jede authentifizierte Session) bedürfen technischer Begründung (Badge-Kritikalität, Sicherheit). Alternative: on-demand beim ersten Bezug oder TTL-Cache mit dokumentierter Invalidierung (shinkan:…-Events bleiben möglich).
  2. Context-value-Objekte müssen stabil gehalten werden (useMemo / useCallback), wenn nicht-triviale Unterbäume davon abhängen (bereits etabliert für Auth; gleiches Muster für neue Contexts).

S5 – Backend: Lesepfad-Design

  1. Keine mehrfachen fast identischen Listenaufrufe durch den Client für denselben zusammensetzbaren Bildschirm, wenn ein einzelner Summary-Endpoint unter gleicher Sichtbarkeitslogik möglich ist. Ausnahme: nachweislich unterschiedliche Cache-Lebensdauer oder unterschiedliche Rechte – dokumentieren.
  2. Neue Listen-Endpoints: Paginierung (limit/offset oder Keyset nach Roadmap) und Obergrenzen; keine „unbegrenzt alles“-Defaults für grosse Tabellen.
  3. Schwere SQL-Konstruktionen (viele korrelierte Subqueries pro Zeile) nur mit Kommentar Warum und Hinweis auf Indexlage oder geplantes Refactoring-Ticket.

S6 – Backend: Mandanten und Caching

  1. Kein HTTP- oder Anwendungs-Cache für mandantenspezifische oder nutzerspezifische Daten ohne expliziten Schlüssel (mindestens: Tenant-Kontext + relevante Parameter) und Invalidierungsstrategie.
  2. Öffentliche oder global geteilte Katalogdaten dürfen mit ETag / kurzem Cache optimiert werden – nach Abgleich mit Governance.

S7 – Performance und Messung (Definition of Done für grössere Features)

  1. Features, die neue Listen schwerer als bestehende Top-10-Queries machen oder > ~50 KB zusätzliches Client-JS pro Route erzeugen: kurz messen (Lighthouse mobil oder Netzwerk-Timing) und im PR festhalten.
  2. Regressions in p95 der betroffenen API nach Deploy: bei Bedarf Rollback- oder Nachsteuerungskriterium mit Team vereinbaren (Zahlen Zielbild/Roadmap).

S8 – Feature-Checkliste (DoD)

Vor Merge einer grösseren Erweiterung:

  • Zugriffsschicht / Audit aktualisiert (falls zutreffend)
  • Kein Verstoss gegen S1–S7 ohne dokumentierte Ausnahme
  • Keine neue direkte DB-Nutzung im Frontend
  • Medien/Lifecycle (falls Medien betroffen) nach Media-Spec

Änderungen an diesen Regeln nur mit expliziter Projektfreigabe (analog zu ARCHITECTURE.md).