django-model - Creating Models with Counterpart Patterns

Overview

Django models at Counterpart follow specific patterns: all inherit from BaseModel with UUID primary keys and audit timestamps, use type hints consistently, and leverage Pydantic for JSON field validation. This skill shows exactly how to build models that follow the architecture patterns documented in CLAUDE.md, including proper relationships, JSON fields, and testing considerations.

When to Use This Skill

• Creating a new Django model for a database entity (applications, quotes, policies, etc.)
• Adding relationships between models (foreign keys, one-to-many, many-to-many)
• Implementing JSON fields with Pydantic validation (nested data structures)
• Working with models that need audit trail tracking (who changed what, when)
• Ensuring type safety and consistency in model definitions

Don't use this skill for:

• Modifying existing models where patterns already exist (just follow the established pattern)
• Simple model tweaks that don't involve new relationships
• Models in third-party packages or external integrations

Prerequisites

Django project with Counterpart setup. Core models live in common/models.py and extend BaseModel.

Required imports:

from django.db import models
from pydantic import BaseModel as PydanticBaseModel, Field
from common.models import BaseModel  # UUID PK + audit fields already included
from typing import Optional, List

Existing patterns in codebase:

• Look at application/models.py, quote/models.py for existing examples
• Review common/models.py for BaseModel definition with audit fields

Decision Tree

Choose your approach based on model complexity:

1. Simple Entity → Basic model with standard fields

   • When: Core business object with no special requirements
   • Best for: Applications, quotes, carriers, standard lookup data
   • Example: Single table, maybe one or two foreign keys

2. Complex Entity → Model with JSON fields for nested data

   • When: Storing flexible, semi-structured data (config, settings, attributes)
   • Best for: Policy terms, coverage details, rating factors
   • Example: Uses Pydantic models as JSON field validators

3. Relationship Hub → Model connecting multiple entities

   • When: Junction/bridge model or central coordinator
   • Best for: Policy events, activity logs, carrier programs
   • Example: Multiple foreign keys with specific ordering/constraints

Workflow

Step 1: Define Pydantic Models for JSON Fields (if needed)

If your model has JSON fields with structured data, define Pydantic models first for validation. This ensures type-safe serialization and validation.

from pydantic import BaseModel as PydanticBaseModel, Field
from typing import Optional, List

class CoverageDetailSchema(PydanticBaseModel):
    """Pydantic model for coverage details stored as JSON."""
    coverage_type: str = Field(..., description="Type of coverage")
    limit: float = Field(..., gt=0, description="Coverage limit in dollars")
    deductible: float = Field(default=0, ge=0, description="Deductible amount")
    effective_date: str = Field(..., description="Start date in YYYY-MM-DD format")
    notes: Optional[str] = Field(default=None, max_length=500)

    class Config:
        json_schema_extra = {
            "example": {
                "coverage_type": "liability",
                "limit": 1000000,
                "deductible": 2500,
                "effective_date": "2024-01-01",
                "notes": "Standard commercial liability"
            }
        }

Key parameters:

• Use Field() for all fields with descriptions and constraints
• Add json_schema_extra with example data for API documentation
• Set gt (greater than), ge (greater than/equal), max_length, etc. for validation

Step 2: Create the Model Class

Use BaseModel as parent (gets UUID PK + audit fields automatically). Add type hints to all fields.

from django.db import models
from common.models import BaseModel
from django.contrib.postgres.fields import JSONField
from pydantic import PydanticEncoder

class PolicyCoverage(BaseModel):
    """Insurance policy coverage details with audit trail."""

    # Related entities - always use ForeignKey with on_delete specified
    policy = models.ForeignKey(
        'policy.Policy',
        on_delete=models.CASCADE,  # Delete coverage when policy deleted
        related_name='coverages',  # Access via policy.coverages.all()
        help_text="Parent policy for this coverage"
    )

    # Standard fields with type hints
    coverage_name: str = models.CharField(
        max_length=100,
        help_text="Human-readable coverage name"
    )

    is_active: bool = models.BooleanField(
        default=True,
        help_text="Whether this coverage is currently active"
    )

    premium_amount: float = models.DecimalField(
        max_digits=12,
        decimal_places=2,
        help_text="Premium amount in dollars"
    )

    # JSON field with Pydantic validation
    coverage_details = models.JSONField(
        default=dict,
        encoder=PydanticEncoder,
        help_text="Coverage details as validated JSON"
    )

    class Meta:
        app_label = 'policy'
        ordering = ['-created_at']  # Newest first
        indexes = [
            models.Index(fields=['policy', 'is_active']),
        ]

    def __str__(self) -> str:
        return f"{self.coverage_name} - {self.policy.policy_number}"

