architecture

Instruction file imported from Banquished/FastAPI-service (.github/instructions/architecture.instructions.md). Copyright stays with the author.

Source Architecture

Preserve dependency direction:

HTTP entry points -> application services -> domain contracts
                                          <- repository and integration adapters

• HTTP handlers parse and validate transport input, invoke one use case, and map results to explicit response models.
• Services coordinate use cases, transaction completion, and domain interactions.
• Domain code expresses business behavior without importing FastAPI, SQLAlchemy, settings, environment access, or downstream payload models.
• Domain protocols describe capabilities needed by application behavior.
• Repositories implement persistence concerns and do not leak ORM objects across domain or HTTP boundaries.
• Integration adapters own downstream serialization, timeouts, retries, and error translation.
• src/core/ contains service-wide infrastructure, not feature-specific business behavior.

Prefer explicit typed contracts. Do not use broad exception catches, silent defaults, untyped dictionaries, or success-shaped fallbacks at boundaries. Translate expected failures at the owning boundary and preserve unexpected failures for safe centralized handling.

Keep application construction in create_app. Inject settings and infrastructure so tests do not depend on process-global state or live external systems.