Dj Models

Admin Rules

• list_display — id first, then the most useful columns. Keep it to 4-6 fields max for readability.

• list_per_page = 25 — default 100 is too slow on large tables. 25 keeps the admin snappy.

• search_fields — always include id. Add name/title fields if they exist. Never search on unindexed columns.

• readonly_fields — always include id (ULID PKs should never be edited). Add computed or auto-set fields.

• ordering — explicit ordering so the admin doesn't rely on the default PK sort. Use -created_at or the most natural time field.

• fieldsets — structure the change view semantically in three bands. Always follow this exact pattern:

  1. Untitled (None) fieldset — primary key and identity fields only (id, plus email / slug / natural key if the model has one). Renders with no collapsible header so identifiers are always visible at the top.
  2. Named semantic sections — group remaining fields by meaning, not DB column order. Reusable section names: "Personal Info", "Details", "Role & Permissions", "Security", "Relations". Use "Details" as the catchall when no more specific name fits.
  3. "Important Dates" (always last) — every datetime field goes here: created_at, updated_at, deleted_at, last_login, date_joined, etc. Title is exactly "Important Dates" (title case).

  fieldsets = (
      (None, {"fields": ("id", "slug")}),
      ("Details", {"fields": ("name", "description", "status")}),
      ("Relations", {"fields": ("category",)}),
      ("Important Dates", {"fields": ("created_at", "updated_at")}),
  )

  Rationale: identity at top (always visible), domain in the middle (named so it's scannable), dates at the bottom (rarely the thing you're editing, and separating them keeps the top fieldset focused on identity).

• add_fieldsets — for models that support admin creation (User primarily), provide a minimal add_fieldsets with just the required fields for a new record:

  add_fieldsets = (
      (None, {
          "classes": ("wide",),
          "fields": ("email", "password1", "password2"),
      }),
  )

  Keeps the "Add" form focused — the full fieldsets is for editing, not creation.

• list_select_related — specify FK fields shown in list_display to avoid N+1 queries: list_select_related = ("customer",)

• raw_id_fields — use for any FK to a large table. The default dropdown loads every row: raw_id_fields = ("product",)

• extra = 0 on inlines — never show empty inline forms by default.

• show_change_link = True on inlines — lets you click through to the inline's own admin page.

• TabularInline for child models on the parent's admin.

• No list_filter on unindexed columns — filtering on unindexed columns causes full table scans.

• autocomplete_fields — prefer over raw_id_fields when the related model has search_fields configured for a better UX: autocomplete_fields = ("customer",)

• date_hierarchy — use on the primary date field if the model is time-series-like (orders, events, logs). Only use on indexed date fields.

Admin Actions

Custom admin actions (the dropdown users select from on the changelist) MUST be thin adapters — never the home of business logic. The action receives a queryset, iterates it, delegates each row to a registered service via get(Service), and reports the result via self.message_user(request, ...).

from django.contrib import admin

from products.services.product import ProductService
from project.services import get


@admin.register(Order)
class OrderAdmin(admin.ModelAdmin):
    actions = ["fulfill_selected_action"]

    @admin.action(description="Fulfill selected orders")
    def fulfill_selected_action(self, request, queryset):
        count = 0
        for order in queryset:
            get(ProductService).fulfill_order(order.id)
            count += 1
        self.message_user(request, f"Fulfilled {count} orders.")

Rules:

1. Named <verb>_<noun>_action and listed in actions = [...]. The _action suffix distinguishes them from regular ModelAdmin methods at a glance.
2. @admin.action(description="...") is mandatory — the description is what users see in the dropdown. No emojis, no ALL-CAPS shouting.
3. Delegate to a service via get(Service).method(id). The action body MUST NOT contain ORM queries beyond iterating the incoming queryset, MUST NOT compute business logic, MUST NOT call external APIs directly.
4. Pass IDs, not model instances, to the service. Matches the rest of the architecture — services deal in DTOs and str IDs.
5. Call self.message_user() with a result summary — count, or a short outcome description. This is what users see after running the action.
6. Do NOT build Celery chains/groups in the action. If the operation needs async orchestration, build the chain inside the service method; the action stays a thin adapter.
7. Error handling — plain exceptions bubble up and Django renders them appropriately. Do not try/except in the action body; the service is where error semantics live.

Full Example

from typing import ClassVar

from django.db import models

from products.models.product import Product
from project.ids import generate_itm_id, generate_ord_id


class Order(models.Model):
    class Meta:
        verbose_name = "order"
        verbose_name_plural = "orders"
        indexes = [
            models.Index(fields=["-date"], name="idx_%(class)s_recent"),
            models.Index(fields=["status", "-date"], name="idx_%(class)s_status_recent"),
        ]
        constraints = [
            models.UniqueConstraint(
                fields=["idempotency_key"],
                name="uq_%(class)s_idempotency",
            ),
        ]

    __prefix__: ClassVar[str] = "ord"

    # Identifiers
    id = models.CharField(
        max_length=64, primary_key=True, default=generate_ord_id, editable=False
    )
    idempotency_key = models.CharField(
        verbose_name="idempotency key",
        max_length=255,
        help_text="Client-generated key to prevent duplicate order submissions.",
    )

    # Time
    date = models.DateTimeField(auto_now_add=True)

    # Status
    status = models.CharField(max_length=20, default="pending")

    # Domain
    total = models.DecimalField(max_digits=12, decimal_places=2)

    def __str__(self) -> str:
        return f"Order {self.id} on {self.date}"


class OrderItem(models.Model):
    class Meta:
        verbose_name = "order item"
        verbose_name_plural = "order items"
        indexes = [
            models.Index(fields=["order", "product"], name="idx_%(class)s_ord_prd"),
        ]

    __prefix__: ClassVar[str] = "itm"

    # Identifiers
    id = models.CharField(
        max_length=64, primary_key=True, default=generate_itm_id, editable=False
    )

    # Domain
    quantity = models.PositiveIntegerField()
    price_at_purchase = models.DecimalField(
        verbose_name="price at purchase",
        max_digits=10,
        decimal_places=2,
        help_text="Snapshot of the product price at the time the order was placed.",
    )

    # Relations
    order = models.ForeignKey(Order, related_name="items", on_delete=models.CASCADE)
    product = models.ForeignKey(Product, on_delete=models.CASCADE)

    def __str__(self) -> str:
        return f"{self.quantity} x {self.product.name} (Order {self.order_id})"  # type: ignore[attr-defined]

Admin for the example above:

from django.contrib import admin

from .models.order import Order, OrderItem


class OrderItemInline(admin.TabularInline):
    model = OrderItem
    fields = ("id", "product", "quantity", "price_at_purchase")
    readonly_fields = ("id",)
    extra = 0
    show_change_link = True


@admin.register(Order)
class OrderAdmin(admin.ModelAdmin):
    list_display = ("id", "status", "date", "total")
    list_per_page = 25
    search_fields = ("id", "idempotency_key")
    readonly_fields = ("id", "date")
    ordering = ("-date",)
    date_hierarchy = "date"
    fieldsets = (
        (None, {"fields": ("id", "date")}),
        ("Details", {"fields": ("status", "total", "idempotency_key")}),
    )
    inlines = [OrderItemInline]

Verify

After creating or modifying models:

uv run python src/manage.py makemigrations && uv run python src/manage.py migrate
uv run ruff check src
uv run ruff format --check src
uv run pyrefly check src
uv run pytest

All must pass. Fix any issue rather than silencing it.

Checklist

• class Meta is the first thing inside the model body
• verbose_name and verbose_name_plural are set — never relying on Django's auto-pluralization
• Field order: identifiers → time → status/state → domain → relations
• All indexes in Meta.indexes — no db_index=True on fields
• All uniqueness in Meta.constraints via UniqueConstraint — no unique=True on fields
• Check constraints in Meta.constraints where applicable
• Indexes match actual query patterns from the repository layer
• No over-indexing — only index what is queried
• Multi-word fields have explicit verbose_name
• Obscure or domain-specific fields have help_text
• No business logic — no custom managers, save(), signals, or computed properties
• __str__ only if useful, and the only method allowed
• Model registered in admin with list_display, list_per_page = 25, search_fields, readonly_fields, ordering, fieldsets
• fieldsets places id and timestamps in the first (untitled) fieldset at the top of the change view
• FKs to large tables use raw_id_fields or autocomplete_fields
• Inlines use extra = 0 and show_change_link = True
• Migrations generated and applied
• ruff, pyrefly, pytest all pass