Field guidelines:

• Always use help_text for documentation
• Use related_name on ForeignKey for reverse queries
• Specify on_delete=models.CASCADE (or SET_NULL if optional) explicitly
• Use DecimalField for money, not FloatField (precision matters)
• Use JSONField with encoder=PydanticEncoder for structured data

Step 3: Create and Run Migration

Django creates migrations automatically, but verify it looks correct.

# Generate migration
python manage.py makemigrations policy

# Review the migration file before applying
cat policy/migrations/000X_auto_YYYYMMDD_HHMM.py

# Apply migration
python manage.py migrate policy

What to verify in migration:

• Foreign key relationships have correct app labels
• Field types match your model definitions
• No accidental field removals

Common Gotchas

Gotcha 1: Forgetting app_label in Meta Class

Symptom: RuntimeError: Model 'MyModel' has not been installed or migrations fail to apply

Cause: Django can't find your model when app_label isn't specified in Meta, especially if the model file structure is unusual

Solution:

class Meta:
    app_label = 'policy'  # Explicitly set to the app containing the model
    ordering = ['-created_at']

Prevention: Always include app_label in Meta. Even though it's often inferred, being explicit prevents migration headaches.

Gotcha 2: Using FloatField for Money

Symptom: Rounding errors, precision loss ($1.23 becomes $1.2300000001234), test failures with specific amounts

Cause: FloatField uses IEEE floating-point which can't represent all decimal values exactly

Solution:

# WRONG
price = models.FloatField()

# CORRECT
price = models.DecimalField(max_digits=12, decimal_places=2)  # Up to $9,999,999.99

Prevention: Use DecimalField for any financial data. The extra digits (max_digits=12) give buffer for calculations.

Gotcha 3: Missing on_delete on ForeignKey

Symptom: TypeError: __init__() missing 1 required positional argument: 'on_delete' during migration

Cause: Django 2.0+ requires explicit behavior when referenced object is deleted

Solution:

# WRONG - will raise error
policy = models.ForeignKey('policy.Policy')

# CORRECT - choose appropriate behavior
policy = models.ForeignKey(
    'policy.Policy',
    on_delete=models.CASCADE,  # Delete this when policy deleted
    # OR on_delete=models.SET_NULL (requires null=True)
    # OR on_delete=models.PROTECT (raise error if try to delete)
)

Prevention: Always specify on_delete. Use CASCADE for child entities, PROTECT for shared resources, SET_NULL for optional refs.

Gotcha 4: Default Mutable Objects in JSONField

Symptom: Updating one object's JSON also updates another object's JSON field inexplicably

Cause: Using mutable default (list, dict) shares the same object across all model instances

Solution:

# WRONG - all instances share same dict
details = models.JSONField(default={})

# CORRECT - callable creates new dict for each instance
details = models.JSONField(default=dict)

# CORRECT - for lists
tags = models.JSONField(default=list)

Prevention: Use callable defaults (dict, list) not literal values ({}, []).

Examples

Example 1: Simple Quote Entity

Scenario: Creating a Quote model that belongs to an Application. Needs core info and status tracking.

Implementation:

from django.db import models
from common.models import BaseModel

class Quote(BaseModel):
    """Insurance quote for an application."""

    application = models.ForeignKey(
        'application.Application',
        on_delete=models.CASCADE,
        related_name='quotes',
        help_text="Parent application"
    )

    quote_number: str = models.CharField(
        max_length=50,
        unique=True,
        help_text="Unique quote identifier"
    )

    base_premium: models.DecimalField(
        max_digits=12,
        decimal_places=2,
        help_text="Base premium before adjustments"
    )

    status: str = models.CharField(
        max_length=20,
        choices=[
            ('draft', 'Draft'),
            ('pending', 'Pending Review'),
            ('approved', 'Approved'),
            ('rejected', 'Rejected'),
        ],
        default='draft',
        help_text="Quote status"
    )

    expires_at = models.DateTimeField(
        help_text="When quote is no longer valid"
    )

    class Meta:
        app_label = 'quote'
        ordering = ['-created_at']
        indexes = [
            models.Index(fields=['quote_number']),
            models.Index(fields=['application', 'status']),
        ]

    def __str__(self) -> str:
        return f"Quote {self.quote_number}"

