direkt-vermittlung-de/docs/251201-architektur-direktVermittlungDe.txt

DvdArchitektur

Architektur Dokument für Direkt Vermittlung Deutschland

# Direkt Vermittlung Deutschland Architektur

## 1. Functional Requirements

**Description: Core features and user stories**

### 1.1 Kernfunktionen (auf Beleg fokussiert)

**FR-1 – Schreiben erfassen (Document Intake)**

* Bürger:innen können ein behördliches Schreiben als PDF hochladen oder via Kamera erfassen.
* Alternativ: Eingabe eines eindeutigen Merkmals (z. B. Aktenzeichen/Kassenzeichen + Behörde).
* Das System erzeugt einen **DocumentEnvelope** inkl. Metadaten (Aktenzeichen, Belegart, Datum, Absenderbehörde).

**FR-2 – Automatisches Routing zur zuständigen Stelle**

* Die Plattform verfügt über eine **Routing-Engine**, die anhand von Metadaten & Konfiguration

  * die zuständige Behörde / Organisationseinheit
  * und idealerweise den zuständigen Sachbearbeiter ermittelt.
* Fallback-Regeln (z. B. Standard-Team, Zentrale) greifen, wenn keine eindeutige Zuordnung möglich ist.

**FR-3 – Interaktionsstart zum Schreiben (Interaction Thread)**

* Bürger:innen können zu einem bestimmten Schreiben:

  * eine Rückfrage stellen (Textnachricht),
  * einen Rückruf anfragen,
  * einen Direktanruf starten (sofern verfügbar),
  * einen Terminwunsch äußern.
* Für jede solche Interaktion wird ein **InteractionThread** zum **DocumentEnvelope** angelegt.

**FR-4 – Kommunikation & Dokumentaustausch**

* Bürger und Behörde können in einem Thread:

  * Nachrichten austauschen,
  * ergänzende Belege hochladen (z. B. Nachweise, Antworten),
  * interne Notizen (behördenintern, nicht für Bürger sichtbar) anlegen.
* Alle Aktivitäten werden chronologisch protokolliert.

**FR-5 – Call-/Rückruf-/Termin-Orchestrierung**

* Das System unterstützt:

  * Weitervermittlung bei eingehenden Anrufen anhand eines Merkmals,
  * Anlegen & Verwalten von Rückrufanforderungen,
  * optionale Terminvereinbarung (Kalenderintegration der Behörde).

**FR-6 – Temporäre Vorhaltung & persönliche Ablage**

* Standard: Daten (Schreiben, Threads, Dateien) werden nur bis zur Erledigung + definierter Inaktivitätsfrist gehalten und dann gelöscht.
* Bürger und Behörde können optional eine **verlängerte Aufbewahrung** (persönliche Ablage) buchen/aktivieren.

**FR-7 – Datenexport an Behördensysteme**

* Behörden können Daten eines Vorgangs (Schreiben, Metadaten, Interaktionshistorie, Anhänge)

  * in ihre eAkte / Fachverfahren exportieren (pull oder push).
* Der Export ist konfigurierbar (welche Daten, welches Format).

---

### 1.2 User Stories (Beispiele)

* *Als Bürger* möchte ich ein behördliches Schreiben scannen oder hochladen können,
  damit ich ohne manuelle Zuständigkeitsrecherche direkt den richtigen Ansprechpartner erreiche.

* *Als Sachbearbeiterin* möchte ich alle offenen Vorgänge zu den Schreiben meiner Behörde in einer Liste sehen,
  damit ich Rückfragen gezielt bearbeiten und priorisieren kann.

* *Als Behördenadministrator* möchte ich Routingregeln konfigurieren (z. B. nach Aktenzeichenbereichen),
  damit Anfragen automatisiert der richtigen Organisationseinheit zugeordnet werden.

* *Als Bürger* möchte ich optional eine längerfristige digitale Ablage wichtiger Schreiben und Klärungsverläufe,
  damit ich später auf diese Informationen zugreifen kann.

**Why It Matters:**
Diese Functional Requirements definieren klar, **was** DVD tut:

* Sie trennen sauber zwischen “Beleg”, “Interaktion” und “Routing” → gute Grundlage für REST-/API-Design.
* Sie machen DVD bewusst **beleggesteuert** (nicht generische Kommunikation) und ermöglichen spätere Erweiterungen (z. B. KI-Extraktion, andere Kanäle), ohne das Kernmodell zu brechen.

---

## 2. Non-Functional Requirements

**Description: Performance, security, usability SLAs**

### 2.1 Performance & Skalierung

