master/docs/001-composition-root-and-lifetimes.md

001 Composition Root and Lifetimes

Context

• The template must initialize repository and usecase objects once and reuse them across requests.
• FastAPI integration must not leak framework concerns into inner layers.

Decision

• Keep a single composition root in adapter/di/container.py.
• Build repositories, usecases, config, and observability adapters during application startup.
• Store the container in application state and expose instances through thin HTTP dependencies.
• Do not create repository or usecase objects per request.

Consequences

• Object lifetimes stay explicit and testable.
• Replacing the web framework affects only the HTTP adapter layer.
• Startup failures surface early instead of during request handling.