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