Skip to content

Overview

Summary

The blueprint is a hexagonal (ports and adapters) application with a spec-first web edge and a single composition root. It favors explicit wiring over implicit magic, and it prefers existing internal libraries over hand-written infrastructure.

The three layers

1
2
3
interfaces/   ← HTTP edge: thin handlers bound to an OpenAPI operationId
domain/       ← business core: models, ports (interfaces), services, orchestrators
infra/        ← adapters: databases, caches, external clients, hardware

Plus two optional layers:

1
2
pipelines/    ← data-driven transformation graphs (extraction, enrichment)
scripts/      ← operator scripts that reuse the composition root

Core principles

  1. One-way dependencies. interfaces -> domain -> infra is allowed; the reverse is forbidden. The domain never imports a framework it does not own.
  2. Ports in the domain, adapters in infra. A service depends on an abstract port; the composition root injects a concrete adapter.
  3. One composition root. Nothing constructs its own dependencies. All wiring lives in one module (init.py) and is exposed as a flat resource registry.
  4. Spec-first. The HTTP contract is declared in an OpenAPI document. Route handlers are looked up by operationId. There are no decorator routers.
  5. Reuse the libraries. Pipeline orchestration, DI, Mongo repositories, ingestion, auth, and docs are provided by internal libraries. Do not reimplement them — see the library registry.
  6. Explicit state machines. Long-running work moves through explicit, durable statuses and can pause for human input.

Runtime processes

A standard app may run as up to three processes that share the same composition root:

Process Entry point Responsibility
API main.py serve HTTP; start/stop resources via lifespan
Worker worker.py poll durable jobs, run pipelines, publish progress
Scripts python -m scripts.<name> one-shot operator tasks