Django Drf Layered Architecture

Django + DRF layered architecture

Portable rules distilled from Lumi ERP / Omayka backends. Apply to new and existing Django+DRF projects unless the repo explicitly overrides them.

Layer dependency (strict)

HTTP → views (DRF) → serializers (I/O edge)
                  → services (use cases)
                  → dtos (typed contracts)
                  → models (ORM)
                  → adapters/* (external I/O: HTTP, browser, LLM, files)

Services receive and return DTOs, not request and ideally not raw models at the public method boundary (map model → DTO inside the service).

A service may call another service in the same app. Never import views from services. Cross-app: prefer DTOs, service APIs, or domain events — avoid importing another app's models for writes when a service exists.

API versioning

• Expose new endpoints only under /api/v1/... (or the project's current version prefix).
• Do not add new clients to unversioned /api/... routes.

App layout (per module)

apps/<module>/
  models.py
  dtos.py
  services.py
  serializers.py
  views.py
  urls.py
  apps.py
  tests/
adapters/                 # optional package at backend root
  <system>/               # e.g. lumi/, llm/, payments/

Shared bits: apps/common/ (BaseDTO, exceptions, EventBus helpers).

DTO patterns

from dataclasses import dataclass
from apps.common.dtos import BaseDTO

@dataclass
class CreateAgentDTO(BaseDTO):
    name: str
    role: str

@dataclass
class AgentDTO(BaseDTO):
    id: str
    name: str
    role: str

• Serializers validate input → build DTO → Service().method(dto) → serialize DTO/dict out.
• Type-hint service public methods.

View pattern (thin)

class AgentViewSet(viewsets.ViewSet):
    def create(self, request):
        ser = CreateAgentSerializer(data=request.data)
        ser.is_valid(raise_exception=True)
        dto = CreateAgentDTO(**ser.validated_data)
        result = AgentService().create(dto)
        return Response(AgentSerializer(result).data, status=201)

Service pattern

class AgentService:
    @transaction.atomic
    def create(self, dto: CreateAgentDTO) -> AgentDTO:
        # validate + persist + map to AgentDTO
        ...

Adapters (external edges)

• Browser automation, third-party HTTP, LLM, filesystem: live under adapters/.
• Services call adapters with DTOs; adapters return DTOs (SkillResultDTO, etc.).
• Keep selectors, SDK clients, and retries inside the adapter.

Multi-tenancy (optional)

• If the project uses schema-per-tenant (django-tenants): never cross schemas; scope queries to active tenant.
• If not multi-tenant (e.g. OrbitQA MVP): still keep services/DTO boundaries; omit tenant_id from DTOs unless needed later.

Models checklist

• Prefer UUID PKs on new business models.
• created_at / updated_at on business entities.
• Never delete old migrations; add new ones.
• List endpoints: select_related / prefetch_related; avoid per-row DB in SerializerMethodField (batch via serializer context).

Tests

• Prefer pytest + pytest-django.
• Test behaviors via services (and API smoke), not private helpers only.
• Mock adapters / external I/O in unit tests.

Anti-patterns

• Fat perform_create with business rules.
• Serializers that call Model.objects.create with domain branching.
• Services that import rest_framework request objects.
• Views that launch Playwright or call OpenAI directly.
• Cross-app model imports for writes when a service exists.
• Unversioned new API routes.

Checklist (new endpoint)

• URL under /api/v1/
• Serializer validates only
• DTO defined
• Service method with types + transaction if needed
• View thin
• External I/O behind adapter
• Tests for happy path + main validation error

More

• Concrete snippets: examples.md