DEV Community: Alanso Mathew

Understanding Django Models and ORM: A Complete Production Guide

Alanso Mathew — Mon, 30 Mar 2026 03:47:08 +0000

A deep dive into Django's most powerful abstraction — from field types and relationships to QuerySet internals, F expressions, annotations, and production-scale optimization strategies.

Orginally Posted at:https://alansomathewdev.blogspot.com/2026/03/understanding-django-models-and-orm.html

Introduction
Why This Matters in Production Systems
Core Concepts
Architecture Design
Step-by-Step Implementation
Code Examples
Performance Optimization
Security Best Practices
Common Developer Mistakes
Real Production Use Cases
Conclusion

Introduction

The Django ORM is arguably the most consequential tool in a Django developer's kit. It is the bridge between your Python objects and your relational database — a translation layer that converts method chains into SQL, relationship declarations into JOIN clauses, and Python exceptions into database constraint violations.

At its surface, the ORM looks deceptively simple. You define a class, declare some fields, and Django creates the database table. You call Model.objects.filter() and get objects back. No SQL required. Get in, get out.

But this simplicity is a trap for the unprepared. The Django ORM is an aggressively lazy system — it defers database execution until the last possible moment, builds query plans in memory before touching the database, and exposes a rich expression language that, when understood, allows you to push complex business logic down into the database where it belongs. When misunderstood, it generates dozens or hundreds of redundant queries per request, loads entire tables into memory, and creates performance characteristics that deteriorate non-linearly as data grows.

This guide covers the Django ORM from the ground up. We'll trace a QuerySet from Python method call to SQL execution, cover every production-critical API, demonstrate real-world patterns for models, managers, custom QuerySets, F expressions, annotations, and aggregations, and give you the optimization and security vocabulary to write database code that holds up at scale.

Whether you're three months into Django or three years, there is something here that will change how you write database queries.

Why This Matters in Production Systems

The performance characteristics of your Django ORM usage are not a theoretical concern. They are the single most common source of production performance degradation in Django applications.

Consider a simple e-commerce endpoint that lists orders and their items. An inexperienced developer writes:

orders = Order.objects.filter(user=request.user)
for order in orders:
    for item in order.items.all():  # ← query per order
        print(item.product.name)    # ← query per item

On a user with 50 orders averaging 5 items each, this generates 1 + 50 + 250 = 301 database queries for a single page load. With 100 concurrent users doing this, you have 30,100 queries per second. Your database collapses. Your response times balloon. Your infrastructure bill spikes.

The correct implementation uses prefetch_related and generates exactly 3 queries — regardless of how many orders or items exist.

Beyond N+1 queries, ORM misuse causes:

Loading unnecessary columns — fetching all fields when you only need two, wasting I/O bandwidth and memory
Evaluating QuerySets prematurely — forcing database hits when the data isn't needed yet
Missing indexes — Django creates no indexes beyond primary keys unless you explicitly declare them
Using Python for aggregations — summing values in a loop instead of pushing SUM() to the database
Raw SQL injection — using .extra() or .raw() incorrectly with unsanitized user input

Understanding the ORM at the level this guide covers means none of these mistakes reach production.

Core Concepts

Models: Python Classes That Map to Database Tables

A Django model is a Python class that inherits from django.db.models.Model. Each class attribute that is a Field instance becomes a column in the database table.

Python Model Class          Database Table
──────────────────          ──────────────
class Product(Model)    →   CREATE TABLE catalog_product (
    name = CharField()          id BIGINT PRIMARY KEY,
    price = DecimalField()       name VARCHAR(255),
    is_active = BooleanField()   price DECIMAL(10,2),
                                 is_active BOOLEAN
                             );

Django derives the table name from the app label and class name ({app_label}_{model_name_lowercase}), but you can override it in Meta.

Fields: The Vocabulary of Your Schema

Django provides ~30 built-in field types. Choosing the right one matters for both correctness and performance:

Field	DB Type	Notes
`CharField`	`VARCHAR`	Always set `max_length`. Use `TextField` for unlimited text.
`IntegerField`	`INTEGER`	Use `BigAutoField` for PKs (default since Django 3.2).
`DecimalField`	`DECIMAL`	Use for money. Never `FloatField` for currency.
`BooleanField`	`BOOLEAN`	Avoid `NullBooleanField`; use `null=True` on `BooleanField` if needed.
`DateTimeField`	`TIMESTAMP`	Use `auto_now_add=True` for created_at, `auto_now=True` for updated_at.
`ForeignKey`	`BIGINT + FK constraint`	Creates `{field_name}_id` column. Always consider `on_delete`.
`JSONField`	`JSONB` (PostgreSQL)	Powerful but avoid for structured data that should be columns.
`UUIDField`	`UUID`	Use for public-facing identifiers to prevent IDOR.

QuerySets: Lazy Representations of Database Queries

A QuerySet is the central abstraction of the Django ORM. One of the most important characteristics of QuerySets is their "laziness." This means that the act of creating or modifying a QuerySet does not immediately result in any database activity.

QuerySets are lazy. A QuerySet can be created, passed around, and combined with other QuerySet instances, without actually incurring any trips to the database to fetch the items it describes.

This is the critical mental model. A QuerySet is not data — it is a description of a query. The database is only hit when the QuerySet is evaluated.

Evaluation triggers (moments when Django hits the database):

Iteration:          for order in Order.objects.all()
Slicing:            Order.objects.all()[0:10]
repr() / print:     print(Order.objects.all())
len():              len(Order.objects.all())
list():             list(Order.objects.all())
bool():             if Order.objects.filter(pk=1):
.get():             Order.objects.get(pk=1)
.count():           Order.objects.count()           ← SELECT COUNT(*)
.exists():          Order.objects.filter(pk=1).exists() ← SELECT 1 LIMIT 1

Keep in mind that once a query is executed, the retrieved data is stored in memory, and subsequent operations on that QuerySet use the "cached" data rather than querying the database again. This internal caching mechanism is limited to the scope of the QuerySet instance and does not persist beyond the lifetime of that specific QuerySet.

The Manager: The Gateway to QuerySets

Every model has at least one Manager — accessed as Model.objects. The manager is the entry point for all database queries. There are two reasons you might want to customize a Manager: to add extra Manager methods, and/or to modify the initial QuerySet the Manager returns. Adding extra Manager methods is the preferred way to add "table-level" functionality to your models.

Architecture Design

Here's a complete mental model of how a QuerySet travels from Python to SQL and back:

Python Code
    │
    │  Order.objects.filter(user=request.user)
    │         .select_related("shipping_address")
    │         .prefetch_related("items__product")
    │         .annotate(item_count=Count("items"))
    │         .order_by("-created_at")
    ▼
┌─────────────────────────────────────────────┐
│            QuerySet Object                   │
│                                              │
│  _result_cache = None   ← empty until eval  │
│  query = Query(...)     ← SQL being built   │
│  model = Order                              │
└──────────────────┬──────────────────────────┘
                   │  evaluation triggered
                   ▼
┌─────────────────────────────────────────────┐
│            SQL Compiler                      │
│                                              │
│  Resolves lookups  ← filter(user=request.user)
│  Builds JOINs      ← select_related(...)
│  Builds subqueries ← prefetch_related(...)
│  Adds GROUP BY     ← annotate(Count(...))
│  Adds ORDER BY     ← order_by("-created_at")
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│         Generated SQL (simplified)           │
│                                              │
│  SELECT orders_order.*,                      │
│         orders_address.*,                   │
│         COUNT(orders_item.id) AS item_count │
│  FROM orders_order                          │
│  LEFT JOIN orders_address                   │
│    ON orders_order.shipping_address_id =    │
│       orders_address.id                     │
│  WHERE orders_order.user_id = 7             │
│  GROUP BY orders_order.id, orders_address.id│
│  ORDER BY orders_order.created_at DESC      │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
            PostgreSQL
                   │
                   ▼ rows returned
┌─────────────────────────────────────────────┐
│         Model Instantiation                  │
│                                              │
│  Each row → Order() instance                │
│  Results cached in QuerySet._result_cache   │
└─────────────────────────────────────────────┘

Understanding this pipeline is the difference between writing code that looks clean but runs 400 queries, and code that looks identical but runs 2.

Step-by-Step Implementation

Step 1: Define Production-Ready Models

# apps/catalog/models.py
from django.db import models
from django.utils.translation import gettext_lazy as _
from django.utils.text import slugify


class TimestampedModel(models.Model):
    """
    Abstract base class providing created_at and updated_at
    to every model that inherits it. Define once, use everywhere.
    """
    created_at = models.DateTimeField(auto_now_add=True, db_index=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True


class Category(TimestampedModel):
    name      = models.CharField(max_length=150, unique=True)
    slug      = models.SlugField(max_length=150, unique=True, blank=True)
    parent    = models.ForeignKey(
        "self",
        on_delete=models.CASCADE,
        null=True,
        blank=True,
        related_name="children",
    )
    is_active = models.BooleanField(default=True, db_index=True)

    class Meta:
        app_label           = "catalog"
        verbose_name        = _("Category")
        verbose_name_plural = _("Categories")
        ordering            = ["name"]

    def save(self, *args, **kwargs):
        if not self.slug:
            self.slug = slugify(self.name)
        super().save(*args, **kwargs)

    def __str__(self) -> str:
        return self.name

Step 2: Define Complex Relationships

# apps/catalog/models.py (continued)

class Product(TimestampedModel):

    class Status(models.TextChoices):
        DRAFT     = "draft",     _("Draft")
        ACTIVE    = "active",    _("Active")
        ARCHIVED  = "archived",  _("Archived")

    name        = models.CharField(max_length=255)
    slug        = models.SlugField(max_length=255, unique=True)
    category    = models.ForeignKey(
        Category,
        on_delete=models.PROTECT,          # ← PROTECT: can't delete category with products
        related_name="products",
    )
    price       = models.DecimalField(
        max_digits=10, decimal_places=2,
        help_text=_("Price in USD"),
    )
    stock       = models.PositiveIntegerField(default=0)
    status      = models.CharField(
        max_length=20,
        choices=Status.choices,
        default=Status.DRAFT,
        db_index=True,
    )
    tags        = models.ManyToManyField(
        "Tag",
        blank=True,
        related_name="products",
    )

    class Meta:
        app_label = "catalog"
        indexes   = [
            models.Index(fields=["status", "category"]),
            models.Index(fields=["slug"]),
            models.Index(fields=["-created_at"]),
        ]
        constraints = [
            models.CheckConstraint(
                check=models.Q(price__gte=0),
                name="catalog_product_price_non_negative",
            ),
            models.CheckConstraint(
                check=models.Q(stock__gte=0),
                name="catalog_product_stock_non_negative",
            ),
        ]

    def __str__(self) -> str:
        return self.name

Step 3: Build Custom Managers and QuerySets

With managers you can freely share annotations, aggregations, and reuse common filters. The cleanest pattern is to define a custom QuerySet and expose it as a manager:

# apps/catalog/querysets.py
from django.db import models
from django.db.models import F, Q, Count, Avg, Sum


class ProductQuerySet(models.QuerySet):

    def active(self):
        """Filter to only published, in-stock products."""
        return self.filter(status="active", stock__gt=0)

    def by_category(self, category_slug: str):
        return self.filter(category__slug=category_slug)

    def with_stats(self):
        """
        Annotate each product with its order statistics.
        Pushes calculations to the database — not Python.
        """
        return self.annotate(
            total_sold=Sum("order_items__quantity"),
            average_rating=Avg("reviews__rating"),
            review_count=Count("reviews", distinct=True),
        )

    def in_price_range(self, min_price=None, max_price=None):
        qs = self
        if min_price is not None:
            qs = qs.filter(price__gte=min_price)
        if max_price is not None:
            qs = qs.filter(price__lte=max_price)
        return qs

    def low_stock(self, threshold: int = 10):
        """Products where stock is low but not zero."""
        return self.filter(stock__gt=0, stock__lte=threshold)

    def search(self, query: str):
        """Full-text search across name and description."""
        return self.filter(
            Q(name__icontains=query) |
            Q(description__icontains=query)
        )

# apps/catalog/models.py
from apps.catalog.querysets import ProductQuerySet

class Product(TimestampedModel):
    # ... fields ...

    # Expose the QuerySet as the default manager
    objects = ProductQuerySet.as_manager()

Usage becomes fluent and composable:

# Clean, readable, no SQL visible
products = (
    Product.objects
    .active()
    .by_category("electronics")
    .with_stats()
    .in_price_range(min_price=50, max_price=500)
    .select_related("category")
    .order_by("-total_sold")
)

Step 4: Configure Settings for Database Performance

# config/settings/production.py
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": env("DB_NAME"),
        "USER": env("DB_USER"),
        "PASSWORD": env("DB_PASSWORD"),
        "HOST": env("DB_HOST"),
        "PORT": env("DB_PORT", default="5432"),
        "CONN_MAX_AGE": 60,           # Reuse connections for 60s
        "OPTIONS": {
            "connect_timeout": 5,
            "options": "-c default_transaction_isolation=read committed",
        },
    }
}

Code Examples

F Expressions: Database-Side Arithmetic

F() expressions reference a model field's value at the database level, allowing you to perform operations without loading the object into Python first. This is both faster and race-condition-safe.

from django.db.models import F

# BAD — loads object into Python, then saves back
product = Product.objects.get(pk=42)
product.stock -= order_quantity
product.save()  # ← Two trips to DB. Race condition between read and write.

# GOOD — single atomic UPDATE at database level
Product.objects.filter(pk=42).update(stock=F("stock") - order_quantity)
# SQL: UPDATE catalog_product SET stock = stock - 3 WHERE id = 42

# F expressions in annotations
from django.db.models import ExpressionWrapper, DecimalField

orders = Order.objects.annotate(
    discount_amount=ExpressionWrapper(
        F("subtotal") * F("discount_percentage") / 100,
        output_field=DecimalField(max_digits=10, decimal_places=2),
    )
)

Q Objects: Complex Lookups and OR Logic

Q() objects allow you to build complex, composable WHERE clauses with AND, OR, and NOT logic:

from django.db.models import Q

# Simple OR: products that are active OR on sale
products = Product.objects.filter(
    Q(status="active") | Q(on_sale=True)
)

# Complex nested logic
# (active OR sale) AND (price < 100) AND NOT (archived)
products = Product.objects.filter(
    (Q(status="active") | Q(on_sale=True)) &
    Q(price__lt=100) &
    ~Q(status="archived")
)

# Reusable Q objects
def active_and_affordable_q(max_price: float) -> Q:
    return Q(status="active") & Q(price__lte=max_price)

budget_products = Product.objects.filter(active_and_affordable_q(50.00))

Annotations and Aggregations: Push Calculations to the Database

Unlike aggregate(), annotate() is not a terminal clause. The output of the annotate() clause is a QuerySet; this QuerySet can be modified using any other QuerySet operation, including filter(), order_by(), or even additional calls to annotate().

from django.db.models import (
    Count, Sum, Avg, Min, Max,
    Case, When, Value, IntegerField, DecimalField,
    ExpressionWrapper, F
)
from django.db.models.functions import Coalesce, TruncMonth

# annotate() → adds a field to EACH object in the QuerySet
categories_with_counts = Category.objects.annotate(
    product_count=Count("products", distinct=True),
    active_count=Count(
        "products",
        filter=Q(products__status="active"),
        distinct=True,
    ),
    avg_price=Coalesce(Avg("products__price"), 0.0),
)
# Each category now has .product_count, .active_count, .avg_price

