Code Architektur

Code-Architektur

Diese Seite ergänzt das Infrastrukturdiagramm um die Struktur innerhalb der Anwendungen.

Backend

HTTP/WebSocket
    ↓
app/api/routes/        Routing, Auth-Abhängigkeiten, Statuscodes
    ↓
app/services/          Geschäftslogik und Transaktionsabläufe
    ↓
app/repositories/      SQLAlchemy-Abfragen und Persistenz
    ↓
app/models/            ORM-Modelle
    ↕
app/schemas/           Pydantic-Ein-/Ausgabemodelle

Querschnittsfunktionen liegen unter app/core/: Konfiguration, Datenbank, Sessions, MFA/WebAuthn, Redis, Rate-Limits, Fehlerprotokollierung und Kryptografie.

Verantwortlichkeiten

• Route: Request validieren, Benutzer/Sitzung laden, Service aufrufen, Response-Modell und passenden HTTP-Status definieren.
• Service: Geschäftsregeln, Berechtigungsentscheidungen und mehrere Repositories koordinieren.
• Repository: Daten laden/speichern; keine UI- oder HTTP-Entscheidungen treffen.
• Schema: öffentliche API-Verträge; interne Integer-IDs nicht nach aussen geben.
• Modell: Tabellen, Beziehungen, Constraints und Indizes.

Neue Fachlogik gehört nicht direkt in eine Route, wenn sie unabhängig vom HTTP-Endpunkt testbar oder von mehreren Endpunkten verwendbar ist.

IDs und Tenant-Scoping

Intern verwendet PostgreSQL Integer-IDs. Extern werden public_id-Werte ausgegeben und akzeptiert. PublicIdModel übersetzt Modell- und Fremdschlüssel-IDs für Read-Schemas.

Jeder Zugriff auf mandantenbezogene Daten muss den aktuellen Mandanten berücksichtigen. Eine Ressource nur anhand ihrer ID zu laden und anschliessend ungeprüft zu ändern ist ein Cross-Tenant-IDOR. Bestehende Access-Services und tenant-gescopte Repository-Methoden sind zu bevorzugen.

Frontend

app/                    Next.js App-Router, Seiten und Layouts
components/             Fachkomponenten und gemeinsame UI
lib/api/                Browser- und Server-API-Zugriff
lib/hooks/              wiederverwendbare Client-Zustände
lib/offline-store.ts    Offline-Pufferung
types/                  API-Typen
e2e/                    Playwright-Szenarien

Server-Komponenten laden Sitzungsdaten über backendFetchWithSession. Browser-Aufrufe verwenden relative /api/...-Pfade mit Cookies und sind dadurch auf Haupt- und Custom-Domains same-origin. Fehler werden als ApiError in die Kategorien offline, timeout, backend, auth, validation und conflict übersetzt.

Kollaboration und Offline-Verhalten

REST-Endpunkte bleiben die persistente Quelle für Autosave. Der WebSocket unter /api/ws/protocols/{id} transportiert Presence, Sperren und Änderungsereignisse. Redis hält diesen Zustand nur ephemer.

Der Client:

• sendet Heartbeats für gehaltene Sperren;
• verbindet sich mit exponentiellem Backoff neu;
• gleicht Sperren nach Reconnect mit dem Server-Snapshot ab;
• kann weiter über REST speichern, wenn die Kollaborationsverbindung ausfällt;
• puffert dafür geeignete Änderungen im Offline-Store und behandelt Konflikte explizit.

Vorlagen und Protokolle

Ein Protokoll übernimmt beim Erstellen einen Snapshot seiner Vorlage. Spätere Vorlagenänderungen dürfen bestehende Protokolle nicht verändern. Live referenzierte Listen-/Verantwortlichkeitswerte werden beim Abschluss eingefroren. Änderungen an diesem Verhalten benötigen Service-, Export- und E2E-Tests.

Word-Import

Der Word-Import besteht aus isoliertem Parsing, Matching/Qualitätsbewertung, Vorschau, Queue und Commit. Relevante Services liegen unter app/services/word_import_* und isolated_parse.py. Parser-Ergebnisse dürfen nicht ungeprüft persistiert werden; Zuordnungen und Schwellenwerte müssen in der Vorschau nachvollziehbar bleiben.

Exporte und Dateien

Dateien werden über FileService und konfigurierte Storage-Verzeichnisse verwaltet. PDF-/Dokumentexporte laufen über ExportService; generierte Ergebnisse sind regenerierbar und unterliegen Retention. Uploads benötigen Grössenprüfung, MIME- und Magic-Byte-Prüfung, sichere Pfade, Quota und – je nach Typ – ClamAV-Scan.

Hintergrundaufgaben

Beim FastAPI-Start werden periodische Health-, Rescan-, Export- und Log-Cleanup-Schleifen gestartet. Weil mehrere Uvicorn-Worker laufen können, schützen PostgreSQL-Advisory-Locks vor doppelter Ausführung. Neue periodische Jobs müssen demselben Muster folgen oder eine andere explizite Single-Runner-Garantie besitzen.