Result: Model with audit trail (created_at, updated_at, id via BaseModel), status tracking, and optimized queries via indexes.

Example 2: Policy with JSON Nested Data

Scenario: Storing policy with flexible coverage details that vary by program. Needs Pydantic validation.

Implementation:

from typing import List, Optional
from pydantic import BaseModel as PydanticBaseModel, Field, validator
from django.db import models
from common.models import BaseModel
from pydantic import PydanticEncoder

# Pydantic schema for coverage data
class CoverageSchema(PydanticBaseModel):
    """Coverage details stored as JSON."""
    type: str = Field(..., description="coverage type", min_length=1)
    limit: float = Field(..., gt=0, description="coverage limit")
    deductible: float = Field(default=0, ge=0, description="deductible amount")

    @validator('limit')
    def limit_must_exceed_deductible(cls, v, values):
        if 'deductible' in values and v <= values['deductible']:
            raise ValueError('limit must exceed deductible')
        return v

class PolicySchema(PydanticBaseModel):
    """Complete policy data with coverages."""
    coverage_list: List[CoverageSchema]
    effective_date: str
    renewal_date: str

# Django model using the Pydantic schema
class Policy(BaseModel):
    """Insurance policy with validated coverage details."""

    carrier_program = models.ForeignKey(
        'carrier_program.CarrierProgram',
        on_delete=models.PROTECT,  # Don't allow deletion if policies exist
        related_name='policies',
        help_text="Carrier program this policy belongs to"
    )

    policy_number: str = models.CharField(
        max_length=100,
        unique=True,
        help_text="Policy number from carrier"
    )

    # Validated JSON field
    policy_data = models.JSONField(
        encoder=PydanticEncoder,
        help_text="Complete policy data with coverages"
    )

    class Meta:
        app_label = 'policy'
        ordering = ['-created_at']
        indexes = [
            models.Index(fields=['policy_number']),
            models.Index(fields=['carrier_program', 'created_at']),
        ]

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

Verification:

# Create policy with validation
python manage.py shell
>>> from policy.models import Policy, PolicySchema
>>> policy_schema = PolicySchema(
...     coverage_list=[
...         {'type': 'liability', 'limit': 1000000, 'deductible': 5000}
...     ],
...     effective_date='2024-01-01',
...     renewal_date='2025-01-01'
... )
>>> Policy.objects.create(
...     carrier_program_id=1,
...     policy_number='POL-2024-001',
...     policy_data=policy_schema.dict()
... )

Example 3: Activity Log with Multiple Relations

Scenario: Tracking policy activity with references to multiple entities. Needs flexible logging.

Implementation:

from django.db import models
from django.contrib.contenttypes.fields import GenericForeignKey
from django.contrib.contenttypes.models import ContentType
from common.models import BaseModel

class ActivityLog(BaseModel):
    """Audit log for policy and application changes."""

    # Which user made the change
    user = models.ForeignKey(
        'users.User',
        on_delete=models.SET_NULL,
        null=True,
        related_name='activity_logs',
        help_text="User who performed the action"
    )

    # Generic relation - can log activity for any model
    content_type = models.ForeignKey(
        ContentType,
        on_delete=models.CASCADE,
        help_text="Content type of the object being logged"
    )
    object_id: str = models.UUIDField(
        help_text="ID of the object being logged"
    )
    content_object = GenericForeignKey('content_type', 'object_id')

    action: str = models.CharField(
        max_length=50,
        choices=[
            ('created', 'Created'),
            ('updated', 'Updated'),
            ('deleted', 'Deleted'),
            ('approved', 'Approved'),
            ('rejected', 'Rejected'),
        ],
        help_text="What action was performed"
    )

    changes = models.JSONField(
        default=dict,
        help_text="Dictionary of what changed: {field_name: [old_value, new_value]}"
    )

    description: str = models.TextField(
        help_text="Human-readable description"
    )

    class Meta:
        app_label = 'policy_events'
        ordering = ['-created_at']
        indexes = [
            models.Index(fields=['content_type', 'object_id']),
            models.Index(fields=['action', 'created_at']),
            models.Index(fields=['user', 'created_at']),
        ]

    def __str__(self) -> str:
        return f"{self.action} on {self.content_object} by {self.user}"

Why this works: Audit logs need flexibility - they log changes to different models. GenericForeignKey allows one model to reference any other model's instances.

Anti-Patterns

