dj-models

Structure a Django Model

You are defining or restructuring a Django model in an opinionated, fully type-safe Django project. Every convention below is mandatory. Do not deviate.

BEFORE WRITING CODE

Read the model file being created or modified, plus:

• src/project/ids.py — existing ID prefixes
• Any existing models in the same app — for cross-model index considerations
• The repository that queries this model — to understand real query patterns
• src/<app>/admin.py — existing admin registrations

Model Structure

Every model follows this exact ordering of members:

from typing import ClassVar

from django.db import models

from project.ids import generate_xxx_id


class MyEntity(models.Model):
    # 1. Meta — ALWAYS first, before any field
    class Meta:
        verbose_name = "my entity"
        verbose_name_plural = "my entities"
        indexes = [
            models.Index(fields=["-created_at"], name="idx_%(class)s_recent"),
        ]
        constraints = [
            models.UniqueConstraint(fields=["slug"], name="uq_%(class)s_slug"),
        ]

    # 2. ClassVar prefix
    __prefix__: ClassVar[str] = "xxx"

    # 3. Identifiers — primary key, slugs, external refs
    id = models.CharField(
        max_length=64, primary_key=True, default=generate_xxx_id, editable=False
    )
    slug = models.SlugField(max_length=255)

    # 4. Time fields — created, updated, any dates/datetimes
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    # 5. Workflow / status / state (if applicable)
    status = models.CharField(max_length=20, choices=STATUS_CHOICES, default="draft")

    # 6. Everything else — domain fields
    name = models.CharField(max_length=255)
    description = models.TextField(blank=True)

    # 7. Relations — ForeignKey, OneToOne, ManyToMany (always last among fields)
    category = models.ForeignKey("categories.Category", on_delete=models.CASCADE)

    # 8. __str__ — only if useful, and the only method allowed
    def __str__(self) -> str:
        return self.name