DDD Concepts to attack-on-domain¶

This page maps standard Domain-Driven Design concepts to their implementation in attack-on-domain.

Core Building Blocks¶

Entity¶

DDD: Mutable object with a unique identity that persists over time. Two entities with the same attributes are different if they have different identities.

AoD: Entity and RootEntity with automatic mutation guards.

class User(Entity):
    id: str
    name: str

    def rename(self, new_name: str) -> None:
        self.name = new_name

Value Object¶

DDD: Immutable object defined by its attributes, not its identity. Two VOs with the same values are interchangeable.

AoD: ValueObject — always immutable, compared by value.

class Money(ValueObject):
    amount: float
    currency: str

Aggregate / Aggregate Root¶

DDD: A cluster of domain objects treated as a single unit. The aggregate root is the only entry point; external objects reference it by ID, never by object reference.

AoD: RootEntity marks the aggregate root. BoundedContext enforces nesting rules — RootEntity cannot be nested inside other entities.

class OrderLine(Entity):
    product_id: str
    quantity: int

class Order(RootEntity):
    id: str
    lines: list[OrderLine]

    def add_line(self, product_id: str, quantity: int) -> None:
        self.lines.append(OrderLine(product_id=product_id, quantity=quantity))

Domain Event¶

DDD: A record of something significant that happened in the domain. Events are immutable and timestamped.

AoD: Event — immutable, auto-timestamped with emitted_at. Emitted via _event_emitter on any domain object.

class OrderPlaced(Event):
    order_id: str
    total: float

class Order(RootEntity):
    id: str
    total: float

    def place(self) -> None:
        self._event_emitter.emit(OrderPlaced(order_id=self.id, total=self.total))

Domain Service¶

DDD: A stateless operation that does not naturally belong to an entity or value object. Often orchestrates multiple aggregates.

AoD: Service — stateless, with event emission and field mutation inside methods.

class PricingService(Service):
    def calculate_total(self, items: list[OrderItem], tax_rate: float) -> float:
        subtotal = sum(item.price * item.quantity for item in items)
        return subtotal * (1 + tax_rate)

Domain Invariant¶

DDD: A business rule that must always be true. Enforced at construction time or on state change.

AoD: @field_invariance (field-level) and @invariance (model-level). Violations raise InvarianceException.

class Money(ValueObject):
    amount: float
    currency: str

    @field_invariance("amount")
    def amount_must_be_positive(cls, v: float) -> float:
        if v < 0:
            raise ValueError("Amount must be positive")
        return v

Bounded Context¶

DDD: A boundary within which a particular domain model is defined and consistent. Each context has its own ubiquitous language.

AoD: BoundedContext groups RootEntity classes and Service classes, discovers child types automatically, and enforces DDD constraints.

product_context = BoundedContext(aggregate_roots=[Product], name="products")
order_context = BoundedContext(aggregate_roots=[Order], name="orders")
app = App("ecommerce", product_context, order_context)

Application Layer¶

Command / Query¶

DDD: Commands express intent to change state; Queries express intent to read state. Both are immutable.

AoD: Command[TEntity, TResult] and Query[TEntity, TResult] with type-validated generic parameters.

class CreateUser(Command[User, None]):
    user_id: str
    name: str
    email: str

class GetUser(Query[User, User | None]):
    user_id: str

Use Case (Application Service)¶

DDD: Orchestrates domain objects to fulfill a user goal. Coordinates domain logic, transactions, and infrastructure.

AoD: UseCase with auto-wired dependencies, internal transaction management, event collection, logging, and cache invalidation via handler.add_cache() with CacheKey/CacheInvalidation.

class CreateUserUseCase(UseCase):
    save_user: CommandPort[CreateUser]

    def run(self, user_id: str, name: str, email: str) -> None:
        user = User(id=user_id, name=name, email=email)
        self.save_user.handle(CreateUser(user_id=user_id, name=name, email=email))

Repository (Data Access)¶

DDD: Mediates between the domain and data mapping layers. Provides collection-like access to aggregates.

AoD: No Repository class. Use CommandHandler[C] and QueryHandler[Q] instead. UseCases depend on CommandPort[T] / QueryPort[T], never on repositories.

class SaveUserHandler(CommandHandler[CreateUser]):
    session: SqlSession

    def handle(self, command: CreateUser) -> None:
        user = User(id=command.user_id, name=command.name, email=command.email)
        self.session.execute(user)

Ports and Adapters (Hexagonal Architecture)¶

DDD: Ports define interfaces; adapters provide implementations. The core depends on ports, not adapters.

AoD: The framework is built on ports and adapters: Port base class, CommandPort/QueryPort for handlers, and built-in ports for cross-cutting concerns.

Mapping Summary¶

Next Steps¶