* **NFR-1:** 95. Perzentil der Antwortzeiten für Kernoperationen (Thread öffnen, Nachricht senden, Routing) < 300 ms bei normaler Last.
* **NFR-2:** System unterstützt mindestens **10k gleichzeitige Sessions** (Behörden + Bürger) pro Region.
* **NFR-3:** Routingentscheidungen werden in < 500 ms getroffen (inkl. Lookups).

### 2.2 Sicherheit & Datenschutz

* **NFR-4:** Vollständige **DSGVO-Konformität**, inkl.

  * Recht auf Auskunft, Löschung, Berichtigung,
  * dokumentierte Retentions-Policies,
  * Privacy-by-Design & by-Default.
* **NFR-5:** End-to-End-Verschlüsselung in Transport (TLS 1.2+) und Verschlüsselung sensibler Daten im Ruhezustand (z. B. Aktenzeichen, PDF-Dokumente).
* **NFR-6:** Zugriff nur auf Basis rollenspezifischer Berechtigungen (least privilege, mandantensicher).

### 2.3 Verfügbarkeit & Resilienz

* **NFR-7:** Zielverfügbarkeit: ≥ 99,5 % im Jahresmittel.
* **NFR-8:** Disaster-Recovery-Konzept mit RPO ≤ 15 min, RTO ≤ 4 h.

### 2.4 Usability

* **NFR-9:** Bürgeroberfläche barrierearm nach WCAG 2.1 AA-Orientierung.
* **NFR-10:** Max. 3 Schritte vom Start bis zur gestellten Anfrage.

**Why:**
Diese NFRs treiben Architekturentscheidungen:

* Asynchrone Verarbeitung, Caching & horizontale Skalierung werden notwendig.
* Strikte IAM- & Verschlüsselungsschichten sind Pflicht in GovTech-Umgebungen.
* Klare SLAs verhindern, dass “Prototyping-Architektur” im Produktivbetrieb kollabiert.

---

## 3. Business Context

**Description: Use cases, target audience, integrations**

### 3.1 Use Cases (Business-Sicht)

* Reduktion der durchschnittlichen **Telefonzeit pro Klärung** (z. B. von 30 auf 10 Minuten).
* Entlastung von Telefonzentralen, Bündelung der Klärung direkt bei den Fachbereichen.
* Schaffung eines digitalen Rückkanals zu behördlichen Schreiben, der nachvollziehbar und sicher ist.

### 3.2 Zielgruppen

* **Primäre Business-Kunden:**

  * Kommunalverwaltungen, Gerichtskassen, Amtsgerichte, Landesbehörden, Finanzämter.
* **Endnutzer:innen:**

  * Bürger:innen (Privatpersonen, Unternehmen) mit Bescheiden / Schreiben.
* **Sekundäre Stakeholder:**

  * Kommunale/regionale IT-Dienstleister, Fachverfahrenshersteller.

### 3.3 Integrationskontext

* eAkte-Systeme der Behörden (unterstützt durch generische Exporte und custom Adapter).
* Identity-Provider (z. B. BundID, eID, SAML/OIDC-basierte Behörden-Singlesignon).
* TK-Anlagen / Callcenter-Software (für Direktvermittlung, Rückruflisten).
* Optional: Dokumentenmanagement / Archivsysteme.

**Why:**
Der Business-Kontext sorgt dafür, dass du die “Nomen” des Systems (DocumentEnvelope, InteractionThread, AuthorityUnit) passend zu realen Strukturen modellierst. Er verhindert, dass du eine “abstrakte Messaging-Plattform” baust, statt eines **belegzentrierten GovTech-Dienstes**.

---

## 4. Technical Constraints

**Description: Existing systems, tech stack, and standards**

*(Hier formuliere ich bewusst Vorschläge, die du später bestätigen/ändern kannst.)*

### 4.1 Architekturparadigmen

* **TC-1:** Service-orientierte / modularisierte Architektur mit klaren Bounded Contexts:

  * Citizen & Channels,
  * Document & Interaction,
  * Routing & Org,
  * Integration & Export.
* **TC-2:** Stateless APIs im Frontend-Layer, Session-Handling via Token (JWT/OAuth2), um horizontale Skalierung zu ermöglichen.

### 4.2 Tech Stack (Vorschlag / Beispiel)

* **Backend:** z. B. Java (Spring Boot) oder Go (stark in Gov-Umfeldern verbreitet), Node.js denkbar – Standard: REST-APIs, optional GraphQL.
* **Datenbank:** Relationale DB (PostgreSQL) für Kernobjekte; Blob-Storage (z. B. S3-kompatibel) für PDF-Dokumente.
* **Caching:** Redis für Sessions, Routing-Cache und häufige Lookups.
* **Messaging:** Optionale Message-Bus/Queue (z. B. Kafka/RabbitMQ) für Export-Jobs, Notifications.

### 4.3 Standards & Schnittstellen

