Skip to content

Layering Rules

Summary

The dependency direction is fixed. Violating it is a design defect.

Allowed imports

1
2
3
4
5
6
interfaces/*      ->  domain/*            (services, ports, models)
interfaces/*      ->  infra/adapters/*    (only read-only value objects)
domain/*          ->  domain/*            (same layer)
domain/*          ->  pipelines/*         (call a pipeline via a port)
infra/adapters/*  ->  domain/ports/*      (implement the interface)
main.py/init.py   ->  everything          (composition root only)

Forbidden imports

1
2
3
4
domain/*          ->  interfaces/*        (never)
domain/*          ->  fastapi/starlette   (never)
infra/adapters/*  ->  interfaces/*        (never)
interfaces/*      ->  infra/db/*          (state lives in resources, not imports)

Why

  • A pure domain is testable without a server, a database, or an event loop.
  • Adapters can be swapped (in-memory fake, real database) without touching business logic.
  • The HTTP edge stays thin and replaceable.

The port/adapter contract

A port is an abstract class or protocol declared in domain/<x>/ports/. An adapter implements it in infra/adapters/. The composition root binds the two.

1
2
3
4
domain/<resource>/ports/db.py       -> repository port + document model
domain/<resource>/ports/service.py  -> service + factory
infra/db/repos/<vendor>.py          -> repository adapter factory
infra/adapters/service.py           -> generic CRUD service base

Enforcement

  • Keep every domain module importable with only the standard library and Pydantic. If a domain import pulls in fastapi, the layering is broken.
  • Reviewers (and CI) reject import fastapi inside domain/ or infra/.