copilot-instructions: Instructions file for GitHub Copilot

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