Django Clean DRF Architect

Overview

This skill provides expert guidance for creating Django REST Framework applications following Clean Architecture principles. It enforces a strict layered architecture that separates concerns, maximizes testability, and produces maintainable production-quality code.

Architecture Layers:

HTTP Layer (Views/Serializers)
    ↓
Application Layer (Use Cases + DTOs)
    ↓
Domain Layer (Services + Models)
    ↓
Infrastructure Layer (ORM, External APIs, Cache)

Key Capabilities:

Layered architecture with strict dependency rules (dependencies flow inward only)
Use Case pattern with dataclass Input/Output DTOs
Service layer for domain logic (static queries, instance mutations)
Thin views that delegate to use cases
Separate Read vs Create/Update serializers
Explicit error handling without exceptions for business logic
Modern Python 3.12+ and Django 5+ features
Full type hints and testability by design

When to Use

Invoke this skill when you encounter these triggers:

New Application Setup:

"Create a new Django API for..."
"Start a new DRF project with clean architecture"
"Set up a new app with layered architecture"
"Initialize a domain-driven Django application"
"Scaffold a Django app following SOLID"

Use Case Implementation:

"Create a use case for..."
"Implement the business logic for..."
"Add a new operation/action for..."
"Handle this transaction atomically"

Service Layer:

"Create a service for..."
"Where should this business logic go?"
"Implement domain validation for..."
"Query data following clean architecture"

Architecture Questions:

"How do I structure this Django app?"
"What layer should handle..."
"How do I avoid fat views/models?"
"How do I make this testable?"
"Apply SOLID principles to Django"

API Design:

"Create API endpoints for..."
"Design the serializers for..."
"Implement CRUD for this entity"

Instructions

Follow this workflow when handling Django Clean DRF requests:

1. Analyze Requirements and Establish Context

Understand the domain:

What entities/models are involved?
What operations/actions are needed?
What business rules must be enforced?
Are there external dependencies (APIs, queues)?

Check existing project structure:

Review existing apps and their organization
Identify patterns already in use
Check Django/Python versions for feature availability

Determine scope:

Single use case or full CRUD?
New app or extending existing?
API-only or includes admin?

2. Load Relevant Reference Documentation

Based on the task, reference the appropriate bundled documentation:

Architecture:

New app setup → references/project-structure.md
Use case implementation → references/use-cases-pattern.md
Service layer → references/services-pattern.md
Models and domain logic → references/models-domain.md
Views and serializers → references/views-serializers.md
Testing → references/testing-clean-arch.md
Complete examples → references/examples.md

API Development:

Query optimization / N+1 → references/query-optimization.md
Pagination, filtering, search → references/api-patterns.md
Authentication / JWT / Permissions → references/authentication.md
Production deployment → references/production-api.md
Django Admin for APIs → references/django-admin.md

Code Quality:

Coding standards / Ruff / Security → references/coding-standards.md

3. Implement Following Clean Architecture Principles

CRITICAL: Layer Dependency Rules

Views → Use Cases → Services → Models
  ↓         ↓           ↓         ↓
Serializers  DTOs    (internal)   ORM

Dependencies flow INWARD only (outer layers depend on inner)
Never import views in use cases, or use cases in services

Use Case Pattern:

from dataclasses import dataclass
from uuid import UUID
from django.db import transaction

@dataclass(frozen=True, slots=True)
class CreateOrderInput:
    customer_id: UUID
    items: list['OrderItemInput']
    notes: str | None = None

@dataclass(frozen=True, slots=True)
class CreateOrderOutput:
    success: bool
    order_id: UUID | None = None
    error: str | None = None

class CreateOrderUseCase:
    def __init__(
        self,
        order_service: OrderService,
        inventory_service: InventoryService,
    ):
        self._order_service = order_service
        self._inventory_service = inventory_service

    @transaction.atomic
    def execute(self, input_dto: CreateOrderInput) -> CreateOrderOutput:
        # Validate
        is_valid, error = self._inventory_service.validate_availability(input_dto.items)
        if not is_valid:
            return CreateOrderOutput(success=False, error=error)

        # Execute
        order = self._order_service.create(
            customer_id=input_dto.customer_id,
            items=input_dto.items,
        )
        return CreateOrderOutput(success=True, order_id=order.id)

Service Pattern:

class OrderService:
    # STATIC methods for QUERIES (no state changes)
    @staticmethod
    def get_by_id(order_id: UUID) -> Order | None:
        return Order.objects.select_related('customer').filter(id=order_id).first()

    # INSTANCE methods for MUTATIONS (state changes)
    def create(self, customer_id: UUID, items: list[OrderItemInput]) -> Order:
        order = Order.objects.create(customer_id=customer_id)
        for item in items:
            OrderItem.objects.create(order=order, **item.__dict__)
        return order

    # VALIDATION returns tuple[bool, str]
    def validate_can_cancel(self, order: Order) -> tuple[bool, str]:
        if order.status == Order.Status.SHIPPED:
            return False, "Cannot cancel shipped orders"
        return True, ""

Thin View Pattern:

class CreateOrderView(APIView):
    permission_classes = [IsAuthenticated]

    def post(self, request: Request) -> Response:
        serializer = CreateOrderSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)

        use_case = CreateOrderUseCase(
            order_service=OrderService(),
            inventory_service=InventoryService(),
        )
        input_dto = CreateOrderInput(**serializer.validated_data)
        output = use_case.execute(input_dto)

        if not output.success:
            return Response({'error': output.error}, status=400)
        return Response({'order_id': str(output.order_id)}, status=201)