# aggregate() → returns a SINGLE dict summarising the entire QuerySet
summary = Order.objects.filter(
    created_at__year=2025
).aggregate(
    total_revenue=Sum("total"),
    average_order_value=Avg("total"),
    order_count=Count("id"),
    max_order=Max("total"),
    min_order=Min("total"),
)
# Returns: {"total_revenue": Decimal("125300.50"), "average_order_value": ..., ...}

# Monthly revenue breakdown — GROUP BY month
monthly_revenue = (
    Order.objects
    .annotate(month=TruncMonth("created_at"))
    .values("month")
    .annotate(revenue=Sum("total"), orders=Count("id"))
    .order_by("month")
)
# SQL: SELECT DATE_TRUNC('month', created_at) AS month,
#             SUM(total) AS revenue, COUNT(id) AS orders
#      FROM orders_order
#      GROUP BY month ORDER BY month

# Conditional annotation with Case/When
products_with_tier = Product.objects.annotate(
    price_tier=Case(
        When(price__lt=25,  then=Value("budget")),
        When(price__lt=100, then=Value("mid-range")),
        When(price__lt=500, then=Value("premium")),
        default=Value("luxury"),
        output_field=models.CharField(),
    )
)
# Each product now has .price_tier: "budget", "mid-range", "premium", or "luxury"

select_related and prefetch_related: The N+1 Cure

# Scenario: Display orders with user, shipping address, and line items

# BAD — N+1 queries
orders = Order.objects.all()
for order in orders:           # 1 query (SELECT orders)
    user = order.user          # N queries (SELECT user WHERE id=X)
    addr = order.shipping_address  # N queries
    for item in order.items.all():  # N queries (SELECT items WHERE order=X)
        name = item.product.name    # N*M queries

# GOOD — 3 queries total, regardless of scale
orders = (
    Order.objects
    # select_related: SQL JOIN for FK/OneToOne relationships
    .select_related("user", "shipping_address")
    # prefetch_related: Separate batched query for M2M/reverse FK
    .prefetch_related("items__product__category")
    .filter(status="processing")
    .order_by("-created_at")
)
# Query 1: SELECT orders + JOIN users + JOIN addresses WHERE status='processing'
# Query 2: SELECT items WHERE order_id IN (1, 2, 3, ...)
# Query 3: SELECT products + JOIN categories WHERE id IN (...)

Custom Prefetch Objects: Prefetch with Filters

from django.db.models import Prefetch

# Prefetch only active reviews, pre-ordered and filtered
active_reviews = Review.objects.filter(is_approved=True).order_by("-created_at")

products = Product.objects.prefetch_related(
    Prefetch("reviews", queryset=active_reviews, to_attr="approved_reviews")
).active()

# Now product.approved_reviews is a pre-loaded list — no extra queries
for product in products:
    top_review = product.approved_reviews[0] if product.approved_reviews else None

Bulk Operations: Dozens of Rows in One Query

from django.db import transaction

# bulk_create: Insert multiple rows in one INSERT statement
new_tags = Tag.objects.bulk_create([
    Tag(name="python"),
    Tag(name="django"),
    Tag(name="backend"),
], ignore_conflicts=True)  # ← skip if already exists

# bulk_update: Update multiple rows in one UPDATE statement
products_to_reactivate = Product.objects.filter(status="archived", stock__gt=0)
for product in products_to_reactivate:
    product.status = "active"

Product.objects.bulk_update(products_to_reactivate, fields=["status"])
# SQL: UPDATE catalog_product SET status=CASE WHEN id=1 THEN 'active' ... END

# update(): Single SQL UPDATE — no model instantiation
Product.objects.filter(
    category__slug="electronics",
    stock=0,
).update(status="archived")
# SQL: UPDATE catalog_product SET status='archived'
#      WHERE category_id IN (SELECT id FROM category WHERE slug='electronics')
#      AND stock = 0

The `iterator()` Method: Memory-Efficient Large Queryset Processing

# BAD — loads ALL 500,000 rows into memory at once
for order in Order.objects.filter(status="pending"):
    process_order(order)  # OOM risk at scale

# GOOD — fetches in chunks, much lower memory footprint
for order in Order.objects.filter(status="pending").iterator(chunk_size=2000):
    process_order(order)

# With prefetch (manual, since prefetch_related doesn't work with iterator)
for order in Order.objects.filter(status="pending").select_related("user").iterator(chunk_size=2000):
    process_order(order)

Model Methods vs Manager Methods

class Order(TimestampedModel):
    # ... fields ...

    # ── MODEL METHODS: row-level, instance-specific logic ──
    def get_subtotal(self) -> Decimal:
        """Sum of all item prices. Requires items to be prefetched."""
        return sum(item.subtotal for item in self.items.all())

    def can_be_cancelled(self) -> bool:
        return self.status in ("pending", "processing")

    def cancel(self) -> None:
        if not self.can_be_cancelled():
            raise ValueError(f"Order #{self.pk} cannot be cancelled from status '{self.status}'")
        self.status = "cancelled"
        self.save(update_fields=["status", "updated_at"])

    # ── USE A MANAGER/SERVICE FOR TABLE-LEVEL OPERATIONS ──
    # Don't put bulk queries or cross-table logic in model methods.

Transactions: Atomicity Guarantees

from django.db import transaction


def create_order_with_items(user, cart_items: list) -> Order:
    """
    Creates an Order and its OrderItems atomically.
    If anything fails, the entire operation rolls back.
    No partial orders reach the database.
    """
    with transaction.atomic():
        order = Order.objects.create(
            user=user,
            status=Order.Status.PENDING,
            total=sum(item["price"] * item["quantity"] for item in cart_items),
        )

        order_items = [
            OrderItem(
                order=order,
                product_id=item["product_id"],
                quantity=item["quantity"],
                unit_price=item["price"],
            )
            for item in cart_items
        ]
        OrderItem.objects.bulk_create(order_items)

        # Update stock atomically — no race condition
        for item in cart_items:
            updated = Product.objects.filter(
                pk=item["product_id"],
                stock__gte=item["quantity"],   # Only update if stock is sufficient
            ).update(stock=F("stock") - item["quantity"])

            if updated == 0:
                raise ValueError(f"Insufficient stock for product {item['product_id']}")

        return order

Performance Optimization

1. Use `only()` and `defer()` to Limit Column Fetches

Loading columns you don't need wastes I/O bandwidth and memory. only() is the whitelist approach; defer() is the blacklist:

# ONLY load the columns you actually use
product_list = (
    Product.objects
    .active()
    .only("id", "name", "slug", "price", "stock")  # ← 5 columns instead of 20
    .order_by("name")
)
# SQL: SELECT id, name, slug, price, stock FROM catalog_product WHERE status='active'

# DEFER columns known to be heavy and rarely needed
products = Product.objects.defer("description", "metadata", "image_data")

Important: Accessing a deferred field on an instance triggers an additional query per instance. Use only() when you know the exact fields needed.

2. Use `values()` and `values_list()` for Read-Only Data

When you don't need model instances — for APIs, exports, aggregations — skip object instantiation entirely:

# Returns dicts instead of model instances — faster, less memory
products = (
    Product.objects
    .active()
    .values("id", "name", "price", "stock")
)
# [{"id": 1, "name": "Widget", "price": "29.99", "stock": 100}, ...]

# Returns tuples — even lighter
product_ids = Product.objects.active().values_list("id", flat=True)
# (1, 2, 3, 4, ...)

# Get a dict directly: {id: name}
id_name_map = dict(Product.objects.values_list("id", "name"))

3. Use `exists()` and `count()` Appropriately

# BAD — loads entire QuerySet to check existence
if len(Order.objects.filter(user=user, status="pending")) > 0:
    ...

# GOOD — SELECT 1 LIMIT 1 — no rows loaded
if Order.objects.filter(user=user, status="pending").exists():
    ...

# BAD — evaluates QuerySet to count
count = len(Product.objects.filter(status="active"))

# GOOD — SELECT COUNT(*) — single aggregate query
count = Product.objects.filter(status="active").count()

4. Enforce Query Budgets in Tests

# apps/orders/tests/test_selectors.py
from django.test import TestCase
from apps.orders.selectors import get_orders_for_user
from apps.orders.tests.factories import OrderFactory, OrderItemFactory


class TestOrderSelectorQueryCount(TestCase):
    """
    Lock in the query count of critical selectors.
    If someone adds an N+1 query, this test fails immediately
    — not in production monitoring at 2am.
    """
    def setUp(self):
        self.user = UserFactory()
        orders = OrderFactory.create_batch(10, user=self.user)
        for order in orders:
            OrderItemFactory.create_batch(5, order=order)

    def test_get_orders_query_count(self):
        with self.assertNumQueries(3):
            # 1: Orders + JOIN users + JOIN addresses
            # 2: Prefetch order items
            # 3: Prefetch products
            list(get_orders_for_user(user_id=self.user.id))

5. Database Indexes: The Most Impactful Single Change

class Order(TimestampedModel):
    class Meta:
        indexes = [
            # Composite: the most common query — "user's orders with status"
            models.Index(
                fields=["user", "status"],
                name="idx_order_user_status",
            ),
            # Descending created_at for default ordering
            models.Index(
                fields=["-created_at"],
                name="idx_order_created_at_desc",
            ),
        ]

        # Partial index (PostgreSQL): only index non-cancelled orders
        # Smaller, faster index that serves the hot query path
        # Add via a custom migration for PostgreSQL-specific syntax:
        # CREATE INDEX idx_active_orders ON orders_order(user_id)
        # WHERE status != 'cancelled';

To identify missing indexes, use EXPLAIN ANALYZE on slow queries:

# In Django shell — inspect query plan for slow selectors
from django.db import connection

with connection.cursor() as cursor:
    cursor.execute("""
        EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
        SELECT * FROM orders_order
        WHERE user_id = 1 AND status = 'processing'
        ORDER BY created_at DESC
        LIMIT 20
    """)
    for row in cursor.fetchall():
        print(row[0])

Security Best Practices

1. SQL Injection: What the ORM Protects and What It Doesn't

The Django ORM parameterises all queries automatically — field lookups and filter() calls are never vulnerable to SQL injection. However, there are escape hatches that require manual care:

# SAFE — ORM parameterises all values
Product.objects.filter(name=user_input)
# SQL: SELECT ... WHERE name = %s -- [user_input]

# DANGEROUS — raw SQL with string formatting
Product.objects.raw(f"SELECT * FROM catalog_product WHERE name = '{user_input}'")
# ← Never do this. user_input = "'; DROP TABLE catalog_product; --"

# SAFE — raw SQL with parameterisation
Product.objects.raw(
    "SELECT * FROM catalog_product WHERE name = %s",
    [user_input]  # ← always use parameterised placeholders
)

# DANGEROUS — extra() with unescaped user input
Product.objects.extra(where=[f"name = '{user_input}'"])  # ← never

# SAFE — extra() with params
Product.objects.extra(where=["name = %s"], params=[user_input])

2. Prevent Mass Assignment

Never pass request.data or request.POST directly to Model.objects.create():

# DANGEROUS — attacker can set any model field
order = Order.objects.create(**request.POST.dict())  # ← never

# SAFE — whitelist fields through a serializer
from apps.orders.serializers import CreateOrderSerializer

serializer = CreateOrderSerializer(data=request.data)
serializer.is_valid(raise_exception=True)
order = OrderService.create(**serializer.validated_data)

3. Prevent IDOR with Object-Level Scoping

# DANGEROUS — any authenticated user can access any order by ID
order = get_object_or_404(Order, pk=pk)  # ← IDOR vulnerability

# SAFE — always scope to the authenticated user
order = get_object_or_404(Order, pk=pk, user=request.user)

# Even better — use a scoped QuerySet in your selector
def get_order_for_user(user, order_id: int) -> Order:
    return get_object_or_404(
        Order.objects.filter(user=user),
        pk=order_id,
    )

4. Use `update_fields` in `.save()` for Precision

# BAD — saves all fields; risks overwriting concurrent updates
product.status = "archived"
product.save()  # ← Rewrites all columns including any not in memory

# GOOD — only updates the specific columns you changed
product.status = "archived"
product.save(update_fields=["status", "updated_at"])
# SQL: UPDATE catalog_product SET status='archived', updated_at=NOW() WHERE id=42

5. Use Constraints for Data Integrity at the Database Level

Django model constraints enforce business rules at the database layer — the last line of defence:

class OrderItem(models.Model):
    quantity   = models.PositiveIntegerField()
    unit_price = models.DecimalField(max_digits=10, decimal_places=2)

    class Meta:
        constraints = [
            models.CheckConstraint(
                check=models.Q(quantity__gt=0),
                name="orderitem_positive_quantity",
            ),
            models.CheckConstraint(
                check=models.Q(unit_price__gte=0),
                name="orderitem_non_negative_price",
            ),
            models.UniqueConstraint(
                fields=["order", "product"],
                name="orderitem_unique_order_product",
            ),
        ]

Common Developer Mistakes

❌ Mistake 1: Evaluating QuerySets Too Early

# BAD — evaluates the QuerySet immediately, loses chainability
def get_active_products():
    return list(Product.objects.filter(status="active"))  # ← evaluated!

# Can't do: get_active_products().filter(category=electronics)

# GOOD — return the QuerySet, let the caller decide when to evaluate
def get_active_products():
    return Product.objects.filter(status="active")  # ← lazy, chainable

# Caller can now refine:
products = get_active_products().filter(category=electronics).order_by("-price")

❌ Mistake 2: Using `len()` Instead of `.count()`

# BAD — loads all rows into memory just to count them
if len(Order.objects.filter(user=user)) > 0:
    ...
n = len(Product.objects.all())   # loads potentially millions of rows

# GOOD — single COUNT(*) query, zero rows loaded
if Order.objects.filter(user=user).exists():
    ...
n = Product.objects.count()

❌ Mistake 3: Combining Multiple Annotations Incorrectly

Combining multiple aggregations with annotate() will yield wrong results because joins are used instead of subqueries.

# BAD — duplicated rows due to multiple JOINs; author__count will be wrong
books = Book.objects.annotate(Count("authors"), Count("stores"))
# books[0].authors__count → wrong (inflated)

# GOOD — use distinct=True to fix double-counting
books = Book.objects.annotate(
    author_count=Count("authors", distinct=True),
    store_count=Count("stores", distinct=True),
)

❌ Mistake 4: Calling `.save()` Inside a Loop

# BAD — 1,000 UPDATE queries for 1,000 products
products = Product.objects.filter(category=electronics)
for product in products:
    product.price *= 0.9  # 10% discount
    product.save()        # ← one query per product

# GOOD — single UPDATE query
Product.objects.filter(category=electronics).update(
    price=F("price") * Decimal("0.9")
)

❌ Mistake 5: Accessing Related Objects Without Prefetching

# BAD — template loop triggers N+1
{% for order in orders %}
    {{ order.user.email }}      {# ← DB hit per order #}
    {{ order.items.count() }}   {# ← DB hit per order #}
{% endfor %}

# GOOD — prefetch before passing to template
orders = Order.objects.select_related("user").prefetch_related("items")

❌ Mistake 6: Using `.filter()` After `.values()` With Annotations

# BAD — filter order matters with annotations
# This may give unexpected results depending on Django version
result = (
    Order.objects
    .values("status")
    .annotate(total=Sum("amount"))
    .filter(status="active")  # ← safe here, but fragile if reordered
)

# GOOD — filter before annotating when possible
result = (
    Order.objects
    .filter(status="active")   # ← filter first
    .values("status")
    .annotate(total=Sum("amount"))
)

Real Production Use Cases

Use Case 1: E-Commerce Dashboard — Complex Aggregations

A product manager's dashboard needs real-time stats: revenue by category, top products, low-stock alerts, conversion rates. All computed in the database — no Python loops:

# apps/analytics/selectors.py
from django.db.models import Sum, Count, Avg, F, Q, ExpressionWrapper, DecimalField
from django.db.models.functions import TruncMonth, Coalesce


def get_dashboard_stats(start_date, end_date) -> dict:
    """
    Returns complete dashboard data in 4 queries.
    Would take 100+ Python iterations if done naively.
    """
    from apps.orders.models import Order, OrderItem
    from apps.catalog.models import Category

    # Query 1: Revenue by category this period
    revenue_by_category = (
        OrderItem.objects
        .filter(order__created_at__range=(start_date, end_date))
        .values("product__category__name")
        .annotate(
            revenue=Sum(
                ExpressionWrapper(
                    F("quantity") * F("unit_price"),
                    output_field=DecimalField(max_digits=12, decimal_places=2),
                )
            ),
            units_sold=Sum("quantity"),
        )
        .order_by("-revenue")[:10]
    )

    # Query 2: Monthly trend
    monthly_trend = (
        Order.objects
        .filter(created_at__range=(start_date, end_date))
        .annotate(month=TruncMonth("created_at"))
        .values("month")
        .annotate(
            revenue=Sum("total"),
            order_count=Count("id"),
            avg_order_value=Avg("total"),
        )
        .order_by("month")
    )

    # Query 3: Top products by revenue
    top_products = (
        OrderItem.objects
        .filter(order__created_at__range=(start_date, end_date))
        .values("product__name", "product__id")
        .annotate(
            total_revenue=Sum(F("quantity") * F("unit_price"),
                              output_field=DecimalField()),
            total_units=Sum("quantity"),
        )
        .order_by("-total_revenue")[:20]
    )

    # Query 4: Low stock alerts
    low_stock = (
        Product.objects
        .active()
        .filter(stock__lte=10)
        .values("id", "name", "stock", "category__name")
        .order_by("stock")
    )

    return {
        "revenue_by_category": list(revenue_by_category),
        "monthly_trend": list(monthly_trend),
        "top_products": list(top_products),
        "low_stock_alerts": list(low_stock),
    }

Use Case 2: Large Data Export — Memory-Efficient Iterator Pattern

A finance team needs to export 500,000 orders to CSV. Loading all into memory would crash the server:

# apps/exports/services.py
import csv
from django.http import StreamingHttpResponse
from apps.orders.models import Order


class EchoWriter:
    """File-like object that echoes its input. For StreamingHttpResponse."""
    def write(self, value):
        return value


def stream_orders_csv(queryset) -> StreamingHttpResponse:
    """
    Stream a massive CSV export without loading everything into memory.
    Uses Django's StreamingHttpResponse + ORM iterator() for O(1) memory usage.
    """
    writer = csv.writer(EchoWriter())

    def generate_rows():
        yield writer.writerow(["ID", "User Email", "Status", "Total", "Created"])

        for order in (
            queryset
            .select_related("user")
            .only("id", "user__email", "status", "total", "created_at")
            .iterator(chunk_size=2000)
        ):
            yield writer.writerow([
                order.id,
                order.user.email,
                order.status,
                str(order.total),
                order.created_at.isoformat(),
            ])

    response = StreamingHttpResponse(generate_rows(), content_type="text/csv")
    response["Content-Disposition"] = 'attachment; filename="orders.csv"'
    return response

Use Case 3: SaaS Multi-Tenant Data Isolation via Custom Manager

# apps/core/managers.py
from django.db import models


class TenantQuerySet(models.QuerySet):
    def for_tenant(self, tenant_id: int):
        return self.filter(tenant_id=tenant_id)


class TenantManager(models.Manager):
    def get_queryset(self):
        return TenantQuerySet(self.model, using=self._db)

    def for_tenant(self, tenant_id: int):
        return self.get_queryset().for_tenant(tenant_id)


# apps/projects/models.py
class Project(TimestampedModel):
    tenant  = models.ForeignKey("tenants.Tenant", on_delete=models.CASCADE)
    name    = models.CharField(max_length=255)
    # ...

    objects = TenantManager()

# Usage — structurally impossible to cross tenant boundaries
projects = Project.objects.for_tenant(request.tenant.id)

Conclusion

The Django ORM is a precision instrument. Used correctly, it is one of the most expressive, safe, and performant database interfaces available in any language. Used carelessly, it is a source of N+1 queries, memory bloat, and data integrity bugs that scale poorly and fail unpredictably.

The patterns in this guide — lazy QuerySet chaining, custom managers with composable QuerySets, F expressions for atomic updates, annotate() for database-side computation, select_related and prefetch_related for relationship loading, iterator() for memory-efficient bulk processing, and model-level constraints for data integrity — are not advanced tricks. They are the baseline for production-quality Django code.

The most important principle is this: do work at the lowest possible layer. Aggregations belong in SQL, not Python loops. Object graphs belong in prefetched QuerySets, not repeated database calls. Business rules belong in database constraints, not only in application code.

Write your models deliberately. Build your QuerySets lazily. Push your computations down. Lock in your query counts with tests. And use EXPLAIN ANALYZE before you assume a query is fast enough for production.

The database is the foundation. Build it like it matters.

Django Apps vs Projects Explained: A Complete Production Guide

Alanso Mathew — Wed, 18 Mar 2026 05:29:03 +0000

From "what's the difference?" to packaging reusable apps and deploying production-grade multi-app architectures — a backend engineer's complete guide.

Originally published at: https://alansomathewdev.blogspot.com/2026/03/django-apps-vs-projects-explained.html

Introduction
Why This Matters in Production Systems
Core Concepts
Architecture Design
Step-by-Step Implementation
Code Examples
Performance Optimization
Security Best Practices
Common Developer Mistakes
Real Production Use Cases
Conclusion

Introduction

Ask ten Django developers to explain the difference between a project and an app, and you'll get ten different answers. Some will say "a project contains apps." Some will say "apps are like modules." A few will shrug and say "I just run startapp when I need a new feature."

They're all partially right — and all missing the deeper picture.

The project/app distinction in Django is not just a file-organisation convention. It is a software design principle implemented as a framework feature. It defines how code is scoped, how it is reused, how it is tested in isolation, how it scales across teams, and ultimately how well your codebase survives the passage of time and the accumulation of features.

An app is a web application that does something — a blog system, a database of public records, or a small poll app. A project is a collection of configuration and apps for a particular website. A project can contain multiple apps, and an app can be in multiple projects.

That definition from the official Django documentation is accurate, but thin. It tells you the vocabulary without telling you why it exists, how to use it well, or what happens when you get it wrong in a production codebase with ten engineers and two years of accumulated technical debt.

This guide goes all the way. We'll cover the conceptual distinction, the file-level mechanics, real production architecture patterns, reusable app packaging, performance, security, and the mistakes that cost teams weeks of refactoring.

Let's start from the beginning.

Why This Matters in Production Systems

Getting the project/app boundary wrong is one of the most expensive structural mistakes you can make in Django. Here's why it compounds over time.

Maintainability degrades non-linearly. When all your models, views, and business logic live in a single app — what engineers call a "god app" — every change has unpredictable blast radius. A change to the users model might break billing, orders, and notifications, but you only find out through integration tests or production errors.

Teams can't work in parallel. If five engineers are all working in the same main app, merge conflicts are constant and code review becomes territorial. Well-defined apps give teams ownership boundaries that reduce friction.

Reuse is impossible. Apps are reusable and can be used in multiple projects. Django follows a "pluggable" architecture, meaning you can plug apps into different projects easily. This modularity allows you to keep your codebase organized and maintainable. A notification system built as a proper Django app can be extracted and dropped into a second product. One built as a mess of views and models scattered across a god app cannot.

Testing is slower and less reliable. An app with clear boundaries can be tested in isolation. A tangled codebase requires spinning up the entire application to test any individual feature.

Scaling becomes architectural surgery. If your codebase eventually needs to split into microservices — or even just separate Django processes for different workloads — apps with clean boundaries can be extracted. Monolithic apps cannot.

The investment in understanding and correctly applying the project/app distinction pays compound interest over the lifetime of a codebase.

Core Concepts

What Is a Django Project?

A project is a top-level container for your web application. A project contains the configurations for your web application and one or more apps, each providing a specific set of functionalities or features. It also contains any components shared between its different apps.

More concretely, a Django project is defined by:

settings.py (or a settings package) — global configuration: database, cache, middleware, installed apps, authentication
urls.py — the root URL dispatcher that routes requests to apps
wsgi.py / asgi.py — the WSGI/ASGI entry point for production servers
manage.py — the project management CLI

A project is not reusable. It is environment-specific. It knows about the server it runs on, the database it talks to, the cloud storage it uses. You wouldn't package a project and put it on PyPI — you'd put an app there.

What Is a Django App?

A Django app is a self-contained component of a Django project. It is a module that provides specific functionality, such as handling authentication, managing blog posts, or serving an API. An app should represent a single, specific functionality or purpose within the overall website.

A Django app is defined by:

models.py — data structure and database schema
views.py — request handling and response logic
urls.py — URL patterns scoped to this app
admin.py — admin site registration
apps.py — the AppConfig class, the app's identity
migrations/ — database schema version history
tests/ — isolated test suite

An app is reusable. The Python Package Index has a vast range of packages you can use in your own Python programs. Django itself is also a normal Python package. This means that you can take existing Python packages or Django apps and compose them into your own web project. You only need to write the parts that make your project unique.

The `AppConfig` Class — The App's Identity

Every properly configured Django app has an AppConfig subclass in apps.py. This is the app's formal registration with Django's application registry:

# apps/orders/apps.py
from django.apps import AppConfig

class OrdersConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name  = "apps.orders"   # full Python dotted path
    label = "orders"        # unique short name used in migrations and DB tables
    verbose_name = "Order Management"

    def ready(self):
        """
        Called once when Django starts.
        Safe place to connect signals.
        """
        import apps.orders.signals  # noqa: F401

The ready() method is critically important for signal registration — more on this in the code examples section.

The `INSTALLED_APPS` Contract

The INSTALLED_APPS setting in your project's settings.py is the formal list of every app the project knows about. Apps not in this list are invisible to Django's ORM, migration system, admin, and template loader.

# config/settings/base.py
INSTALLED_APPS = [
    # ── Django built-in apps ──────────────────────
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",

    # ── Third-party apps (installed via pip) ──────
    "rest_framework",
    "django_filters",
    "corsheaders",
    "celery",

    # ── Local project apps ────────────────────────
    "apps.users.apps.UsersConfig",
    "apps.catalog.apps.CatalogConfig",
    "apps.orders.apps.OrdersConfig",
    "apps.notifications.apps.NotificationsConfig",
    "apps.payments.apps.PaymentsConfig",
]

Always reference apps using their AppConfig class (the dotted string ending in Config) rather than just the package path. This ensures ready() is called and the verbose_name is applied correctly.

Architecture Design

Here's a complete view of how a production Django project organises its apps, and how they relate to each other:

myproject/
│
├── config/                          ← PROJECT (configuration only)
│   ├── settings/
│   │   ├── base.py                  ← Shared project settings
│   │   ├── development.py           ← Local dev overrides
│   │   ├── production.py            ← Production settings
│   │   └── test.py                  ← Test runner settings
│   ├── urls.py                      ← Root URL dispatcher
│   ├── wsgi.py
│   └── asgi.py
│
├── apps/                            ← ALL APPS LIVE HERE
│   │
│   ├── users/                       ← App: authentication & profiles
│   │   ├── migrations/
│   │   ├── tests/
│   │   ├── apps.py                  ← AppConfig
│   │   ├── models.py
│   │   ├── views.py
│   │   ├── serializers.py
│   │   ├── services.py              ← Business logic
│   │   ├── selectors.py             ← Read/query logic
│   │   ├── signals.py
│   │   ├── admin.py
│   │   └── urls.py
│   │
│   ├── catalog/                     ← App: products & categories
│   │   └── ... (same structure)
│   │
│   ├── orders/                      ← App: cart, checkout, order lifecycle
│   │   └── ...
│   │
│   ├── payments/                    ← App: Stripe integration, invoices
│   │   └── ...
│   │
│   └── notifications/               ← App: email, SMS, push
│       └── ...
│
├── common/                          ← SHARED UTILITIES (not a Django app)
│   ├── exceptions.py
│   ├── mixins.py
│   ├── pagination.py
│   └── permissions.py
│
├── infrastructure/                  ← THIRD-PARTY INTEGRATIONS
│   ├── email/                       ← SendGrid/SES wrapper
│   ├── storage/                     ← S3 wrapper
│   └── payment/                     ← Stripe/Braintree wrapper
│
├── requirements/
│   ├── base.txt
│   ├── development.txt
│   └── production.txt
│
├── manage.py
└── pyproject.toml

The Dependency Direction Rule

Apps should form a directed acyclic graph (DAG) of dependencies. No circular imports. No app should import from an app that ranks "above" it conceptually.

ALLOWED dependency direction:

notifications → users      ✅ (notifications can send to users)
orders        → catalog    ✅ (orders reference products)
orders        → users      ✅ (orders belong to users)
payments      → orders     ✅ (payments are for orders)

FORBIDDEN:
users         → orders     ❌ (users shouldn't know about orders)
catalog       → orders     ❌ (products shouldn't know about orders)

If you find yourself wanting to import orders from users, you need a third app (like notifications) that both can depend on — or you need to use Django signals to decouple the relationship.

Step-by-Step Implementation

Step 1: Initialise the Project (Not an App)

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install Django
pip install django django-environ djangorestframework

# Create project — trailing dot puts manage.py at root level
django-admin startproject config .

# Create the apps directory
mkdir -p apps
touch apps/__init__.py

Step 2: Create Your First App

# Navigate into the apps directory and scaffold the app
cd apps
django-admin startapp users
django-admin startapp catalog
django-admin startapp orders
cd ..

Step 3: Update AppConfig for Each App

After creating apps inside the apps/ subdirectory, you must update the name attribute in each AppConfig to reflect the new path:

# apps/users/apps.py
from django.apps import AppConfig

class UsersConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name         = "apps.users"   # ← full dotted path from project root
    label        = "users"        # ← unique short label (used in DB table names)
    verbose_name = "Users & Authentication"

    def ready(self):
        import apps.users.signals  # noqa: F401

Step 4: Wire Apps into the Project

# config/settings/base.py
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    # third-party
    "rest_framework",
    # local apps — always use AppConfig
    "apps.users.apps.UsersConfig",
    "apps.catalog.apps.CatalogConfig",
    "apps.orders.apps.OrdersConfig",
]

AUTH_USER_MODEL = "users.User"

Step 5: Compose App URLs in the Project Router

# config/urls.py
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path("admin/",          admin.site.urls),
    path("api/users/",      include("apps.users.urls",        namespace="users")),
    path("api/catalog/",    include("apps.catalog.urls",      namespace="catalog")),
    path("api/orders/",     include("apps.orders.urls",       namespace="orders")),
    path("api/payments/",   include("apps.payments.urls",     namespace="payments")),
]

Each app declares its own app_name for URL namespacing:

# apps/orders/urls.py
from django.urls import path
from apps.orders.views import OrderListView, OrderDetailView

app_name = "orders"

urlpatterns = [
    path("",          OrderListView.as_view(),   name="list"),
    path("<int:pk>/", OrderDetailView.as_view(), name="detail"),
]

# Reverse URL usage: reverse("orders:detail", kwargs={"pk": 42})

Step 6: Run and Validate

# Create and apply migrations for all installed apps
python manage.py makemigrations
python manage.py migrate

# Verify the project sees all apps
python manage.py shell -c "from django.apps import apps; print([a.name for a in apps.get_app_configs()])"

Code Examples

Complete App Model with Proper Relationships

# apps/orders/models.py
from django.db import models
from django.contrib.auth import get_user_model
from django.utils.translation import gettext_lazy as _

User = get_user_model()


class Order(models.Model):
    """
    Represents a customer order.

    This model belongs to the 'orders' app. It references:
    - apps.users  → via ForeignKey to User
    - apps.catalog → via OrderItem → Product

    It does NOT import from those apps' models directly.
    Cross-app references use ForeignKey strings ("catalog.Product")
    to avoid circular imports.
    """

    class Status(models.TextChoices):
        PENDING    = "pending",    _("Pending")
        PROCESSING = "processing", _("Processing")
        SHIPPED    = "shipped",    _("Shipped")
        DELIVERED  = "delivered",  _("Delivered")
        CANCELLED  = "cancelled",  _("Cancelled")

    user             = models.ForeignKey(
        User,
        on_delete=models.CASCADE,
        related_name="orders",
        verbose_name=_("customer"),
    )
    status           = models.CharField(
        max_length=20,
        choices=Status.choices,
        default=Status.PENDING,
        db_index=True,
    )
    total            = models.DecimalField(max_digits=10, decimal_places=2)
    created_at       = models.DateTimeField(auto_now_add=True)
    updated_at       = models.DateTimeField(auto_now=True)

    class Meta:
        app_label = "orders"   # ← explicit, matches AppConfig.label
        ordering  = ["-created_at"]
        verbose_name        = _("Order")
        verbose_name_plural = _("Orders")
        indexes = [
            models.Index(fields=["user", "status"]),
            models.Index(fields=["-created_at"]),
        ]

    def __str__(self) -> str:
        return f"Order #{self.pk} ({self.get_status_display()})"


class OrderItem(models.Model):
    """
    Line item within an order.
    References catalog.Product using a lazy string to avoid circular imports.
    """
    order    = models.ForeignKey(Order,            on_delete=models.CASCADE, related_name="items")
    product  = models.ForeignKey("catalog.Product", on_delete=models.PROTECT,  related_name="order_items")
    quantity = models.PositiveIntegerField()
    unit_price = models.DecimalField(max_digits=10, decimal_places=2)

    class Meta:
        app_label = "orders"

    @property
    def subtotal(self):
        return self.quantity * self.unit_price

Custom User Model (Always in the `users` App)

# apps/users/models.py
from django.contrib.auth.models import AbstractUser
from django.db import models
from django.utils.translation import gettext_lazy as _


class User(AbstractUser):
    """
    Custom user model. ALWAYS defined in your own app.
    ALWAYS set before the first migration. Non-negotiable.

    django.contrib.auth is a third-party app (included with Django).
    This app (apps.users) extends it for project-specific needs.
    """
    email  = models.EmailField(_("email address"), unique=True)
    avatar = models.ImageField(upload_to="avatars/%Y/%m/", null=True, blank=True)
    bio    = models.TextField(blank=True)

    USERNAME_FIELD  = "email"
    REQUIRED_FIELDS = ["username"]

    class Meta:
        app_label           = "users"
        verbose_name        = _("User")
        verbose_name_plural = _("Users")

    def __str__(self) -> str:
        return self.email

Signals: Decoupling Apps Without Circular Imports

Signals are the primary mechanism for communication between apps without creating direct import dependencies. The orders app can trigger behaviour in the notifications app without importing it:

# apps/orders/signals.py
from django.db.models.signals import post_save
from django.dispatch import receiver
from apps.orders.models import Order


@receiver(post_save, sender=Order)
def on_order_status_changed(sender, instance: Order, created: bool, **kwargs):
    """
    When an order is saved (created or updated), fire a domain event.
    The notifications app listens to this signal — no direct coupling.
    """
    from django.db import transaction

    if created:
        transaction.on_commit(
            lambda: _dispatch_order_created(instance.id)
        )
    elif "status" in (kwargs.get("update_fields") or []):
        transaction.on_commit(
            lambda: _dispatch_order_status_changed(instance.id, instance.status)
        )


def _dispatch_order_created(order_id: int) -> None:
    from apps.notifications.tasks import send_order_confirmation
    send_order_confirmation.delay(order_id)


def _dispatch_order_status_changed(order_id: int, new_status: str) -> None:
    from apps.notifications.tasks import send_order_status_update
    send_order_status_update.delay(order_id, new_status)

# apps/orders/apps.py
from django.apps import AppConfig

class OrdersConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name  = "apps.orders"
    label = "orders"

    def ready(self):
        # Import signals only here, in ready(), never at module level
        import apps.orders.signals  # noqa: F401

Building a Reusable, Packageable App

Here's how to structure an app so it can be lifted out of your project and published to PyPI or shared across your organisation's internal projects:

# django_notifications/apps.py
from django.apps import AppConfig


class NotificationsConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name  = "django_notifications"
    label = "notifications"
    verbose_name = "Notifications"

    # Configurable via project settings
    # Usage in consuming project: NOTIFICATIONS_EMAIL_BACKEND = "sendgrid"
    def ready(self):
        from django_notifications import checks  # noqa: F401
        import django_notifications.signals       # noqa: F401


# django_notifications/conf.py
from django.conf import settings

DEFAULTS = {
    "EMAIL_BACKEND": "django",   # or "sendgrid", "ses"
    "SMS_BACKEND": None,
    "RETENTION_DAYS": 30,
}

class NotificationsSettings:
    def __getattr__(self, name):
        if name not in DEFAULTS:
            raise AttributeError(f"Invalid setting: {name}")
        user_settings = getattr(settings, "NOTIFICATIONS", {})
        return user_settings.get(name, DEFAULTS[name])

app_settings = NotificationsSettings()

# pyproject.toml for a publishable Django app
[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.backends.legacy:build"

[project]
name = "django-my-notifications"
version = "1.0.0"
description = "A reusable Django notifications app"
requires-python = ">=3.11"
dependencies = [
    "Django>=4.2",
]
classifiers = [
    "Framework :: Django",
    "Framework :: Django :: 5.0",
    "Programming Language :: Python :: 3.11",
]

[project.urls]
Homepage = "https://github.com/yourorg/django-my-notifications"

System Checks: App-Level Validation at Startup

Apps can register system checks that run during python manage.py check. This is how Django built-in apps validate their configuration:

# apps/payments/checks.py
from django.core.checks import Error, Warning, register


@register()
def check_stripe_settings(app_configs, **kwargs):
    """
    Validate required payment settings at startup,
    not at runtime when a customer is trying to pay.
    """
    from django.conf import settings
    errors = []

    if not getattr(settings, "STRIPE_SECRET_KEY", None):
        errors.append(
            Error(
                "STRIPE_SECRET_KEY is not set.",
                hint="Add STRIPE_SECRET_KEY to your settings.",
                obj=settings,
                id="payments.E001",
            )
        )

    if not getattr(settings, "STRIPE_WEBHOOK_SECRET", None):
        errors.append(
            Warning(
                "STRIPE_WEBHOOK_SECRET is not set.",
                hint="Webhook signature verification will be disabled.",
                obj=settings,
                id="payments.W001",
            )
        )

    return errors

# apps/payments/apps.py
from django.apps import AppConfig

class PaymentsConfig(AppConfig):
    name  = "apps.payments"
    label = "payments"

    def ready(self):
        from apps.payments import checks  # registers the check
        import apps.payments.signals

Performance Optimization

1. Lazy App Loading — Understand When Code Runs

AppConfig.ready() runs once, at startup, in the main process. Code here should be fast and should not make database calls or network requests. It's for registering signals, system checks, and in-process event handlers only.

# CORRECT: ready() registers signals, nothing else
def ready(self):
    import apps.orders.signals

# WRONG: database call in ready() — will fail and slow startup
def ready(self):
    from apps.users.models import User
    count = User.objects.count()  # ← Never do this in ready()
    print(f"Users: {count}")

2. Per-App Database Routing

When different apps have different scaling requirements, use Django's database router to send reads and writes to different databases:

# config/routers.py
class AppDatabaseRouter:
    """
    Routes read queries for the 'analytics' app to a read replica.
    All other apps use the default (primary) database.
    """
    ANALYTICS_APP = "analytics"
    READ_REPLICA  = "replica"

    def db_for_read(self, model, **hints):
        if model._meta.app_label == self.ANALYTICS_APP:
            return self.READ_REPLICA
        return None  # None = use default

    def db_for_write(self, model, **hints):
        return None  # Always write to default

    def allow_relation(self, obj1, obj2, **hints):
        return True

    def allow_migrate(self, db, app_label, **hints):
        if app_label == self.ANALYTICS_APP:
            return db == self.READ_REPLICA
        return db == "default"

# config/settings/production.py
DATABASE_ROUTERS = ["config.routers.AppDatabaseRouter"]

DATABASES = {
    "default": env.db("DATABASE_URL"),
    "replica": env.db("DATABASE_REPLICA_URL"),
}

3. Migration Performance — Squash by App

Long-running migrations are a production deployment risk. Squash migrations on a per-app basis to keep the migration graph lean:

# Squash all migrations for the orders app into one
python manage.py squashmigrations orders 0001 0042

# Squash migrations up to a specific date
python manage.py squashmigrations catalog 0001 0018 --squashed-name=initial_schema

4. App-Scoped Caching with Key Prefixes

Isolate each app's cache namespace to prevent key collisions and enable targeted cache invalidation:

# apps/catalog/cache.py
from django.core.cache import cache

APP_CACHE_PREFIX = "catalog"
PRODUCT_LIST_KEY = f"{APP_CACHE_PREFIX}:products:active:v2"
CATEGORY_KEY     = f"{APP_CACHE_PREFIX}:categories:v1"


def get_cached_active_products():
    result = cache.get(PRODUCT_LIST_KEY)
    if result is None:
        from apps.catalog.selectors import get_active_products
        result = list(get_active_products().values("id", "name", "slug", "price"))
        cache.set(PRODUCT_LIST_KEY, result, timeout=3600)
    return result


def invalidate_product_cache():
    """Call this from admin save signals or management commands."""
    cache.delete_many([PRODUCT_LIST_KEY, CATEGORY_KEY])

Security Best Practices

1. App-Level Permission Classes

Each app should define its own permission classes rather than relying solely on global DRF settings:

# apps/orders/permissions.py
from rest_framework.permissions import BasePermission


class IsOrderOwner(BasePermission):
    """
    Object-level permission. Grants access only if the requesting
    user is the owner of the order.

    Always use this on order detail endpoints.
    Never rely on URL filtering alone — that's IDOR.
    """
    message = "You do not have permission to access this order."

    def has_object_permission(self, request, view, obj):
        return obj.user_id == request.user.id


class IsOrderOwnerOrAdmin(BasePermission):
    def has_object_permission(self, request, view, obj):
        return (
            obj.user_id == request.user.id
            or request.user.is_staff
        )

2. App-Scoped Model Managers for Data Isolation

Never trust raw querysets on multi-tenant data. Use custom managers that enforce ownership at the ORM layer:

# apps/orders/models.py
from django.db import models


class UserScopedManager(models.Manager):
    """
    A manager that always filters by the current user.
    Prevents IDOR by making it structurally impossible
    to query another user's data through this manager.
    """
    def for_user(self, user):
        return self.get_queryset().filter(user=user)

    def for_user_or_404(self, user, **kwargs):
        from django.shortcuts import get_object_or_404
        return get_object_or_404(self.for_user(user), **kwargs)


class Order(models.Model):
    # ...
    objects = UserScopedManager()

# Usage — impossible to accidentally access another user's orders:
orders = Order.objects.for_user(request.user)
order  = Order.objects.for_user_or_404(request.user, pk=42)

3. Per-App `SECRET_KEY` Rotation Strategy

Use separate secrets for different security contexts within your project:

# config/settings/production.py
import environ
env = environ.Env()

# Main Django secret key — for session signing, CSRF tokens
SECRET_KEY = env("SECRET_KEY")

# Separate signing key for password reset tokens
# Can be rotated without invalidating sessions
PASSWORD_RESET_SIGNING_KEY = env("PASSWORD_RESET_SIGNING_KEY")

# API token signing — separate from main key
API_TOKEN_SIGNING_KEY = env("API_TOKEN_SIGNING_KEY")

# apps/users/services.py
from django.core.signing import TimestampSigner, BadSignature, SignatureExpired
from django.conf import settings


class PasswordResetService:
    SIGNER = TimestampSigner(key=settings.PASSWORD_RESET_SIGNING_KEY, salt="password-reset")

    @classmethod
    def generate_token(cls, user) -> str:
        return cls.SIGNER.sign(str(user.pk))

    @classmethod
    def validate_token(cls, token: str, max_age_seconds: int = 3600) -> int:
        """Returns user_id or raises BadSignature/SignatureExpired."""
        value = cls.SIGNER.unsign(token, max_age=max_age_seconds)
        return int(value)

Common Developer Mistakes

❌ Mistake 1: The God App

# BAD — one app that does everything
apps/
└── main/
    ├── models.py    ← User, Product, Order, Payment, all in here
    ├── views.py     ← 3,000 lines, every endpoint
    └── urls.py      ← 200 URL patterns

# GOOD — each domain has its own app
apps/
├── users/
├── catalog/
├── orders/
└── payments/

If your models.py has more than ~10 model classes, or your views.py has more than ~20 view functions, your app is doing too much.

❌ Mistake 2: Circular App Imports

# BAD — circular import between apps
# apps/orders/models.py
from apps.users.models import User      # orders depends on users ✅

# apps/users/models.py
from apps.orders.models import Order   # users depends on orders ❌ — CIRCULAR

# GOOD — use ForeignKey string reference (lazy import)
# apps/orders/models.py
class Order(models.Model):
    user = models.ForeignKey(
        "users.User",         # ← string reference, no direct import
        on_delete=models.CASCADE
    )

❌ Mistake 3: Forgetting `app_label` on Abstract Models

# BAD — abstract model without app_label confuses migrations
class TimestampedModel(models.Model):
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True
        # Missing: no app_label issue for abstract, but concrete subclasses
        # need explicit app_label if they're in apps/ subdirectory

# GOOD — concrete models always declare app_label explicitly
class Order(TimestampedModel):
    class Meta(TimestampedModel.Meta):
        app_label = "orders"

❌ Mistake 4: Importing from Apps in `settings.py`

# BAD — importing from an app in settings.py causes early import errors
# config/settings/base.py
from apps.users.constants import DEFAULT_PERMISSIONS  # ← Django not ready yet!

# GOOD — reference by string, or use lazy imports inside functions
AUTH_USER_MODEL = "users.User"  # string reference — safe

❌ Mistake 5: Putting Business Logic in `apps.py` `ready()`

# BAD — database call in ready()
class OrdersConfig(AppConfig):
    def ready(self):
        from apps.orders.models import Order
        Order.objects.filter(status="stuck").update(status="pending")  # ❌

# GOOD — ready() is for signal registration only
class OrdersConfig(AppConfig):
    def ready(self):
        import apps.orders.signals  # ✅

❌ Mistake 6: Duplicate App Labels

# BAD — two apps with the same label
INSTALLED_APPS = [
    "apps.v1.payments.apps.PaymentsConfig",  # label = "payments"
    "apps.v2.payments.apps.PaymentsConfig",  # label = "payments" ← COLLISION
]

# GOOD — give each a unique label in AppConfig
class PaymentsV2Config(AppConfig):
    name  = "apps.v2.payments"
    label = "payments_v2"      # ← unique

Real Production Use Cases

Use Case 1: E-Commerce Platform — 6 Apps, Clean Boundaries

apps/
├── users/          → Authentication, profiles, addresses
├── catalog/        → Products, categories, variants, inventory
├── orders/         → Cart, checkout, order lifecycle, fulfillment
├── payments/       → Stripe integration, invoices, refunds
├── shipping/       → Carrier integration, tracking, labels
└── notifications/  → Email (SES), SMS (Twilio), push notifications

Cross-app communication pattern:

User places order
    ↓
orders.views.CheckoutView
    ↓ calls
orders.services.OrderService.create()  ← business logic
    ↓ creates Order, fires post_save signal
    ↓
orders.signals.on_order_created()
    ↓ uses transaction.on_commit to defer:
    ├── payments.tasks.charge_card.delay()
    ├── inventory.tasks.reserve_stock.delay()
    └── notifications.tasks.send_confirmation.delay()

No app imports another app's internal models or services directly. All cross-app communication is through signals and Celery tasks.

Use Case 2: SaaS Multi-Tenant — Shared App, Project-Level Config

A tenancy app is built once and shared across three separate Django projects (three different SaaS products in the same organisation):

# Package: django-company-tenancy (internal PyPI)
# apps/tenancy/models.py

class Tenant(models.Model):
    name     = models.CharField(max_length=255)
    domain   = models.CharField(max_length=255, unique=True)
    plan     = models.CharField(max_length=50)
    is_active = models.BooleanField(default=True)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        app_label = "tenancy"

# Each project's requirements/base.txt
django-company-tenancy==2.3.1   # ← reusable app, versioned

Use Case 3: Microservice Extraction — App Becomes a Service

An organisation's notifications app starts as part of a monolith. As it grows:

It's first extracted into a standalone django-internal-notifications package (reusable app)
Later, it becomes a fully separate Django project (microservice) with its own database and API
The other apps that previously sent signals now call the notifications API over HTTP

This migration is only possible because the notifications app was built with clean boundaries from day one — no circular imports, no shared models with other apps, all cross-app communication through signals and tasks.

Use Case 4: Open-Source App — From Internal to PyPI

# Structure for a publishable Django app
django-audit-log/
├── django_audit_log/             ← the app package
│   ├── __init__.py
│   ├── apps.py
│   ├── models.py
│   ├── middleware.py
│   ├── migrations/
│   └── tests/
├── tests/                        ← project-level tests for the package
│   ├── settings.py               ← minimal test project settings
│   └── test_middleware.py
├── pyproject.toml
├── README.md
└── CHANGELOG.md

# tests/settings.py — minimal settings for testing the app in isolation
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": ":memory:",
    }
}

INSTALLED_APPS = [
    "django.contrib.contenttypes",
    "django.contrib.auth",
    "django_audit_log",           # ← only the app being tested
]

DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
SECRET_KEY = "test-secret-key-not-for-production"

Conclusion

The distinction between a Django project and a Django app is one of the framework's most powerful design decisions — and one of the most consistently underutilised by developers who treat it as mere file organisation.

A project is configuration. It knows where the database lives, what middleware runs, which apps are installed, and how the environment is configured. It is specific, environment-aware, and non-reusable.

An app is behaviour. It owns a single, cohesive domain of responsibility. It is portable, testable in isolation, independently maintainable, and — when built well — reusable across multiple projects.

Keep each app focused on one domain concept to avoid a god app. Put reusable utilities in a common package rather than sprinkling helpers across apps.

The production patterns in this guide — directed dependency graphs, signal-based inter-app communication, custom managers, AppConfig system checks, reusable app packaging — all follow from one principle: an app should be able to stand alone. If it can stand alone, it can be reasoned about. If it can be reasoned about, it can be tested, maintained, scaled, and eventually extracted.

Build your next Django application with this in mind, and the code you ship today will still be navigable, extensible, and maintainable in two years.

That's the real difference between an app and a project — and between a codebase that ages well and one that doesn't.

How Django Works Internally: The Complete Request Response Cycle

Alanso Mathew — Sat, 14 Mar 2026 14:32:57 +0000

A backend engineer's deep dive into what actually happens inside Django — from the moment a client sends a byte to the moment your server writes one back.

Originally published at:https://alansomathewdev.blogspot.com/2026/03/how-django-works-internally-complete.html

Introduction
Why This Matters in Production Systems
Core Concepts
Architecture Design
Step-by-Step Implementation
Code Examples
Performance Optimization
Security Best Practices
Common Developer Mistakes
Real Production Use Cases
Conclusion

Introduction

Every time a user clicks a link in a Django-powered application, a chain reaction begins. A packet leaves their browser, travels the internet, reaches a server, is unwrapped by Nginx, passed to Gunicorn, handed to Django, threaded through middleware, matched against URL patterns, handed to a view, which queries a database through the ORM, renders a template, packages a response, and sends it back the same way it came — all in under 100 milliseconds if you're good at your job.

Most Django developers can build views, write models, configure URLs, and ship features. Far fewer can explain — with precision — what happens between the HTTP request arriving and the response leaving. That knowledge gap is exactly where production bugs hide, where performance bottlenecks live, and where security vulnerabilities breed.

This article changes that.

We're going to tear the entire Django request/response cycle open and look at every layer: WSGI and ASGI, the middleware stack, the URL dispatcher, the view layer, the ORM, the template engine, and the response pipeline. We'll look at the actual Django source code, build production-grade examples, and cover the optimization and security techniques that separate good Django developers from great ones.

Whether you're a beginner learning what "MVT architecture" actually means in practice, or a senior engineer who's been shipping Django apps for years and wants a crisp mental model, this is the guide you've been looking for.

Let's go.

Why This Matters in Production Systems

You might be thinking: "I ship features with Django every day. Why do I need to know its internals?"

Here's why.

Performance. The difference between a 50ms response and a 3-second response is almost always found somewhere in the request/response cycle. Is it a middleware doing a synchronous database call? A view fetching 200 related objects without select_related? A template rendering thousands of rows? You can't fix what you can't see.

Debugging. "A 500 error appears randomly in production but never in development." Nine times out of ten, the answer lives in the middleware stack or the ORM query layer. Knowing the cycle tells you exactly where to look.

Security. Django's security features — CSRF protection, session handling, clickjacking prevention, SQL injection protection — are all implemented as middleware or ORM abstractions. Understanding where they live tells you what's protected, what isn't, and what you can accidentally bypass.

Architecture decisions. When should you use middleware vs a decorator on a view? When does an ASGI setup outperform WSGI? When should you use StreamingHttpResponse? These decisions require understanding the mechanics.

Scaling. When you need to scale a Django application to thousands of concurrent requests, you need to know where the bottlenecks are by design — not by accident.

This knowledge is the foundation everything else is built on.

Core Concepts

Before we trace a request end-to-end, we need to establish the vocabulary. These are the building blocks.

WSGI: The Contract Between Server and Framework

WSGI (Web Server Gateway Interface, defined in PEP 3333) is the standard that allows Python web frameworks like Django to talk to web servers like Gunicorn, uWSGI, or Apache mod_wsgi.

The contract is simple:

The server calls your application as a callable with two arguments: environ (a dict of CGI-style environment variables) and start_response (a callback)
Your application processes the request and returns an iterable of byte strings as the response body

Django's WSGI entry point is in wsgi.py:

# project/wsgi.py
import os
from django.core.wsgi import get_wsgi_application

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings.production')

application = get_wsgi_application()

This application callable is the gatekeeper. Everything that happens inside Django starts here.

ASGI: The Async Evolution

ASGI (Asynchronous Server Gateway Interface) is the spiritual successor to WSGI, introduced in Django 3.0. It extends the contract to support asynchronous code, WebSockets, long-polling, and server-sent events.

# project/asgi.py
import os
from django.core.asgi import get_asgi_application

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings.production')

application = get_asgi_application()

The key difference: under WSGI, a worker thread is blocked for the entire duration of the request. Under ASGI with an async server like Uvicorn or Daphne, a single thread can handle thousands of concurrent connections by yielding control during I/O waits.

The MVT Pattern

Django uses the Model-View-Template (MVT) pattern. It maps to MVC like this:

MVC             Django MVT
─────────────   ──────────────────────────────
Model       →   Model     (models.py)
Controller  →   View      (views.py)
View        →   Template  (templates/*.html)

Despite the naming confusion, the concept is identical. Models define data structure and database interaction. Views contain business logic and orchestration. Templates handle presentation.

The Middleware Onion

Middleware is the most misunderstood concept in Django. The mental model that makes it click is the onion:

Request →  [SecurityMiddleware]
       →  [SessionMiddleware]
       →  [CommonMiddleware]
       →  [CsrfViewMiddleware]
       →  [AuthenticationMiddleware]
       →  [MessageMiddleware]
       →  [XFrameOptionsMiddleware]
              ↓
           [URL Dispatcher]
              ↓
           [View Function]
              ↓
       ←  [XFrameOptionsMiddleware]
       ←  [MessageMiddleware]
       ←  [AuthenticationMiddleware]
       ←  [CsrfViewMiddleware]
       ←  [CommonMiddleware]
       ←  [SessionMiddleware]
       ←  [SecurityMiddleware]
← Response

The request enters from the outside, travels inward through each middleware layer, hits the view at the center, and the response travels back through each middleware in reverse order. Each middleware can:

Inspect or modify the request before passing it on
Short-circuit the entire stack by returning a response early
Inspect or modify the response on the way back out
Handle exceptions thrown anywhere inside it

Architecture Design

Here is the complete architecture of a production Django deployment, from client to database and back:

CLIENT (Browser / Mobile / API Consumer)
    │
    │ HTTP/HTTPS Request
    ▼
┌─────────────────────────────────────────┐
│           NGINX (Reverse Proxy)          │
│  - SSL termination                       │
│  - Static file serving                   │
│  - Load balancing                        │
│  - Rate limiting                         │
└──────────────────┬──────────────────────┘
                   │ Proxied Request
                   ▼
┌─────────────────────────────────────────┐
│         GUNICORN (WSGI Server)           │
│  - Worker process management             │
│  - Concurrency model (sync workers)      │
│  - Request queuing                       │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│          DJANGO APPLICATION              │
│                                          │
│  wsgi.py / asgi.py                       │
│       │                                  │
│       ▼                                  │
│  settings.py (loaded once at startup)    │
│       │                                  │
│       ▼                                  │
│  ┌─────────────────────────────────┐     │
│  │      MIDDLEWARE STACK           │     │
│  │  SecurityMiddleware             │     │
│  │  SessionMiddleware              │     │
│  │  CommonMiddleware               │     │
│  │  CsrfViewMiddleware             │     │
│  │  AuthenticationMiddleware       │     │
│  └──────────────┬──────────────────┘     │
│                 │                        │
│                 ▼                        │
│  ┌─────────────────────────────────┐     │
│  │       URL DISPATCHER            │     │
│  │  ROOT_URLCONF → urls.py         │     │
│  │  include() chaining             │     │
│  │  Named URL patterns             │     │
│  └──────────────┬──────────────────┘     │
│                 │                        │
│                 ▼                        │
│  ┌─────────────────────────────────┐     │
│  │       VIEW LAYER                │     │
│  │  FBV or CBV                     │     │
│  │  Calls Services/Selectors       │     │
│  │  Calls ORM                      │     │
│  │  Renders Templates              │     │
│  └──────────────┬──────────────────┘     │
│                 │                        │
│                 ▼                        │
│  ┌────────────────────────────────┐      │
│  │     Django ORM Layer           │      │
│  │  QuerySet  →  SQL              │      │
│  │  Model Managers                │      │
│  └──────────────┬─────────────────┘      │
│                 │                        │
└─────────────────┼────────────────────────┘
                  │ SQL Queries
                  ▼
┌─────────────────────────────────────────┐
│         PostgreSQL / MySQL               │
│         (Primary Database)              │
└─────────────────────────────────────────┘
                  │ + Cache Layer
                  ▼
┌─────────────────────────────────────────┐
│     Redis (Cache + Sessions + Celery)    │
└─────────────────────────────────────────┘

Every production Django deployment follows this architecture. Let's now trace a single request through every layer of it.

Step-by-Step Implementation

Step 1: The Client Sends a Request

A user types https://myapp.com/api/orders/42/ into their browser. The browser resolves DNS, establishes a TLS connection, and sends:

GET /api/orders/42/ HTTP/1.1
Host: myapp.com
Authorization: Bearer eyJ0eXAiOiJKV1Q...
Accept: application/json

Step 2: Nginx Receives and Proxies the Request

Nginx terminates TLS, inspects the request path, and proxies it to Gunicorn via a Unix socket or TCP port:

# /etc/nginx/sites-available/myapp
upstream django_app {
    server unix:/run/gunicorn/myapp.sock fail_timeout=0;
}

server {
    listen 443 ssl;
    server_name myapp.com;

    # Serve static files directly — never hit Django for these
    location /static/ {
        alias /var/www/myapp/static/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    location /media/ {
        alias /var/www/myapp/media/;
    }

    # Everything else goes to Django
    location / {
        proxy_pass http://django_app;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Why Nginx in front of Gunicorn? Nginx is vastly more efficient at handling slow clients, serving static files, and managing connection queues. Gunicorn workers are precious synchronous processes — you don't want them blocked waiting for a slow client to download a response.

Step 3: Gunicorn Passes to Django's WSGI Handler

Gunicorn translates the raw HTTP request into a WSGI environ dict and calls Django's application callable. The WSGIHandler class in django.core.handlers.wsgi takes over.

What WSGIHandler does at startup (not per-request):

Loads settings.py
Instantiates all middleware classes in MIDDLEWARE order
Builds the middleware chain as a series of nested callables

What it does per-request:

Wraps the WSGI environ into an HttpRequest object
Calls the outermost middleware with the request

Step 4: The Request Traverses the Middleware Stack

This is where Django's first real work happens. Each middleware in settings.MIDDLEWARE is called in order:

# config/settings/base.py
MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",         # 1st inbound
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware", # 7th inbound
]

Notable things each built-in middleware does:

Middleware	Inbound (request)	Outbound (response)
`SecurityMiddleware`	Enforces HTTPS redirect, sets HSTS	Adds security headers
`SessionMiddleware`	Loads session from cookie/DB	Saves modified session data
`CommonMiddleware`	URL normalisation (trailing slashes)	Sets `Content-Length`
`CsrfViewMiddleware`	Validates CSRF token on unsafe methods	Sets CSRF cookie
`AuthenticationMiddleware`	Attaches `request.user` from session	—
`MessageMiddleware`	Attaches message storage backend	Saves messages to storage
`XFrameOptionsMiddleware`	—	Sets `X-Frame-Options` header

Step 5: URL Resolution

After the middleware inbound pass, Django's URL resolver takes over. It reads ROOT_URLCONF from settings, loads your root urls.py, and walks the URL patterns until it finds a match for /api/orders/42/:

# config/urls.py
from django.urls import path, include

urlpatterns = [
    path("admin/", admin.site.urls),
    path("api/", include("apps.api.urls")),
]

# apps/api/urls.py
from django.urls import path
from apps.orders.views import OrderDetailView

urlpatterns = [
    path("orders/<int:pk>/", OrderDetailView.as_view(), name="order-detail"),
]

Django's URL resolver uses regex internally but the path() function provides a cleaner converter syntax. <int:pk> means: match a sequence of digits, convert to int, and pass as keyword argument pk to the view.

If no URL pattern matches, Django raises Http404. This is caught either by the 404 handler or by middleware's exception handling, and returns a 404 Not Found response.

Step 6: The View Is Called

The URL resolver returns a callable (the view) and calls it with (request, pk=42). The view does the application work:

# apps/orders/views.py
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status

from apps.orders.selectors import get_order_for_user
from apps.orders.serializers import OrderDetailSerializer

class OrderDetailView(APIView):
    def get(self, request, pk: int):
        order = get_order_for_user(user=request.user, order_id=pk)
        serializer = OrderDetailSerializer(order)
        return Response(serializer.data)

The view must return an HttpResponse (or a subclass, like DRF's Response). If it doesn't, Django raises an error.

Step 7: The ORM Queries the Database

The selector calls the ORM, which translates Python into SQL:

# apps/orders/selectors.py
from apps.orders.models import Order
from django.shortcuts import get_object_or_404

def get_order_for_user(user, order_id: int) -> Order:
    return get_object_or_404(
        Order.objects
        .select_related("user", "shipping_address")
        .prefetch_related("items__product"),
        pk=order_id,
        user=user,
    )

Django's ORM translates this into roughly:

SELECT
    orders_order.*,
    auth_user.*,
    orders_address.*
FROM orders_order
INNER JOIN auth_user ON orders_order.user_id = auth_user.id
LEFT JOIN orders_address ON orders_order.shipping_address_id = orders_address.id
WHERE orders_order.id = 42
  AND orders_order.user_id = 7;

Followed by a second query to prefetch order items:

SELECT orders_orderitem.*, catalog_product.*
FROM orders_orderitem
INNER JOIN catalog_product ON orders_orderitem.product_id = catalog_product.id
WHERE orders_orderitem.order_id IN (42);

Two queries. No N+1.

Step 8: The Response Travels Back Through Middleware

The view returns an HttpResponse. Django passes it back through the middleware stack in reverse order. Each middleware can inspect or modify the response before it reaches the client.

SecurityMiddleware adds security headers. SessionMiddleware saves any session data changes. XFrameOptionsMiddleware sets X-Frame-Options: DENY.

Step 9: The WSGI Handler Returns to Gunicorn

WSGIHandler calls start_response with the status code and headers, then returns the response body as an iterable. Gunicorn sends it to Nginx. Nginx sends it to the client.

Total round trip: ~40ms on a well-optimized setup.

Code Examples

Custom Middleware: Request Timing

# common/middleware/timing.py
import time
import logging

logger = logging.getLogger(__name__)

class RequestTimingMiddleware:
    """
    Logs the duration of every request.
    Attach to MIDDLEWARE after SecurityMiddleware.
    """
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        start_time = time.perf_counter()

        response = self.get_response(request)  # Call the rest of the stack

        duration_ms = (time.perf_counter() - start_time) * 1000
        response["X-Request-Duration-Ms"] = str(round(duration_ms, 2))

        logger.info(
            "request_completed",
            extra={
                "method": request.method,
                "path": request.path,
                "status": response.status_code,
                "duration_ms": round(duration_ms, 2),
                "user_id": getattr(request.user, "id", None),
            },
        )
        return response

Custom Middleware: JWT Authentication

# common/middleware/jwt_auth.py
from django.contrib.auth.models import AnonymousUser
from apps.users.services import UserAuthService

class JWTAuthMiddleware:
    """
    Attaches the authenticated user to the request from a Bearer token.
    Works alongside DRF's authentication classes for non-API routes.
    """
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        auth_header = request.META.get("HTTP_AUTHORIZATION", "")

        if auth_header.startswith("Bearer "):
            token = auth_header.split(" ", 1)[1]
            user = UserAuthService.get_user_from_token(token)
            request.user = user if user else AnonymousUser()

        return self.get_response(request)

Custom URL Converter

# common/converters.py
class UUIDConverter:
    """
    Custom URL converter for UUID-based primary keys.
    Usage: path("resources/<uuid:pk>/", view)
    """
    regex = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"

    def to_python(self, value: str):
        import uuid
        return uuid.UUID(value)

    def to_url(self, value) -> str:
        return str(value)

# config/urls.py
from django.urls import register_converter, path
from common.converters import UUIDConverter

register_converter(UUIDConverter, "uuid")

urlpatterns = [
    path("resources/<uuid:pk>/", ResourceDetailView.as_view()),
]

Class-Based View with Full HTTP Method Handling

# apps/orders/views.py
from django.http import HttpRequest, JsonResponse
from django.views import View
from django.utils.decorators import method_decorator
from django.views.decorators.cache import cache_page
from django.contrib.auth.decorators import login_required

from apps.orders.selectors import get_order_for_user, get_orders_for_user
from apps.orders.services import OrderService
from apps.orders.serializers import OrderSerializer


@method_decorator(login_required, name="dispatch")
class OrderView(View):
    """
    Handles listing and creating orders.
    GET  /api/orders/     → list orders for the authenticated user
    POST /api/orders/     → create a new order
    """

    @method_decorator(cache_page(60 * 5))  # cache 5 minutes
    def get(self, request: HttpRequest) -> JsonResponse:
        orders = get_orders_for_user(user_id=request.user.id)
        data = OrderSerializer(orders, many=True).data
        return JsonResponse({"results": data, "count": len(data)})

    def post(self, request: HttpRequest) -> JsonResponse:
        import json
        body = json.loads(request.body)
        order = OrderService.create_order(user=request.user, **body)
        return JsonResponse(
            {"id": order.id, "status": order.status},
            status=201
        )

The Complete Model Layer

# apps/orders/models.py
from django.db import models
from django.contrib.auth import get_user_model

User = get_user_model()


class Order(models.Model):
    class Status(models.TextChoices):
        PENDING    = "pending",    "Pending"
        PROCESSING = "processing", "Processing"
        SHIPPED    = "shipped",    "Shipped"
        DELIVERED  = "delivered",  "Delivered"
        CANCELLED  = "cancelled",  "Cancelled"

    user             = models.ForeignKey(User, on_delete=models.CASCADE, related_name="orders")
    status           = models.CharField(max_length=20, choices=Status.choices, default=Status.PENDING)
    shipping_address = models.ForeignKey("ShippingAddress", on_delete=models.SET_NULL, null=True)
    total            = models.DecimalField(max_digits=10, decimal_places=2)
    created_at       = models.DateTimeField(auto_now_add=True)
    updated_at       = models.DateTimeField(auto_now=True)

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

    def __str__(self):
        return f"Order #{self.pk} — {self.user.email} ({self.status})"


class OrderItem(models.Model):
    order    = models.ForeignKey(Order, on_delete=models.CASCADE, related_name="items")
    product  = models.ForeignKey("catalog.Product", on_delete=models.PROTECT)
    quantity = models.PositiveIntegerField()
    price    = models.DecimalField(max_digits=10, decimal_places=2)

    class Meta:
        constraints = [
            models.CheckConstraint(check=models.Q(quantity__gt=0), name="positive_quantity"),
        ]

Signal-Based Post-Processing

# apps/orders/signals.py
from django.db.models.signals import post_save
from django.dispatch import receiver
from apps.orders.models import Order
from apps.orders.tasks import send_order_confirmation_email

@receiver(post_save, sender=Order)
def order_created_handler(sender, instance: Order, created: bool, **kwargs):
    """
    After an Order is created, dispatch a Celery task to send
    a confirmation email. This runs AFTER the transaction commits,
    keeping the request cycle fast.
    """
    if created:
        # Use transaction.on_commit to ensure this only fires
        # after the DB transaction is actually committed.
        from django.db import transaction
        transaction.on_commit(
            lambda: send_order_confirmation_email.delay(instance.id)
        )

Performance Optimization

1. Eliminate N+1 Queries with `select_related` and `prefetch_related`

The N+1 problem is the most common performance killer in Django. It happens when you access a related object inside a loop without preloading it:

# BAD — generates N+1 queries
orders = Order.objects.all()
for order in orders:
    print(order.user.email)   # Each iteration hits the database
    for item in order.items.all():  # Another query per order
        print(item.product.name)    # Another query per item

# GOOD — 3 queries total, regardless of order count
orders = (
    Order.objects
    .select_related("user", "shipping_address")    # JOIN — for ForeignKey/OneToOne
    .prefetch_related("items__product")             # Separate batched query — for M2M/reverse FK
    .only("id", "status", "total", "created_at")   # Defer unneeded columns
)

Use assertNumQueries in tests to enforce your query budget:

# apps/orders/tests/test_selectors.py
from django.test import TestCase
from apps.orders.selectors import get_orders_for_user

class TestOrderSelectors(TestCase):
    def test_order_list_query_count(self):
        # Ensure the selector never generates more than 3 queries,
        # regardless of how many orders or items exist.
        with self.assertNumQueries(3):
            list(get_orders_for_user(user_id=self.user.id))

2. Use Django's Caching Framework

# apps/catalog/selectors.py
from django.core.cache import cache
from django.utils.functional import cached_property

CATEGORY_CACHE_KEY = "active_categories_v2"
CATEGORY_CACHE_TTL = 60 * 60  # 1 hour

def get_active_categories():
    """
    Categories rarely change. Cache aggressively.
    Invalidate the cache key in the admin save signal.
    """
    result = cache.get(CATEGORY_CACHE_KEY)
    if result is None:
        result = list(
            Category.objects
            .filter(is_active=True)
            .values("id", "name", "slug")
            .order_by("name")
        )
        cache.set(CATEGORY_CACHE_KEY, result, timeout=CATEGORY_CACHE_TTL)
    return result


# Per-view caching with cache_page decorator
from django.views.decorators.cache import cache_page

@cache_page(60 * 15)  # Cache for 15 minutes
def product_list(request):
    ...

Settings for Redis-backed caching:

# config/settings/production.py
CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": env("REDIS_URL"),
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
        },
        "KEY_PREFIX": "myapp",
        "TIMEOUT": 300,
    }
}

# Use Redis for sessions too — eliminates session DB queries
SESSION_ENGINE = "django.contrib.sessions.backends.cache"
SESSION_CACHE_ALIAS = "default"

3. Database Indexing Strategy

Indexes are the single most impactful database optimization:

class Order(models.Model):
    # ...

    class Meta:
        indexes = [
            # Composite index for the most common query pattern:
            # "find all orders for this user with this status"
            models.Index(fields=["user", "status"], name="idx_order_user_status"),

            # Descending index for the default ordering
            models.Index(fields=["-created_at"], name="idx_order_created_at_desc"),
        ]

        # Partial index (PostgreSQL only): only index non-cancelled orders
        # This is a small index that serves the hottest query path
        constraints = [
            # Not an index, but worth noting for data integrity
            models.UniqueConstraint(
                fields=["user", "external_reference"],
                name="unique_user_order_reference"
            )
        ]

For PostgreSQL-specific optimizations, run EXPLAIN ANALYZE on slow queries:

# In Django shell, inspect the SQL and query plan
from django.db import connection
from apps.orders.selectors import get_orders_for_user

qs = get_orders_for_user(user_id=1)

# See the generated SQL
print(qs.query)

# Run EXPLAIN ANALYZE
with connection.cursor() as cursor:
    cursor.execute(f"EXPLAIN ANALYZE {qs.query}")
    for row in cursor.fetchall():
        print(row[0])

4. Gunicorn Configuration for Production

# gunicorn.conf.py
import multiprocessing

# Number of worker processes
# Rule of thumb: (2 × CPU cores) + 1
workers = multiprocessing.cpu_count() * 2 + 1

# Worker class — use sync for CPU-bound, gevent/uvicorn for I/O-bound
worker_class = "sync"

# Worker timeout — kill and restart if a worker doesn't respond
timeout = 30

# Connection queue size
backlog = 2048

# Keep-alive connections
keepalive = 5

# Logging
accesslog = "-"    # stdout
errorlog  = "-"    # stderr
loglevel  = "info"

# Graceful shutdown timeout
graceful_timeout = 30

# Preload application (loads Django once, then forks)
# Reduces memory usage via copy-on-write, but loses graceful reload
preload_app = True

5. Database Connection Pooling

By default, Django creates a new database connection per request and closes it after. This is expensive. Use pgBouncer in production, or configure CONN_MAX_AGE:

# config/settings/production.py
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": env("DB_NAME"),
        "USER": env("DB_USER"),
        "PASSWORD": env("DB_PASSWORD"),
        "HOST": env("DB_HOST"),
        "PORT": env("DB_PORT", default="5432"),

        # Reuse database connections for up to 60 seconds
        # This is the single-line change that eliminates connection overhead
        "CONN_MAX_AGE": 60,

        "OPTIONS": {
            "connect_timeout": 5,
            "options": "-c default_transaction_isolation=read committed",
        },
    }
}

Security Best Practices

1. Understand What Django Protects (and What It Doesn't)

Django's built-in security layer is substantial, but it has boundaries. Know where they are.

Automatically protected by Django:

SQL Injection → The ORM parameterises all queries. Never use .raw() with user input unless you also parameterise it.
CSRF → CsrfViewMiddleware validates the CSRF token on all non-safe HTTP methods (POST, PUT, PATCH, DELETE).
XSS → The template engine auto-escapes HTML by default. Using {{ variable }} in templates is safe.
Clickjacking → XFrameOptionsMiddleware sets X-Frame-Options: DENY.

What you must handle yourself:

Broken object-level authorization (BOLA/IDOR) → Always filter querysets by the authenticated user. Never trust a URL parameter without checking ownership.
Mass assignment → Always use serializer field whitelisting. Never pass request.data or request.POST directly to a model.
Sensitive data in logs → Your RequestTimingMiddleware should never log request bodies or authorization headers.

2. Security Settings Checklist

# config/settings/production.py

# HTTPS enforcement
SECURE_SSL_REDIRECT = True
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")

# HSTS — tells browsers to only ever use HTTPS for your domain
SECURE_HSTS_SECONDS = 31536000         # 1 year
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_HSTS_PRELOAD = True

# Cookies
SESSION_COOKIE_SECURE = True           # Only send session cookie over HTTPS
SESSION_COOKIE_HTTPONLY = True         # JS cannot read session cookie
SESSION_COOKIE_SAMESITE = "Lax"        # CSRF protection for session cookie
CSRF_COOKIE_SECURE = True
CSRF_COOKIE_HTTPONLY = True

# Content security
SECURE_CONTENT_TYPE_NOSNIFF = True     # X-Content-Type-Options: nosniff
X_FRAME_OPTIONS = "DENY"

# Never expose debug info in production
DEBUG = False
ALLOWED_HOSTS = ["myapp.com", "www.myapp.com"]

3. Prevent IDOR (Insecure Direct Object Reference)

# BAD — any authenticated user can access any order by ID
def get_order(request, pk):
    order = get_object_or_404(Order, pk=pk)  # ← IDOR vulnerability
    ...

# GOOD — always scope to the authenticated user
def get_order(request, pk):
    order = get_object_or_404(Order, pk=pk, user=request.user)  # ← safe
    ...

# In selectors, always require user context:
def get_order_for_user(user, order_id: int) -> Order:
    return get_object_or_404(
        Order.objects.filter(user=user),
        pk=order_id
    )

4. Rate Limiting Middleware

# common/middleware/rate_limit.py
import time
from django.core.cache import cache
from django.http import JsonResponse


class RateLimitMiddleware:
    """
    Simple sliding-window rate limiter using Redis.
    1000 requests per IP per hour for anonymous users.
    10000 requests per user per hour for authenticated users.
    """
    ANON_LIMIT  = 1000
    AUTH_LIMIT  = 10000
    WINDOW_SECS = 3600  # 1 hour

    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        key, limit = self._get_key_and_limit(request)
        count = cache.get(key, 0)

        if count >= limit:
            return JsonResponse(
                {"error": "Rate limit exceeded. Try again later."},
                status=429,
                headers={"Retry-After": str(self.WINDOW_SECS)},
            )

        # Increment with TTL
        cache.set(key, count + 1, timeout=self.WINDOW_SECS)

        response = self.get_response(request)
        response["X-RateLimit-Remaining"] = str(limit - count - 1)
        return response

    def _get_key_and_limit(self, request):
        window = int(time.time() // self.WINDOW_SECS)
        if request.user.is_authenticated:
            return f"rl:user:{request.user.id}:{window}", self.AUTH_LIMIT
        ip = request.META.get("HTTP_X_FORWARDED_FOR", request.META["REMOTE_ADDR"])
        return f"rl:ip:{ip}:{window}", self.ANON_LIMIT

Common Developer Mistakes

❌ Mistake 1: Querying the Database in Middleware

# BAD — runs a DB query on EVERY request
class TenantMiddleware:
    def __call__(self, request):
        hostname = request.get_host()
        request.tenant = Tenant.objects.get(domain=hostname)  # DB hit every time!
        return self.get_response(request)

# GOOD — cache the tenant lookup
class TenantMiddleware:
    def __call__(self, request):
        hostname = request.get_host()
        cache_key = f"tenant:{hostname}"
        tenant = cache.get(cache_key)
        if tenant is None:
            tenant = Tenant.objects.get(domain=hostname)
            cache.set(cache_key, tenant, timeout=300)
        request.tenant = tenant
        return self.get_response(request)

❌ Mistake 2: Fat Views with Business Logic

# BAD — testing this requires an HTTP client
def create_order(request):
    product = Product.objects.get(id=request.POST["product_id"])
    if product.stock < int(request.POST["quantity"]):
        return JsonResponse({"error": "Out of stock"}, status=400)
    order = Order.objects.create(user=request.user, ...)
    product.stock -= int(request.POST["quantity"])
    product.save()
    send_mail("Order confirmed", ..., [request.user.email])
    return JsonResponse({"id": order.id})

# GOOD — views are thin HTTP adapters; logic is in services
def create_order(request):
    serializer = CreateOrderSerializer(data=request.POST)
    serializer.is_valid(raise_exception=True)
    order = OrderService.create_order(user=request.user, **serializer.validated_data)
    return JsonResponse({"id": order.id}, status=201)

❌ Mistake 3: Forgetting `transaction.on_commit`

# BAD — Celery task runs BEFORE the DB transaction commits
# If the task runs before the commit, it won't find the Order row
@receiver(post_save, sender=Order)
def on_order_created(sender, instance, created, **kwargs):
    if created:
        send_confirmation_email.delay(instance.id)  # Race condition!

# GOOD — wait for the transaction to commit
@receiver(post_save, sender=Order)
def on_order_created(sender, instance, created, **kwargs):
    if created:
        transaction.on_commit(
            lambda: send_confirmation_email.delay(instance.id)
        )

❌ Mistake 4: Using `DEBUG = True` Without Understanding the Cost

With DEBUG = True, Django stores the full details of every SQL query in memory for the duration of the process. In production, this is a memory leak that grows until the process is restarted. Always, always, always set DEBUG = False in production.

❌ Mistake 5: Ignoring `CONN_MAX_AGE`

# BAD — default Django behaviour: new DB connection per request
DATABASES = {"default": env.db("DATABASE_URL")}

# GOOD — reuse connections for up to 60 seconds
DATABASES = {
    "default": {
        **env.db("DATABASE_URL"),
        "CONN_MAX_AGE": 60,
    }
}

Benchmarks show CONN_MAX_AGE=60 reduces p99 latency by 15–30% on high-traffic endpoints by eliminating connection establishment overhead.

Real Production Use Cases

Use Case 1: Multi-Tenant SaaS — Tenant Resolution in Middleware

A SaaS application where each customer has their own subdomain (customer-a.myapp.com, customer-b.myapp.com). The tenant must be resolved and attached to every request:

# common/middleware/tenant.py
from django.http import Http404
from apps.tenants.models import Tenant
from django.core.cache import cache


class TenantResolutionMiddleware:
    """
    Resolves the tenant from the request hostname and attaches it
    to request.tenant. All subsequent middleware and views can
    rely on request.tenant being set.
    """
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        hostname = request.get_host().split(":")[0]  # strip port

        cache_key = f"tenant_by_host:{hostname}"
        tenant = cache.get(cache_key)

        if tenant is None:
            try:
                tenant = Tenant.objects.get(domain=hostname, is_active=True)
                cache.set(cache_key, tenant, timeout=300)
            except Tenant.DoesNotExist:
                raise Http404(f"No active tenant for domain: {hostname}")

        request.tenant = tenant
        return self.get_response(request)

Use Case 2: API Rate Limiting by Plan Tier

A REST API where different subscription plans get different rate limits. This is cleanest as middleware because it runs on every request and doesn't require view-level knowledge:

PLAN_RATE_LIMITS = {
    "free":       100,    # requests per hour
    "starter":    1_000,
    "pro":        10_000,
    "enterprise": 100_000,
}

class PlanRateLimitMiddleware:
    def __call__(self, request):
        if not request.user.is_authenticated:
            return self.get_response(request)

        plan  = request.user.subscription.plan
        limit = PLAN_RATE_LIMITS.get(plan, 100)
        key   = f"rate:{request.user.id}:{int(time.time() // 3600)}"
        count = cache.incr(key, default=0)

        if count == 1:
            cache.expire(key, 3600)

        if count > limit:
            return JsonResponse({"error": "Rate limit exceeded"}, status=429)

        return self.get_response(request)

Use Case 3: ASGI for Real-Time Order Tracking

# project/asgi.py
import os
from django.core.asgi import get_asgi_application
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.auth import AuthMiddlewareStack
from apps.orders.routing import websocket_urlpatterns

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings.production")

application = ProtocolTypeRouter({
    "http": get_asgi_application(),
    "websocket": AuthMiddlewareStack(
        URLRouter(websocket_urlpatterns)
    ),
})

# apps/orders/consumers.py
from channels.generic.websocket import AsyncJsonWebsocketConsumer

class OrderStatusConsumer(AsyncJsonWebsocketConsumer):
    async def connect(self):
        order_id = self.scope["url_route"]["kwargs"]["order_id"]
        self.group_name = f"order_{order_id}"
        await self.channel_layer.group_add(self.group_name, self.channel_name)
        await self.accept()

    async def order_status_update(self, event):
        await self.send_json({"status": event["status"]})

    async def disconnect(self, close_code):
        await self.channel_layer.group_discard(self.group_name, self.channel_name)

Conclusion

The Django request/response cycle looks simple from the outside. URL goes in. HTML or JSON comes out. But between those two moments lies a precisely orchestrated sequence of events: WSGI/ASGI handling, settings loading, middleware traversal, URL resolution, view execution, ORM translation, database I/O, and response construction.

Every layer of that pipeline is a leverage point:

Middleware gives you global, composable hooks without modifying views
The URL dispatcher keeps routing declarative and inspectable
The ORM translates Python to SQL — but only if you understand when it hits the database
The response pipeline gives you control over every header and byte before the client sees it

The engineers who build fast, secure, maintainable Django applications are not the ones who know the most framework APIs. They're the ones who understand the mechanics well enough to know where things go wrong — and how to fix them before they do.

You now have that understanding. Go build something fast.

Django Project Structure Best Practices: A Production-Ready Guide

Alanso Mathew — Tue, 10 Mar 2026 11:03:43 +0000

A software engineer's guide to structuring Django projects that scale — built from real-world experience shipping production systems.

Originally published at: https://alansomathewdev.blogspot.com/2026/03/django-project-structure-best-practices.html

Introduction
Core Concepts
Architecture Overview
Step-by-Step Implementation
Code Examples
Performance and Scalability Tips
Common Mistakes to Avoid
Real-World Use Cases
Best Practices Summary
Conclusion

Introduction

Every Django developer has been there: you clone a year-old project, open the repository, and immediately face a wall of confusion. Files scattered at the root level, a single settings.py trying to serve three environments, models buried inside unrelated apps, and business logic crammed into views. The project works — but barely, and only if you already know where everything lives.

Django's famously quick onboarding is also its quiet danger. The framework's startproject scaffold is designed to get you moving, not to get you scaling. For small personal projects, the default layout is perfectly fine. But the moment your codebase grows to more than one developer, one environment, or one domain of responsibility, you need intentional structure.

Django project structure isn't just about aesthetics or personal preference. It directly impacts:

Onboarding speed — how quickly a new developer becomes productive
Maintainability — how safely you can change one component without breaking another
Testability — how easily you can write isolated, fast unit tests
Deployability — how cleanly you can promote code from development to staging to production
Scalability — how painlessly you can extract a bounded domain into a microservice later

This article walks through production-grade Django project structure from first principles. You'll learn not just the patterns, but the reasoning behind them — which is what separates a developer who follows rules from one who can design their own.

Core Concepts

Before diving into the file tree, it's essential to internalize a few foundational ideas that drive every structural decision.

The Twelve-Factor App

The Twelve-Factor App methodology defines principles for building software-as-a-service apps that are portable, scalable, and maintainable. Several factors directly influence Django project structure:

Config — store configuration in the environment, not in code
Dev/prod parity — keep development and production as similar as possible
Dependencies — explicitly declare and isolate dependencies

A well-structured Django project is, at its core, a Twelve-Factor App.

Separation of Concerns

Each module, file, and class should have one reason to change. In Django terms:

Models define data shape and storage — nothing else
Views handle HTTP request/response — nothing else
Services contain business logic — separate from HTTP and data layers
Serializers/Forms handle data validation and transformation

When business logic leaks into views, or database queries live inside templates, you've violated this principle. The cost compounds quickly.

Apps as Bounded Contexts

Django apps are the primary unit of code organization. Each app should map to a single, cohesive domain concept — a bounded context in Domain-Driven Design (DDD) terms.

A good Django app:

Has a clear, single responsibility
Can be reasoned about independently
Has minimal coupling to other apps
Could theoretically be extracted into a package

If your app is named utils, helpers, or misc, that's a signal it's doing too much.

Architecture Overview

Here's a bird's-eye view of a production-ready Django project:

myproject/
│
├── config/                     # Project configuration (not an app)
│   ├── __init__.py
│   ├── settings/
│   │   ├── __init__.py
│   │   ├── base.py             # Shared settings
│   │   ├── development.py      # Dev overrides
│   │   ├── production.py       # Production overrides
│   │   └── test.py             # Test-specific settings
│   ├── urls.py                 # Root URL configuration
│   ├── wsgi.py
│   └── asgi.py
│
├── apps/                       # All Django apps live here
│   ├── users/
│   │   ├── migrations/
│   │   ├── tests/
│   │   │   ├── __init__.py
│   │   │   ├── test_models.py
│   │   │   ├── test_views.py
│   │   │   └── test_services.py
│   │   ├── __init__.py
│   │   ├── admin.py
│   │   ├── apps.py
│   │   ├── models.py
│   │   ├── serializers.py
│   │   ├── services.py         # Business logic layer
│   │   ├── selectors.py        # Read/query logic
│   │   ├── urls.py
│   │   └── views.py
│   │
│   └── orders/
│       └── ...
│
├── common/                     # Shared utilities, base classes, mixins
│   ├── __init__.py
│   ├── exceptions.py
│   ├── mixins.py
│   ├── pagination.py
│   └── permissions.py
│
├── infrastructure/             # Third-party integrations
│   ├── email/
│   ├── storage/
│   └── payment/
│
├── templates/                  # Global templates (if server-rendered)
├── static/                     # Static assets
├── media/                      # User-uploaded content (local dev only)
│
├── requirements/
│   ├── base.txt
│   ├── development.txt
│   └── production.txt
│
├── scripts/                    # Management scripts, data migrations
├── docs/                       # Project documentation
│
├── .env.example                # Template for local environment variables
├── .gitignore
├── docker-compose.yml
├── Dockerfile
├── Makefile
├── manage.py
└── pyproject.toml              # or setup.cfg / tox.ini

This layout has a clear hierarchy of responsibility:

config/ owns project-level configuration
apps/ owns all domain logic
common/ owns reusable infrastructure shared across apps
infrastructure/ owns third-party integrations

Step-by-Step Implementation

Step 1: Initialize with a `config` Package

The default startproject creates a folder named after your project that doubles as both the Python package and the configuration directory. This conflation causes confusion. Separate them.

django-admin startproject config .

Notice the trailing dot — this places manage.py at the root and creates config/ as your settings package rather than duplicating your project name.

Step 2: Split Settings by Environment

Never use a single settings.py in production. The classic pattern uses a settings/ package with environment-specific modules:

mkdir config/settings
touch config/settings/__init__.py
touch config/settings/base.py
touch config/settings/development.py
touch config/settings/production.py
touch config/settings/test.py

Set the correct settings module per environment using the DJANGO_SETTINGS_MODULE environment variable:

# .env (local development)
DJANGO_SETTINGS_MODULE=config.settings.development

# Production server / CI
DJANGO_SETTINGS_MODULE=config.settings.production

Step 3: Place All Apps Under an `apps/` Directory

Django's startapp places apps at the root level by default. This is fine for toy projects but creates a flat, hard-to-navigate root as you scale.

mkdir apps
cd apps
django-admin startapp users
django-admin startapp orders

Then update apps.py in each app to reflect the new path:

# apps/users/apps.py
from django.apps import AppConfig

class UsersConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name = "apps.users"  # ← full dotted path
    label = "users"

And update INSTALLED_APPS in your settings:

INSTALLED_APPS = [
    # Django internals
    "django.contrib.admin",
    "django.contrib.auth",
    # ...

    # Third-party
    "rest_framework",
    "django_filters",

    # Local apps
    "apps.users.apps.UsersConfig",
    "apps.orders.apps.OrdersConfig",
]

Step 4: Separate Business Logic into a Service Layer

This is the single highest-leverage structural change you can make. Views should be thin HTTP adapters; services should own business logic.

# apps/orders/views.py  ← THIN
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status

from apps.orders.serializers import CreateOrderSerializer
from apps.orders.services import OrderService

class OrderCreateView(APIView):
    def post(self, request):
        serializer = CreateOrderSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)

        order = OrderService.create_order(
            user=request.user,
            **serializer.validated_data,
        )
        return Response({"id": order.id}, status=status.HTTP_201_CREATED)

# apps/orders/services.py  ← BUSINESS LOGIC
from django.db import transaction
from apps.orders.models import Order, OrderItem
from apps.inventory.selectors import get_product_by_id
from infrastructure.payment.gateway import charge_card

class OrderService:
    @staticmethod
    @transaction.atomic
    def create_order(user, product_id, quantity, payment_token):
        product = get_product_by_id(product_id)

        if product.stock < quantity:
            raise ValueError("Insufficient stock")

        order = Order.objects.create(user=user, total=product.price * quantity)
        OrderItem.objects.create(order=order, product=product, quantity=quantity)

        charge_card(token=payment_token, amount=order.total)
        product.reduce_stock(quantity)

        return order

Why this matters: your business logic is now testable without an HTTP request, reusable from management commands, Celery tasks, or other services, and readable without HTTP noise.

Step 5: Add a Selectors Layer for Queries

Following the HackSoft Django styleguide pattern, separate write logic (services) from read logic (selectors):

# apps/orders/selectors.py
from django.db.models import QuerySet
from apps.orders.models import Order

def get_orders_for_user(user_id: int) -> QuerySet:
    return (
        Order.objects
        .filter(user_id=user_id)
        .select_related("user")
        .prefetch_related("items__product")
        .order_by("-created_at")
    )

This keeps views lean, makes query optimization localized, and makes read paths testable in isolation.

Code Examples

Base Settings Pattern

# config/settings/base.py
from pathlib import Path
import environ

BASE_DIR = Path(__file__).resolve().parent.parent.parent

env = environ.Env()
environ.Env.read_env(BASE_DIR / ".env")

SECRET_KEY = env("SECRET_KEY")
DEBUG = env.bool("DEBUG", default=False)
ALLOWED_HOSTS = env.list("ALLOWED_HOSTS", default=[])

DATABASES = {
    "default": env.db("DATABASE_URL")
}

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    # third-party
    "rest_framework",
    # local
    "apps.users.apps.UsersConfig",
]

AUTH_USER_MODEL = "users.User"

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "rest_framework_simplejwt.authentication.JWTAuthentication",
    ],
    "DEFAULT_PERMISSION_CLASSES": [
        "rest_framework.permissions.IsAuthenticated",
    ],
    "DEFAULT_PAGINATION_CLASS": "common.pagination.PageNumberPagination",
    "PAGE_SIZE": 20,
}

# config/settings/development.py
from .base import *

DEBUG = True
ALLOWED_HOSTS = ["*"]

INSTALLED_APPS += ["debug_toolbar"]

INTERNAL_IPS = ["127.0.0.1"]

EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"

# config/settings/production.py
from .base import *

SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_HSTS_SECONDS = 31536000
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_HSTS_PRELOAD = True

STORAGES = {
    "default": {
        "BACKEND": "storages.backends.s3boto3.S3Boto3Storage",
    },
    "staticfiles": {
        "BACKEND": "storages.backends.s3boto3.S3StaticStorage",
    },
}

Custom User Model (Set Up From Day One)

# apps/users/models.py
from django.contrib.auth.models import AbstractUser
from django.db import models

class User(AbstractUser):
    """
    Custom user model. Always define this before your first migration.
    Changing it later is painful beyond words.
    """
    email = models.EmailField(unique=True)
    avatar = models.ImageField(upload_to="avatars/", null=True, blank=True)

    USERNAME_FIELD = "email"
    REQUIRED_FIELDS = ["username"]

    class Meta:
        verbose_name = "User"
        verbose_name_plural = "Users"

    def __str__(self):
        return self.email

Structured Requirements Files

# requirements/base.txt
Django==5.0.4
djangorestframework==3.15.1
django-environ==0.11.2
psycopg2-binary==2.9.9
celery==5.3.6
redis==5.0.3
django-filter==24.2
Pillow==10.3.0

# requirements/development.txt
-r base.txt
django-debug-toolbar==4.3.0
pytest-django==4.8.0
factory-boy==3.3.0
ipython==8.23.0
black==24.3.0
ruff==0.4.1

# requirements/production.txt
-r base.txt
gunicorn==22.0.0
django-storages[s3]==1.14.3
sentry-sdk[django]==1.44.1

Testing Structure

# apps/orders/tests/test_services.py
import pytest
from django.contrib.auth import get_user_model
from apps.orders.services import OrderService
from apps.orders.tests.factories import ProductFactory

User = get_user_model()

@pytest.mark.django_db
class TestOrderService:
    def test_create_order_success(self, user, mocker):
        product = ProductFactory(stock=10, price=99.99)
        mock_charge = mocker.patch("infrastructure.payment.gateway.charge_card")

        order = OrderService.create_order(
            user=user,
            product_id=product.id,
            quantity=2,
            payment_token="tok_test",
        )

        assert order.total == 199.98
        mock_charge.assert_called_once()
        product.refresh_from_db()
        assert product.stock == 8

    def test_create_order_raises_on_insufficient_stock(self, user):
        product = ProductFactory(stock=1)

        with pytest.raises(ValueError, match="Insufficient stock"):
            OrderService.create_order(
                user=user,
                product_id=product.id,
                quantity=5,
                payment_token="tok_test",
            )

Performance and Scalability Tips

1. Use `select_related` and `prefetch_related` in Selectors

Every N+1 query problem you'll encounter can be traced to forgetting these. Centralizing queries in selectors means you fix it in one place:

# Always optimize at the selector level, not the view level
def get_order_list(user_id: int):
    return (
        Order.objects.filter(user_id=user_id)
        .select_related("user", "shipping_address")
        .prefetch_related("items__product__category")
        .only("id", "status", "total", "created_at")  # defer heavy fields
    )

2. Index Strategically

Add database indexes on fields used in filter(), order_by(), and get() calls:

class Order(models.Model):
    user = models.ForeignKey(User, on_delete=models.CASCADE, db_index=True)
    status = models.CharField(max_length=20, db_index=True)
    created_at = models.DateTimeField(auto_now_add=True, db_index=True)

    class Meta:
        indexes = [
            models.Index(fields=["user", "status"]),  # composite index
            models.Index(fields=["-created_at"]),
        ]

3. Offload to Celery

Any operation that doesn't need to complete within the HTTP request cycle should be async:

# apps/orders/tasks.py
from celery import shared_task
from apps.orders.services import OrderService

@shared_task(bind=True, max_retries=3)
def send_order_confirmation_email(self, order_id: int):
    try:
        OrderService.send_confirmation(order_id)
    except Exception as exc:
        raise self.retry(exc=exc, countdown=60)

4. Cache Aggressively at the Right Layer

Cache at the selector or service layer, not the view layer:

from django.core.cache import cache

def get_active_categories():
    cache_key = "active_categories"
    result = cache.get(cache_key)
    if result is None:
        result = list(Category.objects.filter(is_active=True).values("id", "name"))
        cache.set(cache_key, result, timeout=3600)
    return result

5. Use Database Connection Pooling

In production, configure pgBouncer or use django-db-geventpool. Unpooled connections are one of the fastest paths to production incidents under load.

Common Mistakes to Avoid

❌ Fat Views

# BAD — view doing way too much
def create_order(request):
    product = Product.objects.get(id=request.POST["product_id"])
    if product.stock < int(request.POST["quantity"]):
        return JsonResponse({"error": "Out of stock"}, status=400)
    order = Order.objects.create(user=request.user, ...)
    send_mail("Order confirmed", ..., [request.user.email])
    return JsonResponse({"id": order.id})

Move business logic to services. Views should be 5–15 lines.

❌ Not Defining a Custom User Model Upfront

Django's docs say it explicitly: always define a custom user model before your first migration. If you don't, retrofitting one later requires raw SQL surgery on your database. It takes under 10 minutes to set up and can save hours of future pain.

❌ Hardcoding Settings

# BAD
SECRET_KEY = "my-secret-key-12345"
DATABASES = {"default": {"HOST": "localhost", "PASSWORD": "postgres"}}

Use django-environ or python-decouple to read from environment variables. Never commit secrets to version control.

❌ Mega-Apps

An api/ app or core/ app that contains everything defeats the purpose of apps. If your models file is 2,000 lines, your app is doing too much. Split by domain, not by Django layer.

❌ Missing `init.py` or Misconfigured App Labels

When you move apps into a subdirectory, update both name (full dotted path) and label (short unique name) in AppConfig. Duplicate labels cause subtle, hard-to-debug errors.

❌ Skipping Migrations for Test Speed

Using --no-migrations in tests can cause false positives. Use pytest-django with a proper test database instead. For speed, use --reuse-db from pytest-django.

Real-World Use Cases

SaaS Multi-Tenant Platform

A SaaS product might organize apps like this:

apps/
├── accounts/       # Tenants / organizations
├── billing/        # Subscriptions, invoices (Stripe integration)
├── users/          # User auth within tenants
├── projects/       # Core product domain
├── notifications/  # Email, in-app, push
└── analytics/      # Usage tracking

Each app maps to a product domain. The billing/ app talks to Stripe via infrastructure/payment/. The notifications/ app is consumed by projects/ and billing/ via service calls, never direct model access.

E-Commerce Backend

apps/
├── catalog/        # Products, categories, variants
├── inventory/      # Stock management
├── orders/         # Cart, checkout, order lifecycle
├── shipping/       # Fulfillment, tracking
├── customers/      # User accounts, addresses
└── promotions/     # Discount codes, campaigns

Each bounded context owns its own models. The orders/ service calls inventory/ selectors to check stock. It never imports inventory models directly — only through the public selector API.

Internal Admin Tool

Smaller teams building internal tools can simplify:

apps/
├── core/           # Shared models, abstract base classes
├── employees/      # HR data
├── finance/        # Budget tracking
└── reporting/      # Dashboards, exports

The key remains the same: one app, one concern.

Best Practices Summary

Area	Best Practice
Settings	Split into base/dev/prod/test; use environment variables
Apps	Group under `apps/`; one app per domain; avoid mega-apps
Business Logic	Always in `services.py`; never in views or models
Queries	Centralized in `selectors.py`; optimize with `select_related`
User Model	Always define a custom user model before migration 0001
Testing	Mirror app structure in `tests/`; test services independently
Requirements	Split by environment; pin all versions
Migrations	Never edit applied migrations; use `squashmigrations` when needed
Configuration	Use `AppConfig` with `default_app_config` pattern
Secrets	Always read from environment; never commit to git

Conclusion

A well-structured Django project is not an accident. It's the result of deliberate, principled decisions made early — and then consistently enforced as the project grows.

The structure outlined here — split settings, an apps/ namespace, a service layer, a selectors layer, and a shared common/ module — isn't dogma. It's a battle-tested foundation used across dozens of production systems. It's specifically designed to remain navigable when the team doubles, the domain grows, and the deadline pressure climbs.

The most important takeaway isn't any specific file layout. It's the reasoning: separate concerns, keep each layer responsible for exactly one thing, isolate third-party dependencies, and make every component independently testable.

Start with this structure on your next Django project. When you feel the temptation to put business logic in a view "just this once," recall how it felt to read someone else's fat-view spaghetti — and resist.

The developers who inherit your code (including future you) will thank you.

DEV Community: Alanso Mathew

Understanding Django Models and ORM: A Complete Production Guide

Table of Contents

Introduction

Why This Matters in Production Systems

Core Concepts

Models: Python Classes That Map to Database Tables

Fields: The Vocabulary of Your Schema

QuerySets: Lazy Representations of Database Queries

The Manager: The Gateway to QuerySets

Architecture Design

Step-by-Step Implementation

Step 1: Define Production-Ready Models

Step 2: Define Complex Relationships

Step 3: Build Custom Managers and QuerySets

Step 4: Configure Settings for Database Performance

Code Examples

F Expressions: Database-Side Arithmetic

Q Objects: Complex Lookups and OR Logic

Annotations and Aggregations: Push Calculations to the Database

select_related and prefetch_related: The N+1 Cure

Custom Prefetch Objects: Prefetch with Filters

Bulk Operations: Dozens of Rows in One Query

The iterator() Method: Memory-Efficient Large Queryset Processing

Model Methods vs Manager Methods

Transactions: Atomicity Guarantees

Performance Optimization

1. Use only() and defer() to Limit Column Fetches

2. Use values() and values_list() for Read-Only Data

3. Use exists() and count() Appropriately

4. Enforce Query Budgets in Tests

5. Database Indexes: The Most Impactful Single Change

Security Best Practices

1. SQL Injection: What the ORM Protects and What It Doesn't

2. Prevent Mass Assignment

3. Prevent IDOR with Object-Level Scoping

4. Use update_fields in .save() for Precision

5. Use Constraints for Data Integrity at the Database Level

Common Developer Mistakes

❌ Mistake 1: Evaluating QuerySets Too Early

❌ Mistake 2: Using len() Instead of .count()

❌ Mistake 3: Combining Multiple Annotations Incorrectly

❌ Mistake 4: Calling .save() Inside a Loop

❌ Mistake 5: Accessing Related Objects Without Prefetching

❌ Mistake 6: Using .filter() After .values() With Annotations

Real Production Use Cases

Use Case 1: E-Commerce Dashboard — Complex Aggregations

Use Case 2: Large Data Export — Memory-Efficient Iterator Pattern

Use Case 3: SaaS Multi-Tenant Data Isolation via Custom Manager

Conclusion

Further Reading

Django Apps vs Projects Explained: A Complete Production Guide

Table of Contents

Introduction

Why This Matters in Production Systems

Core Concepts

What Is a Django Project?

What Is a Django App?

The AppConfig Class — The App's Identity

The INSTALLED_APPS Contract

Architecture Design

The Dependency Direction Rule

Step-by-Step Implementation

Step 1: Initialise the Project (Not an App)

Step 2: Create Your First App

Step 3: Update AppConfig for Each App

Step 4: Wire Apps into the Project

Step 5: Compose App URLs in the Project Router

Step 6: Run and Validate

Code Examples

Complete App Model with Proper Relationships

Custom User Model (Always in the users App)

Signals: Decoupling Apps Without Circular Imports

Building a Reusable, Packageable App

System Checks: App-Level Validation at Startup

Performance Optimization

1. Lazy App Loading — Understand When Code Runs

2. Per-App Database Routing

3. Migration Performance — Squash by App

4. App-Scoped Caching with Key Prefixes

The `iterator()` Method: Memory-Efficient Large Queryset Processing

1. Use `only()` and `defer()` to Limit Column Fetches

2. Use `values()` and `values_list()` for Read-Only Data

3. Use `exists()` and `count()` Appropriately

4. Use `update_fields` in `.save()` for Precision

❌ Mistake 2: Using `len()` Instead of `.count()`

❌ Mistake 4: Calling `.save()` Inside a Loop

❌ Mistake 6: Using `.filter()` After `.values()` With Annotations

The `AppConfig` Class — The App's Identity

The `INSTALLED_APPS` Contract

Custom User Model (Always in the `users` App)

3. Per-App `SECRET_KEY` Rotation Strategy

❌ Mistake 3: Forgetting `app_label` on Abstract Models

❌ Mistake 4: Importing from Apps in `settings.py`

❌ Mistake 5: Putting Business Logic in `apps.py` `ready()`

1. Eliminate N+1 Queries with `select_related` and `prefetch_related`

❌ Mistake 3: Forgetting `transaction.on_commit`

❌ Mistake 4: Using `DEBUG = True` Without Understanding the Cost

❌ Mistake 5: Ignoring `CONN_MAX_AGE`