copilot-instructions domain-driven-design.instructions.md

Domain-Driven Design Instructions

Overview

This instruction file enforces Domain-Driven Design (DDD) tactical patterns in Python projects.

Building Blocks

1. Entities

Objects with a distinct identity that persists over time.

from dataclasses import dataclass
from typing import List
from uuid import UUID, uuid4

@dataclass
class Customer:
    id: UUID
    email: str
    name: str
    _version: int = 0

    @classmethod
    def create(cls, email: str, name: str) -> 'Customer':
        """Factory method for entity creation"""
        return cls(id=uuid4(), email=email, name=name)

    def change_email(self, new_email: str) -> None:
        """Domain behavior"""
        if '@' not in new_email:
            raise ValueError("Invalid email format")
        self.email = new_email
        self._version += 1

2. Value Objects

Immutable objects defined by their attributes, not identity.

from dataclasses import dataclass
from typing import Self

@dataclass(frozen=True)
class Money:
    amount: float
    currency: str

    def __post_init__(self):
        if self.amount < 0:
            raise ValueError("Amount cannot be negative")
        if not self.currency:
            raise ValueError("Currency is required")

    def add(self, other: 'Money') -> 'Money':
        if self.currency != other.currency:
            raise ValueError("Cannot add different currencies")
        return Money(self.amount + other.amount, self.currency)

    def multiply(self, factor: float) -> 'Money':
        return Money(self.amount * factor, self.currency)

3. Aggregates

A cluster of entities and value objects with a root entity.

from dataclasses import dataclass, field
from typing import List
from datetime import datetime

@dataclass
class OrderItem:
    product_id: str
    quantity: int
    price: Money

@dataclass
class Order:
    """Aggregate Root"""
    id: UUID
    customer_id: UUID
    items: List[OrderItem] = field(default_factory=list)
    status: str = "PENDING"
    created_at: datetime = field(default_factory=datetime.utcnow)

    def add_item(self, product_id: str, quantity: int, price: Money) -> None:
        """Business invariant: can't modify confirmed orders"""
        if self.status != "PENDING":
            raise ValueError("Cannot modify confirmed order")

        # Check if item exists, update quantity
        for item in self.items:
            if item.product_id == product_id:
                item.quantity += quantity
                return

        self.items.append(OrderItem(product_id, quantity, price))

    def confirm(self) -> None:
        """State transition with validation"""
        if not self.items:
            raise ValueError("Cannot confirm empty order")
        if self.status != "PENDING":
            raise ValueError("Order already confirmed")
        self.status = "CONFIRMED"

    def calculate_total(self) -> Money:
        """Aggregate consistency"""
        if not self.items:
            return Money(0, "USD")

        total = self.items[0].price.multiply(self.items[0].quantity)
        for item in self.items[1:]:
            total = total.add(item.price.multiply(item.quantity))
        return total