ddd-architecture-python

Domain-Driven Design in Python

Match the project's existing domain model conventions. When uncertain, read 2-3 existing aggregate or entity modules to infer the local style. Check for existing base classes, event infrastructure, and repository patterns before introducing new ones. These defaults apply only when the project has no established convention.

Never rules

These are unconditional. They prevent structural defects regardless of project style.

• Never put business logic in service layers while domain models are empty data bags. This is the anemic domain model. If all methods live in services and entities are just data carriers, you have Transaction Scripts with extra mapping cost. Move behavior that enforces invariants into the entity or aggregate that owns the state.
• Never create repositories for anything other than aggregate roots. Repositories exist per aggregate root, not per entity. Accessing child entities bypassing the aggregate root breaks consistency boundaries. OrderLineRepository is always wrong if OrderLine belongs to an Order aggregate.
• Never use @dataclass(frozen=True) for entities. Frozen dataclasses enforce structural equality (compare all fields). Entities have identity -- two User objects with the same id are the same user even if email changed. Use @dataclass(eq=False, slots=True) and implement identity-based __eq__ and __hash__ on the id field.
• Never use unsafe_hash=True on mutable dataclasses. It makes mutable objects hashable, causing subtle bugs when attributes change after insertion into sets or dict keys. Use frozen for value objects, custom hash for entities.
• Never let domain models import from infrastructure. The dependency arrow points inward: infrastructure -> application -> domain. Domain models must not import SQLAlchemy, Pydantic, httpx, or any external framework.
• Never duplicate validation between API layer and domain layer. Pydantic validates input shape at the boundary (type coercion, required fields). Domain validates business invariants (order total can't be negative, user can't have more than 5 active subscriptions). These are different concerns.
• Never apply tactical DDD patterns to CRUD-only modules. If a bounded context has no business invariants beyond "save and retrieve," use plain service functions or direct ORM operations. Strategic DDD (bounded contexts, ubiquitous language) is almost always valuable; tactical DDD is conditional.