direkt-vermittlung-de/prototype-chatgpt5/IMPLEMENTATION_GUIDE.md

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.