direkt-vermittlung-de/docs/decisions.md

Decision Log: DirektVermittlungDe

Status: Approved Date: 2025-12-01 Context: [DvdArchitektur.txt], [Introduction.txt]

Here is the formal Decision Log for the DirektVermittlungDe (DVD) project. This document captures the critical architectural choices, the options considered, and the rationale based on the provided requirements and constraints.

Decision Log: DirektVermittlungDe

Status: Approved Date: 2025-12-01 Context: [DvdArchitektur.txt], [Introduction.txt]

---

ADR-001: Separation of Metadata and Content Payload

Context: [cite_start]The system requires an automated Routing-Engine to assign documents to the correct authority[cite: 4]. [cite_start]However, strict End-to-End Encryption (E2E) is required for sensitive data in transport and rest[cite: 23]. The server cannot route what it cannot read.

Decision: We will implement a Split-Payload Model:

1. [cite_start]Metadata (Plaintext): A defined set of non-sensitive routing criteria (e.g., Authority ID, Reference/Aktenzeichen, Document Type) is sent as unencrypted JSON (over TLS)[cite: 3].
2. [cite_start]Payload (Encrypted): The actual PDF document and sensitive message content are encrypted on the client side and stored as opaque blobs[cite: 23, 42].

Rationale:

• [cite_start]Compliance: Satisfies NFR-5 (Privacy/Encryption) while enabling FR-2 (Auto-routing)[cite: 4, 23].
• [cite_start]Performance: The Routing Engine operates on lightweight JSON metadata (< 500ms target) without needing to decrypt/encrypt heavy files[cite: 20].

[Image of end to end encryption architecture]

---

ADR-002: Stateless Authentication via OAuth2/JWT

Context: [cite_start]The system must support 10k+ concurrent sessions per region [cite: 20] [cite_start]and allow horizontal scaling (TC-2)[cite: 40]. Traditional server-side sessions (sticky sessions) would hinder scalability.

Decision: Use OAuth2 with OpenID Connect (OIDC) and stateless JWTs (JSON Web Tokens) for session handling.

• Citizens: Authenticate via BundID/eID.
• [cite_start]Officials: Authenticate via Authority SSO (SAML/OIDC integration)[cite: 35].

Rationale:

• [cite_start]Scalability: Allows the backend to be purely stateless; any instance can service any request (TC-2)[cite: 40].
• [cite_start]Security: Scopes (e.g., citizen:write, official:read) map directly to the least-privilege NFR-6[cite: 24].

---

ADR-003: Pagination Strategy for Interaction Threads

Context: Interaction threads (FR-3) can grow long over time. [cite_start]The NFR-1 target is a response time of < 300ms for core operations[cite: 19]. Standard "Page/Offset" pagination degrades in performance as datasets grow (Offset Drifting) and handles real-time updates poorly.

Decision:

• Cursor-based Pagination: Used for InteractionThreads (chat history). The cursor will be the timestamp of the message.
• [cite_start]Offset-based Pagination: Retained for the Official’s Case List/Inbox (FR-1.2), where users expect to "jump to page 2"[cite: 13].

Rationale:

• [cite_start]Performance: Cursor seeking is O(1) complexity, ensuring the 300ms SLA is met regardless of thread length[cite: 19].
• [cite_start]Usability: Prevents "missing messages" or duplicates if new messages arrive while a user is scrolling (essential for chat)[cite: 8].

---

ADR-004: Asynchronous Processing for Data Exports

Context: [cite_start]Authorities need to export data (PDFs + History) to their eAkte systems (FR-7)[cite: 11]. Generating these packages is resource-intensive and unpredictable in duration, which risks timing out a synchronous HTTP request.

Decision: Implement the Asynchronous Request-Reply Pattern.

1. Client POSTs to /exports and receives 202 Accepted + Job-ID.
2. [cite_start]Background workers (via Message Queue) process the PDF assembly[cite: 43].
3. Client polls for completion or receives a webhook.

Rationale:

• [cite_start]Resilience: Prevents blocking the main API threads, protecting the availability goal of ≥ 99.5%[cite: 25].
• User Experience: Provides immediate feedback to the official instead of a loading spinner that might freeze.

---

ADR-005: Resource Naming and Structure

Context: [cite_start]The API must be intuitive ("Clean API") and extensible[cite: 17]. The domain model includes "Documents", "Threads", and "Routing".

Decision: Adopt a Document-Centric REST hierarchy:

• [cite_start]Root: /documents (The core "Envelope")[cite: 2].
• [cite_start]Sub-resource: /documents/{id}/threads (The communication context)[cite: 6].
• [cite_start]Strict Nouns: Use /documents instead of /uploadDocument[cite: 44].

Rationale:

• [cite_start]Alignment: Matches the architectural definition of DVD being "belegorientiert" (document-driven), not just a generic chat app[cite: 17].
• Extensibility: Allows adding new sub-resources (e.g., /documents/{id}/audit-log or /documents/{id}/appeals) without breaking the root model.

---

ADR-006: Data Retention & Deletion

Context: [cite_start]Standard behavior requires data deletion after the case is closed (FR-6)[cite: 9]. [cite_start]However, users can opt for a "Personal Archive"[cite: 10, 15].

Decision: Implement a TTL (Time-To-Live) Engine on the database rows.

• Default: deletionDate = closedAt + gracePeriod.
• Archive Option: If personalArchive is active, deletionDate is set to null or an extended timestamp.

Rationale:

• [cite_start]GDPR Compliance: Ensures Privacy-by-Design (NFR-4) by automating the "Right to Erasure" / data economy principles[cite: 21].
• Automation: Reduces administrative overhead for cleanup.

ADR-007: Python & ProcessPoolExecutor for Backend Services

Context: The implementation team utilizes Agentic Coding (LLM-driven TDD). While Go/Java offers native concurrency, Python provides superior velocity with LLMs. However, Python's GIL risks blocking the event loop during CPU-intensive tasks (Encryption, PDF merging). Decision: Implement the Service Layer in Python (FastAPI) with a strict Hybrid Concurrency Pattern:

1. I/O (DB/Network): Native async/await.
2. CPU (Crypto/PDF): Must be offloaded to a ProcessPoolExecutor. Rationale:

• Velocity: Maximizes the efficiency of AI coding assistants (Claude/GPT).
• Performance: ProcessPoolExecutor bypasses the GIL, ensuring the main loop remains non-blocking for the 10k concurrent connections.
• Ecosystem: Access to superior Python-based libraries for potential future AI features (classification/extraction).

xxx