Zum Inhalt springen
Werkszeit Docs

Werkszeit App — Architektur-Übersicht

Die Werkszeit-App-Familie besteht aus drei Komponenten:

  1. Mobile-App (Flutter, iOS + Android, ein Codebase)
  2. Web-Portal (Astro Static + Hono API; werkszeit.de + admin.werkszeit.de)
  3. API (Hono + Drizzle + PostgreSQL 16, gehostet auf AWS App Runner)

Diese Architektur-Übersicht ist die Entwickler-Tiefenseite zur App-Beschreibung auf werkszeit.de/app/. Wer einen User-Flow nachvollziehen will, sollte parallel das jeweilige Feinkonzept im Repo öffnen — die Feinkonzepte sind die maßgebliche Wahrheits-Quelle.

C4 — System-Kontext

Abschnitt betitelt „C4 — System-Kontext“
graph TD
  Inhaber[Inhaber/Bauleitung]
  Mitarbeiter[Mitarbeiter]
  Steuerberater[Steuerberater/DATEV]


  Inhaber -->|Web-Portal| Marketing[werkszeit.de + /admin/]
  Mitarbeiter -->|iOS/Android| App[Werkszeit Mobile-App]
  Mitarbeiter -->|ESS Web| Marketing
  Marketing --> API[api.werkszeit.de]
  App --> API
  API --> DB[(PostgreSQL 16, RLS)]
  API --> S3[(S3 eu-central-1)]
  API -->|EXTF/LODAS| Steuerberater

C4 — Container

Abschnitt betitelt „C4 — Container“
graph LR
  subgraph "AWS eu-central-1 (Frankfurt)"
    CFwww[CloudFront werkszeit.de]
    CFdocs[CloudFront docs.werkszeit.de]
    CFapi[CloudFront api.werkszeit.de]
    S3www[S3 marketing-prod]
    S3docs[S3 docs-prod]
    AppRunner[App Runner Hono API]
    RDS[(RDS PostgreSQL 16, Multi-AZ)]
    S3files[S3 Files & Backups]
  end


  CFwww --> S3www
  CFdocs --> S3docs
  CFapi --> AppRunner
  AppRunner --> RDS
  AppRunner --> S3files

Auth-Flow — Passkey-Login

Abschnitt betitelt „Auth-Flow — Passkey-Login“
sequenceDiagram
  participant U as Mitarbeiter
  participant App as Mobile App
  participant API as api.werkszeit.de
  participant DB as PostgreSQL


  U->>App: Tippt "Mit Face ID anmelden"
  App->>API: POST /v1/auth/passkey/login/begin
  API->>DB: SELECT challenge
  DB-->>API: Challenge-Bytes
  API-->>App: Challenge + RP-ID
  App->>U: Face-ID-Prompt
  U-->>App: Biometrie OK
  App->>API: POST /v1/auth/passkey/login/finish (Signatur)
  API->>DB: Verify + create session
  API-->>App: Set-Cookie werkszeit.session

Datenmodell-Prinzipien

Abschnitt betitelt „Datenmodell-Prinzipien“
  • Multi-Tenancy: Alle Geschäftsdaten sind über tenant_id mandantenisoliert. Postgres Row-Level-Security erzwingt die Isolation auf Datenbank-Ebene — die Anwendung kann keine Tenant-Grenze versehentlich überschreiten.
  • Append-only Geschäfts-Tabellen: Zeitbuchungen, Bautagebuch-Einträge, Audit-Events sind unveränderlich. Korrekturen sind neue Versionen mit Verweis auf den Vorgänger.
  • Hash-Chain-Audit: Jeder Audit-Eintrag enthält prev_hash, der den SHA-256-Hash des Vorgängereintrags spiegelt. Eine nachträgliche Manipulation bricht die Kette unabhängig prüfbar.

Compliance-Architektur

Abschnitt betitelt „Compliance-Architektur“

Compliance ist nicht nachträglich auf die App geschraubt, sondern in jeder Schicht verankert:

Anforderung Realisierung Schicht
GoBD §147 AO Hash-Chain + 10-Jahres-Aufbewahrung in S3 (90 Tage Lifecycle bis Glacier) DB-Trigger + S3-Lifecycle
ArbZG §3/§4/§5 Echtzeit-Policy-Engine, Pause/Ruhezeit/Höchstgrenze API-Service (arbeitszeit-compliance)
DSGVO Art. 15/17/20 DSGVO-Export-Endpoint, ESS-Datenexport API-Endpoints + Cron-Jobs
BetrVG §87 Abs. 1 Nr. 6 Login-Event-White-List, kein Verhalten/Leistung-Tracking Audit-Konfiguration
BFSG (ab 28.06.2025) WCAG 2.1 AA + axe-core in CI Tests + Komponenten-Layer
XRechnung 3.0 KoSIT UBL/CII-Generator + KoSIT-Validator vor Versand Service-Module bau-abrechnung

Verlinkungen

Abschnitt betitelt „Verlinkungen“