55 lines
2.0 KiB
Markdown
55 lines
2.0 KiB
Markdown
# 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
|
|
|
|
```
|
|
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:
|
|
|
|
```
|
|
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 |
|