❌ BAD: Tight Coupling to Specific Models

# This model is tightly coupled - hard to reuse, test, or extend
class RatingFactor(BaseModel):
    application = models.ForeignKey('application.Application', on_delete=models.CASCADE)
    quote = models.ForeignKey('quote.Quote', on_delete=models.CASCADE)
    policy = models.ForeignKey('policy.Policy', on_delete=models.CASCADE)

    def get_related_entity(self):
        if self.application_id:
            return self.application
        # ... many conditionals

Why it fails:

• Each new entity type requires schema migration
• Model becomes a dumping ground for relationships
• Testing requires setting up multiple related objects
• Queries are inefficient with many nullable ForeignKeys

✅ GOOD: Use Generic Relations for Flexibility

from django.contrib.contenttypes.fields import GenericForeignKey
from django.contrib.contenttypes.models import ContentType

class RatingFactor(BaseModel):
    """Rating factor - can apply to any entity type."""

    content_type = models.ForeignKey(
        ContentType,
        on_delete=models.CASCADE,
        help_text="Type of entity this rating applies to"
    )
    object_id: str = models.UUIDField()
    content_object = GenericForeignKey('content_type', 'object_id')

    factor_code: str = models.CharField(max_length=50)
    value = models.DecimalField(max_digits=5, decimal_places=2)

Why it works:

• Single model works with any entity type
• No schema changes when adding new entity types
• Cleaner queries: RatingFactor.objects.filter(content_type=app_ct, object_id=id)
• Easier to test with mock objects

---

❌ BAD: Storing Complex Business Logic in Model Fields

class Policy(BaseModel):
    # Mixing data storage with business logic
    policy_number: str = models.CharField(max_length=100)

    def save(self, *args, **kwargs):
        # Complex side effects on every save
        self.policy_number = self.generate_policy_number_with_validation()
        self.update_rating()
        self.sync_with_salesforce()
        super().save(*args, **kwargs)

Why it fails:

• Model.save() becomes a dumping ground for side effects
• Impossible to update fields without triggering full flow
• Celery tasks can't reuse logic (they call save())
• Tests require mocking everything

✅ GOOD: Keep Models Simple, Use Service Layer

# model.py - just data storage
class Policy(BaseModel):
    policy_number: str = models.CharField(max_length=100)
    status: str = models.CharField(max_length=20)

# services.py - business logic
class PolicyService:
    @staticmethod
    def create_policy(carrier_program, application_data) -> Policy:
        policy_number = PolicyService.generate_policy_number(carrier_program)
        policy = Policy.objects.create(
            policy_number=policy_number,
            status='draft'
        )
        return policy

    @staticmethod
    def approve_policy(policy: Policy) -> None:
        policy.status = 'approved'
        policy.save(update_fields=['status'])  # Only update status
        # Trigger async tasks if needed
        sync_with_salesforce_task.delay(policy.id)

Why it works:

• Models stay simple and testable
• Business logic reusable from tasks, APIs, tests
• Explicit dependencies - easier to mock
• Clear separation of concerns

---

❌ BAD: Not Indexing Query Paths

class Policy(BaseModel):
    policy_number: str = models.CharField(max_length=100)
    status: str = models.CharField(max_length=20)
    carrier_program = models.ForeignKey('carrier_program.CarrierProgram', on_delete=models.CASCADE)

    class Meta:
        app_label = 'policy'
        # No indexes - queries will be slow as data grows

✅ GOOD: Index Based on Query Patterns

class Policy(BaseModel):
    policy_number: str = models.CharField(max_length=100)
    status: str = models.CharField(max_length=20)
    carrier_program = models.ForeignKey('carrier_program.CarrierProgram', on_delete=models.CASCADE)

    class Meta:
        app_label = 'policy'
        indexes = [
            models.Index(fields=['policy_number']),  # Frequent exact lookups
            models.Index(fields=['carrier_program', 'status']),  # Filter by program+status
            models.Index(fields=['status', 'created_at']),  # Status + recency queries
        ]
        # If querying by combinations: add compound indexes

Why it works:

• Queries with indexed fields return in milliseconds
• Without indexes, table scans slow as data grows
• Think about actual query patterns in code, then index them

Troubleshooting

