Architektur-Überblick
Diese Seite gibt einen Überblick über die Komponenten von KanzleiSynchron und wie sie lokal zusammenspielen. Sie richtet sich an Entwickler.
Komponenten
Abschnitt betitelt „Komponenten“| Komponente | Technologie | Port (lokal) |
|---|---|---|
| Frontend | Next.js (TypeScript), Verzeichnis frontend/ | 3013 |
| Backend / API | Rust, Axum, Crate-Binary ks-api | 3030 |
| Datenbank | PostgreSQL | 5433 |
| Identity | Ory Kratos (über Docker) | 4433 / 4434 |
Lokal startet der gesamte Stack über ./ks-run.sh (siehe Lokale Entwicklung). PostgreSQL und Kratos laufen über infra/docker-compose.yml; Backend und Frontend laufen nativ.
Request-Fluss
Abschnitt betitelt „Request-Fluss“Die gesamte Arbeit findet auf :3013 statt. Das Frontend ruft seine API über den Same-Origin-Pfad /api/* auf (NEXT_PUBLIC_API_URL=/api). next.config.ts schreibt /api/* serverseitig auf BACKEND_INTERNAL_URL (lokal http://localhost:3030) um.
Browser ──/api/*──▶ Next.js (:3013) ──Rewrite──▶ ks-api (Axum, :3030) ──▶ PostgreSQL (:5433)Dieser Same-Origin-Aufbau ist beabsichtigt: Der Browser schickt das HttpOnly-Cookie ks_session nur an /api/* (auf :3013 gescoped). Ein direkter Cross-Origin-Aufruf des Backends würde das Cookie nicht mitführen.
Backend-Workspace (Rust)
Abschnitt betitelt „Backend-Workspace (Rust)“Das Backend ist ein Cargo-Workspace unter backend/ mit fünf Crates (backend/Cargo.toml, members = ["api", "core", "db", "models", "sample-gen"]):
| Verzeichnis | Crate-Name | Aufgabe |
|---|---|---|
api/ | api (Binary ks-api) | Axum-HTTP-Server: Routen, Auth, Request-Handling. Einstiegspunkt cargo run --bin ks-api. |
core/ | app_core | Domänen-/Geschäftslogik (Abstimmung, Exporte, Periodenlogik). |
db/ | db | Datenbankzugriff, Migrationen, sqlx-Anbindung. |
models/ | models | Geteilte Datentypen und Fehlertypen (z. B. models::common::KsError). |
sample-gen/ | sample-gen | Generator für Beispiel-/Testdaten. |
Die API-Routen liegen unter backend/api/src/routes/ — u. a. uploads, exceptions, periods, reports, exports, handoff, stb, settings, admin, ops, privacy, audit_pack.
Authentifizierung
Abschnitt betitelt „Authentifizierung“- Identitäten werden über Ory Kratos verwaltet; der Login-Flow läuft über das Frontend (
/api/auth/login). - Die Sitzung wird in einem HttpOnly-Cookie
ks_sessiongehalten, das auf:3013gescoped ist und automatisch an/api/*mitgeschickt wird. - Das Backend leitet aus der Sitzung den
AuthUser(inkl.tenant_id,user_id,role) ab (backend/api/src/auth.rs).
Mandantentrennung & Rollen
Abschnitt betitelt „Mandantentrennung & Rollen“KanzleiSynchron ist mandantenfähig: Importe, Abstimmungen, Ausnahmen und Übergabepakete sind strikt pro Mandant getrennt. Jede Backend-Abfrage filtert auf tenant_id aus dem AuthUser.
Die Berechtigungen folgen einem zweiachsigen Rollenmodell (Mandanten-Rollen wie reviewer / merchant_admin und interne Ops-Rollen). Details und die vollständige Matrix: Rollen & Capabilities.
Übergabepaket
Abschnitt betitelt „Übergabepaket“Das 6-Datei-Übergabepaket wird in backend/api/src/routes/handoff.rs in einer Transaktion erzeugt (POST /handoff/:period_id/build-pack) und in handoff_pack_files persistiert. Die Dateien: UStVA-preview.xml, BWA.pdf, ZM-EU-recap.csv, DATEV-EXTF.csv, audit-log.jsonl und manifest.sha256. Der DATEV-EXTF-Export folgt dem Format v7.0 (backend/api/src/routes/exports.rs).