# DirektVermittlungDe Backend (Reference Implementation)

This repository contains a **FastAPI-based** reference implementation of the
DirektVermittlungDe (DVD) backend.

DVD provides **document-centric communication** between citizens and authorities:
citizens upload a letter or provide an *Aktenzeichen*, the system auto-routes it to
the responsible unit and opens an interaction thread for clarification instead of
a phone-based "Schnitzeljagd".

## Features

- **Document Intake (`POST /documents`)**
  - Split-payload model: plaintext metadata + encrypted payload.
  - Auto-routing to assigned unit.

- **Interaction Threads**
  - Create a thread per document (`/documents/{id}/threads`).
  - Citizen/official messages via `/threads/{threadId}/messages`.
  - Cursor-based pagination for message history.

- **Exports**
  - Async export workflow (`POST /exports`) with job IDs and status polling.

- **Security & NFR Alignment**
  - OAuth2 / JWT-based auth (scopes: `citizen:write`, `official:read`, `official:write`).
  - Document retention date for GDPR-friendly cleanup.
  - Architected for async I/O and offloading CPU-heavy work (hybrid concurrency).

## Quickstart

1. **Install dependencies**

   ```bash
   pip install -e .
   ```

2. **Run DB migrations (simple metadata create)**

   ```bash
   python -m app.scripts.init_db
   ```

3. **Run the API**

   ```bash
   uvicorn app.main:app --reload
   ```

4. **Open Swagger UI**

   Visit: `http://localhost:8000/docs`