Error	Cause	Fix
django.core.exceptions.FieldError: Local field 'field_name' in class 'ModelName' clashes with field of the same name from base class	Field defined in both BaseModel and your model	Remove field - BaseModel already has id, created_at, updated_at
psycopg2.errors.UndefinedColumn: column "tablename"."fieldname" does not exist	Field added to model but migration not applied	Run python manage.py migrate appname
TypeError: <class 'MyModel'> is not JSON serializable	Model instance in JSONField without encoder	Add encoder=PydanticEncoder to JSONField
ValueError: null=True and blank=True	Setting null=True without considering semantics	null=True for DB-level NULL; blank=True for forms; use both only when optional

Debug mode for migrations:

# See SQL being executed
python manage.py migrate appname --verbosity=3

# Dry run - see what would happen
python manage.py migrate appname --plan

Performance Considerations

Scale factors:

• Compound indexes are critical - single-column indexes don't help composite queries
• JSONField queries without proper indexing scan entire column
• ForeignKey relationships without select_related() cause N+1 queries
• Generic relations can't be indexed as efficiently - only use when necessary

Optimization tips:

• Add compound indexes for common query patterns: models.Index(fields=['program_id', 'status']) for queries filtering both fields
• Use select_related() in queries: Policy.objects.select_related('carrier_program') reduces queries from N+1 to 1
• Use only() for large models: Policy.objects.only('id', 'policy_number') avoids loading unnecessary columns
• Batch operations with bulk_create(): For >100 creates, use Model.objects.bulk_create(instances) instead of loop

Benchmarks (typical PostgreSQL on modern hardware):

# Single row by indexed field: ~1-2ms
SELECT * FROM policy WHERE policy_number = 'POL-2024-001';

# Filter by two indexed fields: ~2-3ms
SELECT * FROM policy WHERE carrier_program_id = 1 AND status = 'approved';

# Unindexed scan of 100k rows: ~50-100ms (slow!)
SELECT * FROM policy WHERE notes LIKE '%term%';  # No index, full table scan

Advanced Usage

Advanced Technique 1: Using Q Objects for Complex Queries

When you need complex filtering logic in the model or service layer:

from django.db.models import Q
from common.models import BaseModel

class Quote(BaseModel):
    """Quote model for querying multiple conditions."""

# Query using Q objects for OR/AND logic
quotes = Quote.objects.filter(
    Q(status='approved') | Q(expires_at__gte=now)  # Approved OR not expired
)

# Complex: approved quotes from specific programs
from datetime import datetime
quotes = Quote.objects.filter(
    (Q(status='approved') | Q(status='pending')) &
    Q(application__carrier_program__in=[1, 2, 3]) &
    Q(created_at__gte=datetime(2024, 1, 1))
)

When to use: Complex filtering that's hard to express with simple .filter() calls. Easier to test logic when extracted into service methods.

Advanced Technique 2: Custom Managers for Common Queries

Define custom managers to encapsulate frequent query patterns:

from django.db import models
from common.models import BaseModel

class ApprovedPoliciesManager(models.Manager):
    """Manager for approved policies - encapsulates common filtering."""

    def get_queryset(self):
        return super().get_queryset().filter(status='approved')

    def by_carrier(self, carrier_id):
        return self.filter(carrier_program_id=carrier_id)

class Policy(BaseModel):
    """Policy model with custom manager."""

    status: str = models.CharField(max_length=20)
    carrier_program = models.ForeignKey('carrier_program.CarrierProgram', on_delete=models.PROTECT)

    # Add custom manager
    approved = ApprovedPoliciesManager()

# Usage - much cleaner
approved_policies = Policy.approved.by_carrier(1)  # Already filtered to approved

When to use: Queries used in multiple places or complex filtering logic. Makes code more readable and DRY.

Integration with Other Tools

Works well with:

• pytest fixtures: Use model factories in test conftest.py for creating test instances
• Django REST framework serializers: Serialize model instances to JSON for APIs
• Celery tasks: Reference model IDs in tasks, instantiate in task handlers
• Django admin: Automatically register models for admin interface management

Testing notes:

• Use pytest-django for model testing
• Mock external API calls in service layer tests
• Use factory_boy for generating test instances with realistic data

Related Skills

• django-service-layer - Use for business logic around model creation/updates
• django-migrations - Use when modifying existing models or dealing with complex migrations
• django-api-design - Use when exposing models through REST endpoints

Maintenance Notes

Last updated: October 2024

Known issues:

• UUID primary keys require PostgreSQL or explicit UUID support in other databases
• SimpleHistory package may conflict with custom save() methods

Tested with:

• Django 4.2+
• Python 3.9+
• PostgreSQL 13+
• Pydantic 2.x