copilot-instructions clean-architecture.instructions.md

Clean Architecture Instructions

Overview

This instruction file enforces Clean Architecture principles in Python projects to ensure separation of concerns, testability, and maintainability.

Layer Structure

1. Domain Layer (Core/Entities)

• Contains business entities, value objects, and domain logic
• No dependencies on external frameworks or libraries (except standard library)
• Pure Python classes with business rules
• Located in: domain/ or core/

Example:

from dataclasses import dataclass
from typing import Optional
from datetime import datetime

@dataclass(frozen=True)
class OrderId:
    value: str

@dataclass
class Order:
    id: OrderId
    customer_id: str
    created_at: datetime
    total_amount: float

    def apply_discount(self, percentage: float) -> 'Order':
        """Business logic stays in the domain"""
        if not 0 <= percentage <= 100:
            raise ValueError("Invalid discount percentage")
        new_total = self.total_amount * (1 - percentage / 100)
        return Order(self.id, self.customer_id, self.created_at, new_total)

2. Application Layer (Use Cases)

• Contains application-specific business rules
• Orchestrates the flow of data between layers
• Uses interfaces/protocols for external dependencies
• Located in: application/ or use_cases/

Example:

from typing import Protocol
from domain.order import Order, OrderId

class OrderRepository(Protocol):
    def get_by_id(self, order_id: OrderId) -> Optional[Order]:
        ...

    def save(self, order: Order) -> None:
        ...

class ApplyDiscountUseCase:
    def __init__(self, order_repository: OrderRepository):
        self._repository = order_repository

    def execute(self, order_id: OrderId, discount: float) -> Order:
        order = self._repository.get_by_id(order_id)
        if not order:
            raise ValueError(f"Order {order_id.value} not found")

        discounted_order = order.apply_discount(discount)
        self._repository.save(discounted_order)
        return discounted_order