django

django

Core Django backend patterns for project organisation, model abstractions, DRF conventions, ORM optimisation, middleware, and testing. Applies identically across single-tenant and multi-tenant projects; specialised concerns (Channels, Celery, multi-tenancy, i18n) live in references/.

Pairs with: django-frontend for HTMX / Alpine / Bulma template patterns. Load both on full-stack feature work (e.g. a view that returns an HTMX partial on HX-Request).

When to use

TRIGGER when: editing a Django project (manage.py, models.py, views.py, serializers.py, admin.py, migrations/); adding a DRF endpoint, viewset, or permission; touching BaseModel / mixins / middleware; running makemessages; debugging N+1 or query-count issues.

SKIP for: template-only work (use django-frontend); pure-frontend JS; non-Django Python projects (FastAPI / Flask / Starlette have different idioms); DevOps without code (use deployment).

Pattern

Project structure

Infrastructure at repo root, Django code under web/:

git_repo_root/
├── docker-compose.yml         # Infrastructure
├── Dockerfile
├── nginx/
├── docs/
├── tools/
└── web/                       # ← All Django code here
    ├── manage.py
    ├── requirements.txt
    ├── .env.example
    ├── project/               # settings.py, urls.py, asgi.py
    ├── core/                  # BaseModel, mixins, permissions, middleware
    ├── auth/
    ├── api/
    └── [feature]/

Why web/: clean separation of infra vs. app code. Docker's web service mounts web/ to /app in the container, keeping Django self-contained and infra isolated from the Python path.

Type hints and docstrings

Mandatory on all function signatures and classes. Explicit arg/return types (def process(data: dict) -> bool:) and a descriptive docstring per class / function / method.

BaseModel abstraction

Reduce duplication with an abstract base: