Breeding App Reference¶

The Breeding app manages queen breeding programs and colony reproduction tracking, including grafting, rearing, colony splitting operations, and status audit trails.

Overview¶

Location: app/breeding/

Purpose: Queen breeding programs and colony reproduction

Key Models: QueenBreeding, ColonySplit, BreedingStatusChange, SplitStatusChange

File Structure¶

breeding/
├── models.py              # 4 models (QueenBreeding, ColonySplit, BreedingStatusChange, SplitStatusChange)
├── views.py               # 8 view classes
├── forms.py               # 4 forms (2 model forms + 2 filter forms)
├── urls.py                # 8 URL patterns
├── signals_status.py      # 4 signal handlers (status change tracking)
├── apps.py                # AppConfig with signal import
├── admin.py               # Django admin config
├── tests/                 # Integration tests
│   └── test_breeding_integration.py
└── templates/breeding/    # Breeding and split templates

Models¶

See Database Models - Breeding App for complete field reference.

QueenBreeding¶

Records queen breeding sessions from planning through laying. Uses OrgPermissionMixin with breeder as the permission owner field.

Breeding Methods: Configurable via System Configuration (breeding_method category)

Status Progression:

Planning → Grafted → Accepted → Capped → Emerged → Mated → Laying
    ↓          ↓          ↓         ↓         ↓         ↓
  Failed     Failed     Failed   Failed    Failed    Failed

Each status can transition to "Failed" at any stage. Both "Laying" and "Failed" are terminal states.

Key Fields:

Timeline: breeding_date, graft_date, emergence_date, mating_flight_date, first_laying_date
Outcomes: cells_started, cells_accepted, queens_emerged, queens_mated, queens_successfully_laying
Genetics: mother_hive (genetic source), breeding_hive (operational workspace), drone_source, breed_line
Assessment: quality_rating (configurable via System Configuration)

Property: success_rate -- Calculated as (cells_accepted / cells_started) * 100

Conceptual Separation:

mother_hive (Hive): Production hive providing genetic material (larvae/eggs)
breeding_hive (BreedingHive): Dedicated breeding workspace where queen rearing takes place

Key Methods:

get_status_display() -- Returns human-readable status label from System Configuration
clean() -- Validates status transitions against allowed rules
save(skip_validation=False) -- Runs full validation before saving; pass skip_validation=True for admin overrides

ColonySplit¶

Records colony splitting operations. Uses OrgPermissionMixin with split_by as the permission owner field.

Split Types: Configurable via System Configuration (split_type category)

Status Progression:

Planned → Completed → Queenright
    ↓          ↓     → Queenless → Combined
  Failed       ↓                → Failed
             Combined

"Failed" and "Combined" are terminal states.

Key Fields:

parent_hive, new_hive -- Source and destination hives
frames_transferred, brood_frames, honey_frames -- Frame counts
Queen management: queen_included, queen_cell_added, queen_introduced
Timeline: queen_introduction_date, queen_accepted_date, first_eggs_seen
Activity tracking: assigned_to, scheduled_date, completed_date, priority, cost
is_successful -- Final outcome

Validation: Breeding hives cannot be used as parent_hive or new_hive in splits. This is enforced at both model level (clean()) and form level (ColonySplitForm.clean()).

BreedingStatusChange¶

Tracks historical changes to queen breeding status. Inherits from AbstractStatusChange and uses DelegatedPermissionMixin to delegate permissions to the parent breeding record.

Fields: breeding (FK to QueenBreeding), old_status, new_status, changed_at, changed_by, notes

SplitStatusChange¶

Tracks historical changes to colony split status. Inherits from AbstractStatusChange and uses DelegatedPermissionMixin to delegate permissions to the parent split record.

Fields: split (FK to ColonySplit), old_status, new_status, changed_at, changed_by, notes

Views¶

Queen Breeding¶

View	Purpose
BreedingListView	List breedings with org/method/status/date filters and sortable columns
BreedingDetailView	Display breeding details with permission check
BreedingCreateView	Create breeding record, auto-sets organization and breeder
BreedingUpdateView	Update breeding record with permission check

Colony Splits¶

View	Purpose
SplitListView	List splits with org/type/status/success/date filters and sortable columns
SplitDetailView	Display split details with permission check
SplitCreateView	Create colony split record, auto-sets organization and split_by
SplitUpdateView	Update split record with permission check

All list views use SortableListMixin for column sorting and support pagination (20 items per page).

Forms¶

QueenBreedingForm¶

Model form for creating and editing queen breeding records. Populates choice fields from System Configuration:

breeding_method from breeding_method category
status from breeding_status category
quality_rating from breeding_quality category

Filters mother_hive and breeding_hive querysets to the user's organizations. Validates all choice values against System Configuration.

ColonySplitForm¶

Model form for creating and editing colony split records. Populates choice fields from System Configuration:

split_type from split_type category
status from split_status category
priority from operation_priority category

Filters parent_hive and new_hive querysets to the user's organizations. Prevents breeding hives from being used as the parent hive in splits.

BreedingListFilterForm¶

Filters: organization, breeding_method, status, start_date, end_date. Default date range is the last 365 days.

SplitListFilterForm¶

Filters: organization, split_type, status, is_successful, start_date, end_date. Default date range is the last 365 days.

URL Patterns¶

breeding/                        → BreedingListView (breeding-list)
breeding/<int:pk>/               → BreedingDetailView (breeding-detail)
breeding/new/                    → BreedingCreateView (breeding-create)
breeding/<int:pk>/edit/          → BreedingUpdateView (breeding-update)
breeding/splits/                 → SplitListView (split-list)
breeding/split/<int:pk>/         → SplitDetailView (split-detail)
breeding/split/new/              → SplitCreateView (split-create)
breeding/split/<int:pk>/edit/    → SplitUpdateView (split-update)

Signals¶

The breeding app uses four signal handlers in signals_status.py to automatically track status changes:

Signal	Trigger	Purpose
track_breeding_status_pre_save	QueenBreeding pre_save	Stores previous status for change detection
track_breeding_status_change	QueenBreeding post_save	Creates BreedingStatusChange audit record
track_split_status_pre_save	ColonySplit pre_save	Stores previous status for change detection
track_split_status_change	ColonySplit post_save	Creates SplitStatusChange audit record

Signal handlers are loaded in apps.py when the app is ready.

Integration with Hives App¶

Queen Lineage¶

Queens created through breeding programs link back via breeding_record and mother_queen:

queen = Queen.objects.create(
    hive=new_hive,
    breeding_record=breeding,   # Links to QueenBreeding
    mother_queen=source_queen,  # Links to mother for lineage
    origin='bred_here',
)

Colony Splitting¶

Splits require creating the new hive first, then recording the split:

new_hive = Hive.objects.create(name="Split-1", organization=org)
split = ColonySplit.objects.create(
    parent_hive=existing_hive,
    new_hive=new_hive,
    frames_transferred=5,
)

Breeding Hive Protection¶

Breeding hives (BreedingHive model) cannot be used in colony splits. This is validated at both model and form levels to prevent accidental splitting of dedicated breeding equipment.

System Configuration Categories¶

The breeding app uses the following configurable choice categories:

Category Code	Used By	Purpose
`breeding_method`	QueenBreeding.breeding_method	Available breeding methods
`breeding_status`	QueenBreeding.status	Available breeding statuses
`breeding_quality`	QueenBreeding.quality_rating	Quality rating options
`split_type`	ColonySplit.split_type	Available split types
`split_status`	ColonySplit.status	Available split statuses
`operation_priority`	ColonySplit.priority	Priority levels