init: documentation and prototypes

prototype-chatgpt5/README.md

@@ -0,0 +1,52 @@
+# 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`