Serializer Separation:

# WRITE serializer (input validation)
class CreateOrderSerializer(serializers.Serializer):
    items = OrderItemInputSerializer(many=True, min_length=1)
    notes = serializers.CharField(max_length=500, required=False)

# READ serializer (output display)
class OrderReadSerializer(serializers.ModelSerializer):
    customer_name = serializers.CharField(source='customer.name', read_only=True)

    class Meta:
        model = Order
        fields = ['id', 'customer_name', 'status', 'created_at']
        read_only_fields = fields

Model with Domain Logic:

class Order(models.Model):
    class Status(models.TextChoices):
        PENDING = 'pending', 'Pending'
        CONFIRMED = 'confirmed', 'Confirmed'
        SHIPPED = 'shipped', 'Shipped'

    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    customer = models.ForeignKey('Customer', on_delete=models.PROTECT, related_name='orders')
    status = models.CharField(max_length=20, choices=Status.choices, default=Status.PENDING)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        ordering = ['-created_at']
        indexes = [models.Index(fields=['customer', 'status'])]

    @property
    def is_cancellable(self) -> bool:
        return self.status in (self.Status.PENDING, self.Status.CONFIRMED)

4. Validate and Finalize

Architecture Checklist:

Views are thin (< 20 lines of logic)
Use cases handle single operations
Services contain reusable domain logic
Dependencies flow inward only
No circular imports between layers

Code Quality Checklist:

Type hints on all public interfaces
Dataclass DTOs are frozen with slots
No exceptions for business logic errors → return Output
Validation returns tuple[bool, str]
@transaction.atomic wraps state changes

Performance Checklist:

select_related for ForeignKey access
prefetch_related for reverse relations
Indexes on frequently queried fields
No N+1 queries in serializers

Directory Structure

apps/<app_name>/
├── __init__.py
├── models.py              # Domain entities with @property logic
├── views.py               # Thin HTTP handlers
├── serializers.py         # Read and Write serializers
├── urls.py                # Route definitions
├── admin.py               # Django Admin
├── services/
│   ├── __init__.py        # Export services
│   └── <entity>_service.py
├── use_cases/
│   ├── __init__.py        # Export use cases
│   └── <action>_<entity>.py  # One file per use case
├── tests/
│   ├── __init__.py
│   ├── test_models.py
│   ├── test_services.py
│   ├── test_use_cases.py
│   ├── test_views.py
│   └── factories.py       # Factory Boy factories
└── migrations/

Bundled Resources

references/ - Comprehensive Clean Architecture and API documentation

Architecture Patterns

references/project-structure.md Directory layout, file naming, module organization, dependency rules
references/use-cases-pattern.md Input/Output DTOs, constructor injection, transaction handling, error handling
references/services-pattern.md Static vs instance methods, validation patterns, cross-service communication
references/models-domain.md Domain logic in models, TextChoices, UUID keys, indexes
references/views-serializers.md Thin views, permissions, Read vs Write serializers
references/testing-clean-arch.md Unit testing use cases, mocking services, integration tests
references/examples.md Complete CRUD example, complex workflows, testing examples

API Best Practices

references/query-optimization.md N+1 queries, select_related/prefetch_related, indexes, bulk operations, aggregations
references/api-patterns.md Pagination, filtering, searching, ordering, API versioning, error handling, throttling
references/authentication.md JWT authentication, permissions, API keys, role-based access, security headers
references/production-api.md Settings structure, database config, caching, logging, Sentry, health checks, Docker
references/django-admin.md ModelAdmin configuration, inlines, custom actions, query optimization, permissions, security

Code Quality

references/coding-standards.md Ruff configuration, import ordering, security practices, YAGNI, logging, documentation

Core Principles

No Exceptions for Business Logic

# BAD
def create_order(self, data):
    if not self.can_create():
        raise ValidationError("Cannot create order")
    return Order.objects.create(**data)

# GOOD
def create_order(self, data) -> CreateOrderOutput:
    if not self.can_create():
        return CreateOrderOutput(success=False, error="Cannot create order")
    order = Order.objects.create(**data)
    return CreateOrderOutput(success=True, order_id=order.id)

Validation Returns Tuples

# BAD
def validate(self, order) -> bool:
    return order.status != 'shipped'

# GOOD
def validate(self, order) -> tuple[bool, str]:
    if order.status == 'shipped':
        return False, "Cannot modify shipped orders"
    return True, ""

Constructor Injection for Testability

# BAD - Hard to test
class CreateOrderUseCase:
    def execute(self, input_dto):
        service = OrderService()  # Hardcoded dependency
        return service.create(input_dto)

# GOOD - Easy to mock
class CreateOrderUseCase:
    def __init__(self, order_service: OrderService):
        self._order_service = order_service

    def execute(self, input_dto):
        return self._order_service.create(input_dto)

Additional Notes

Python Version: 3.10+ required (for X | None union syntax), 3.12+ recommended Django Version: 4.2 LTS minimum, 5.0+ recommended

Naming Conventions:

Use cases: <action>_<entity>.py (e.g., create_order.py)
Services: <entity>_service.py (e.g., order_service.py)
Serializers: <Entity>ReadSerializer, <Entity>CreateSerializer

Integration with Other Skills:

Use django-celery-expert for background tasks
Use refactordjango to migrate existing code to this architecture

django-clean-drf