django-model - Creating Models with Counterpart Patterns

Overview

Django models at Counterpart follow specific patterns: all inherit from

BaseModel

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

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

Cause: Django can't find your model when

app_label

Solution:

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

Prevention: Always include

app_label

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'

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

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

django.core.exceptions.FieldError: Local field 'field_name' in class 'ModelName' clashes with field of the same name from base class

psycopg2.errors.UndefinedColumn: column "tablename"."fieldname" does not exist

python manage.py migrate appname

TypeError: <class 'MyModel'> is not JSON serializable

encoder=PydanticEncoder

ValueError: null=True and blank=True

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()

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