# 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.