init: documentation and prototypes

prototype-chatgpt5/IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,59 @@
+# Implementation Guide – DirektVermittlungDe (FastAPI)
+
+This guide explains how this codebase implements the architectural decisions
+and API specification of DirektVermittlungDe.
+
+## 1. Architecture Mapping
+
+- **Belegorientierung**: `Document` is the central aggregate.
+  - Domain models in `app/domain/models.py`
+  - ORM model in `app/adapters/orm.py::Document`
+- **Interaction Threads**: `Thread` and `Message` map to interaction threads and their logs.
+  - Cursor-based pagination implemented in `app/service/threads_service.py::list_messages`
+  - The `created_at` timestamp is used as the pagination cursor.
+
+- **Routing Engine**:
+  - Implemented as an adapter in `app/adapters/routing.py`
+  - Operates solely on `DocumentMetadata` (plaintext) as required by the split-payload model.
+
+- **Asynchronous Exports**:
+  - `POST /exports` → `start_export()` in `app/service/exports_service.py`
+  - Returns `202 Accepted` with `jobId` and uses a job registry (`app/adapters/jobs.py`)
+  - In a production system this would publish to Redis / RabbitMQ and be processed by workers.
+
+## 2. Security
+
+- **Auth**:
+  - OAuth2 / JWT is abstracted in `app/adapters/auth.py`.
+  - In this reference implementation, we parse unverified claims; in production, validate via JWKS.
+
+- **Data Protection**:
+  - Encrypted payloads are treated as opaque strings and stored via `app/adapters/storage.py`.
+  - Only routing metadata is stored in PostgreSQL for server-side logic.
+
+- **Retention**:
+  - Each `Document` gets a `retention_date`, set to a grace period in the future.
+  - Implement a periodic cleanup job that deletes rows where `retention_date < NOW()`.
+
+## 3. Performance / Hybrid Concurrency
+
+- All endpoints are `async def` and rely on the async SQLAlchemy engine.
+- CPU-heavy operations (PDF merge, crypto) must not be run inside the event loop.
+  - To extend this, create a `ProcessPoolExecutor` in `workers/` and call via `loop.run_in_executor`.
+
+## 4. Extending the System
+
+- **Real Routing Rules**:
+  - Add a `routing_rules` table and adapt `app/adapters/routing.py` to query it.
+- **Real Export Workers**:
+  - Replace `jobs.py` with a Redis-backed queue and a worker process in `workers/exports_worker.py`.
+- **Authority Integration**:
+  - Call the authority’s eAkte ingress API from the worker, using authority-specific keys.
+
+## 5. Definition of Done Checklist
+
+Before going to production:
+
+- Load-test `POST /documents` and `GET /threads/{id}/messages`.
+- Verify that logs never contain Aktenzeichen or other PII.
+- Verify that retention cleanup jobs work correctly on staging data.