* **TC-3:** REST/JSON-APIs als Primärschnittstelle; sprechende Ressourcen (z. B. `/documents`, `/threads`, `/exports`).
* **TC-4:** HTTPS/TLS verpflichtend, HSTS aktiviert.
* **TC-5:** OpenAPI-Spezifikation für alle externen APIs (für Behörden & Integrationspartner).

**Why:**
Diese Constraints helfen, früh falsche Technologieentscheidungen auszuschließen und das System **von Anfang an auf Skalierbarkeit & Interoperabilität** auszurichten. OpenAPI-First erleichtert LLM-gestützte Codegenerierung und Mock-APIs.

---

## 5. Stakeholder Feedback

**Description: Early input from consumers (e.g., devs using the API)**

### 5.1 Stakeholder-Gruppen für Feedback

* **Behörden-Fachseite:** Sachbearbeiter:innen und Fachbereichsleitungen

  * Fokus: Usability, Prozesslogik, Zuständigkeitsmodell.
* **Behörden-IT:** Architekt:innen, Admins, Datenschutzbeauftragte

  * Fokus: Integrationsfähigkeit, Sicherheit, Betriebsmodell.
* **Bürgerperspektive:** Pilot-Testgruppen

  * Fokus: Verständlichkeit, Barrierefreiheit, Friktion beim Einstieg (Schreiben hochladen, Merkmal finden etc.).

### 5.2 Feedback-Mechanismen

* Interaktive Mock-UIs / klickbare Prototypen (z. B. Figma) zur frühen Usability-Validierung.
* **Mock-APIs** (z. B. via Postman, Insomnia oder Swagger-UI) zur API-Validierung mit Behördensystemen.
* Kurze Surveys oder Interviews (z. B. „Was ist für Sie das größte Problem bei Rückfragen zu Schreiben?“).

### 5.3 Iterationsschleifen

* Frühzeitige “Pilot-Phase” mit einer kleinen Behörde/Abteilung, bevor generisch ausgebaut wird.
* Veränderungswünsche in **Versionierte API-Designs** überführen (z. B. v1 → v1.1), kein “API-Chaos”.

**Why:**
Stakeholder-Feedback verhindert, dass du an den eigentlichen Bedürfnissen vorbeientwickelst (z. B. zu komplizierte Ablaufsteuerung). Es ist essentiell für **cleanes, *wirklich* extensibles Design**, insbesondere, weil Behörden-IT traditionell komplexe und gewachsene Umfelder hat.

---

## 6. Existing Assets

**Description: Legacy docs, wireframes, or code snippets**

Im Moment sind das bei DVD überwiegend **noch zu definierende** Assets – aber hier ist, was du konkret sammeln/erstellen solltest (und wie es der Architektur hilft):

### 6.1 Fachliche Assets

* Beispiel-Briefe aus verschiedenen Behörden (gerichtliche Schreiben, Gebührenbescheide, Steuerbescheide etc.)

  * inkl. Struktur der Aktenzeichen/Kassenzeichen (Masken, Beispiele).
* Prozessbeschreibungen, wie Rückfragen heute laufen (IST-Prozess) – z. B. BPMN oder einfache Swimlane-Diagramme.

### 6.2 Modell- & Design-Assets

* Erste **Domänenmodelle / UML-Klassendiagramme** für:

  * `DocumentEnvelope`, `InteractionThread`, `RoutingRule`, `AuthorityUnit`, `User`.
* Wireframes/Mockups für:

  * Bürger-Oberfläche (Schreiben hochladen, Anfrage stellen),
  * Sachbearbeiter-Oberfläche (Postkorb, Vorgänge, Antworten).

### 6.3 Technische Assets

* Beispiel-JSON-Payloads für zentrale API-Objekte, z. B.:

```json
{
  "documentId": "doc-123",
  "organisationId": "court-xyz",
  "caseNumber": "12 C 345/25",
  "documentType": "PaymentNotice",
  "issuedAt": "2025-12-01",
  "citizenHint": "Bitte geben Sie dieses Aktenzeichen bei Rückfragen an."
}
```

```json
{
  "threadId": "thr-789",
  "documentId": "doc-123",
  "messages": [
    {
      "messageId": "msg-1",
      "from": "citizen",
      "content": "Ich habe eine Frage zur Zahlungsfrist.",
      "createdAt": "2025-12-02T09:15:00Z"
    }
  ]
}
```

**Why:**
Diese Assets sind Gold für:

* spätere LLM-Unterstützung (z. B. “Generiere Routing-Regeln basierend auf diesen Beispielbriefen”),
* Reduktion von Missverständnissen bei Domainmodell & API-Design,
* schnellere Implementierung, weil Entwickler konkrete Fälle sehen.

---