Database Models Reference¶

Complete reference for all database models in Bifolk, organized by app.

Target Audience: Software developers

Overview¶

Bifolk uses Django's ORM with 31+ models across 8 apps. Key design patterns:

Organization-based data isolation: All business models have an organization ForeignKey
Permission helpers: Models implement user_can_view(), user_can_edit(), user_can_delete()
Audit trails: Most models track created_by, created_at, updated_at
Translatable fields: SystemConfig models support English and German labels

Note

For exact field definitions and line numbers, see the internal AI reference at docs/claude/01-MODELS.md.

Organizations App¶

Organization¶

Multi-tenant organization entity.

Field	Type	Description
`name`	CharField(200)	Organization name
`org_type`	CharField(20)	personal, family, cooperative, commercial, club
`description`	TextField	Optional description
`is_active`	BooleanField	Active status
`logo`	ImageField	Auto-resized to 300x300px
`members`	ManyToManyField(User)	Through OrganizationMembership

Key methods: get_owners(), get_admins(), user_is_member(user), user_role(user)

OrganizationMembership¶

User-Organization relationship with role-based access.

Field	Type	Description
`organization`	FK(Organization)	Organization (CASCADE)
`user`	FK(User)	User (CASCADE)
`role`	CharField(20)	owner, admin, member, viewer
`invited_by`	FK(User)	Who invited (SET_NULL)
`is_active`	BooleanField	Active membership

Constraint: Unique (organization, user)

Key methods: can_manage_members(), can_delete_organization(), can_edit_resources(), can_delete_resources()

OrganizationInvitation¶

Email invitation system for organization members.

Field	Type	Description
`email`	EmailField	Recipient email
`role`	CharField(10)	Role assigned on acceptance
`token`	UUIDField	Unique invitation token
`status`	CharField(10)	pending, accepted, declined, expired
`expires_at`	DateTimeField	Auto-set to 7 days

Key methods: is_valid(), accept(user), decline()

OrganizationSettings¶

Organization-specific preferences (1-to-1 with Organization).

Field	Type	Description
`date_format`	CharField(20)	Python date format string
`time_zone`	CharField(50)	Organization timezone
`unit_system`	CharField(10)	metric or imperial
`language`	CharField(10)	Preferred language

Users App¶

Profile¶

Extends Django's User model (1-to-1). Auto-created via signal on user registration.

Field	Type	Description
`user`	OneToOneField(User)	Django User (CASCADE)
`image`	ImageField	Profile picture, auto-resized to 300x300
`language`	CharField(7)	Preferred language (en or de)

Hives App¶

The largest app, containing hive management, queens, inspections, operations, harvests, and honey traceability.

Hive¶

Main hive tracking model.

Field	Type	Description
`name`	CharField(100)	Hive name
`hive_type`	CharField(20)	Configurable via SystemConfig
`location`	CharField(200)	Physical location
`organization`	FK(Organization)	Owner organization
`created_by`	FK(User)	Creator
`health_status`	CharField(20)	Configurable health status
`is_active`	BooleanField	Whether hive is active

Relationships: Has one Queen (optional), many Inspections, many HarvestRecords, many Operations, many HivePhotos.

BreedingHive¶

Specialized hive for queen breeding (Multi-Table Inheritance from Hive). Cannot be split via ColonySplit.

Queen¶

Queen bee tracking with lineage support.

Field	Type	Description
`hive`	OneToOneField(Hive)	Associated hive (CASCADE)
`breed`	CharField(100)	Queen breed
`date_introduced`	DateField	Introduction date
`marking_color`	CharField(20)	International color code (white, yellow, red, green, blue, unmarked)
`origin`	CharField(20)	bred_here, purchased, swarm, supersedure, etc.
`mother_queen`	FK('self')	Self-referential for lineage (SET_NULL)
`breeding_record`	FK(QueenBreeding)	Related breeding record (SET_NULL)
`identification_number`	CharField(50)	Unique ID or registry number

Properties: age_in_days, age_in_years Lineage methods: get_ancestors(generations), get_descendants(), get_lineage_depth()

HiveInspection¶

Individual hive inspection records.

Field	Type	Description
`hive`	FK(Hive)	Hive inspected (CASCADE)
`inspection_date`	DateField	Date of inspection
`inspector`	FK(User)	Who inspected
`frames_of_brood`	IntegerField	Brood frame count
`frames_of_honey`	IntegerField	Honey frame count
`queen_seen`	BooleanField	Queen observed
`signs_of_disease`	BooleanField	Disease observed
`temperament`	CharField(20)	calm, moderate, aggressive

BeekeepingOperation (Abstract)¶

Abstract base model for all beekeeping operations. Provides common fields:

Field	Type	Description
`organization`	FK(Organization)	Owner (CASCADE)
`created_by`	FK(User)	Creator (SET_NULL)
`assigned_to`	FK(User)	Assigned user (SET_NULL)
`scheduled_date`	DateField	Scheduled date
`completed_date`	DateField	Completion date
`status`	CharField(15)	planned, in_progress, completed, cancelled
`priority`	CharField(10)	low, medium, high, urgent
`cost`	DecimalField(8,2)	Cost in euros

Concrete subclasses:

Model	Purpose	Key Extra Fields
HiveFeeding	Feeding records	`hive`, `feed_type`, `quantity`, `ratio`, `inventory_item`
HiveTreatment	Pest/disease treatments	`hive`, `treatment_type`, `product_name`, `dosage`, `effectiveness`
HiveMaintenance	Equipment maintenance	`hive`, `maintenance_type`, `description`, `parts_used`
HiveCombine	Colony combining	`primary_hive`, `secondary_hive`, `method`, `is_successful`
QueenReplacement	Requeening	`hive`, `old_queen`, `new_queen`, `replacement_method`, `acceptance_confirmed`

OperationPhoto¶

Photo documentation for any beekeeping operation.

HivePhoto¶

Photo documentation for hives.

Honey Traceability Chain¶

Four models form a complete traceability chain from harvest to final product:

HarvestRecord¶

Individual harvest from a hive.

Field	Type	Description
`hive`	FK(Hive)	Source hive (CASCADE)
`harvest_date`	DateField	Date of harvest
`harvested_by`	FK(User)	Who harvested
`weight_kg`	DecimalField(6,2)	Weight in kg
`honey_type`	CharField(100)	Configurable honey type

HoneyBatch (Topf)¶

Aggregation of multiple harvests into a batch.

HoneyBucket (Eimer)¶

Bucket-level tracking from a batch.

HoneyJar (Glas)¶

Final product jar from a bucket.

HealthStatusChange¶

Automatic history record created when a hive's health status changes (via signal).

QueenHealthStatusChange¶

Automatic history record for queen health status changes.

Breeding App¶

QueenBreeding¶

Queen rearing records with detailed breeding timeline.

Field	Type	Description
`breeding_date`	DateField	Start date
`breeding_method`	CharField(20)	grafting, natural, jenter, nicot, walk_away
`status`	CharField(20)	planning through laying or failed
`organization`	FK(Organization)	Owner
`mother_hive`	FK(Hive)	Genetic source hive
`cells_started`	IntegerField	Cells started
`queens_emerged`	IntegerField	Queens emerged
`queens_mated`	IntegerField	Successfully mated

Property: success_rate - acceptance rate percentage

ColonySplit¶

Colony splitting and reproduction records.

Field	Type	Description
`split_date`	DateField	Date of split
`split_type`	CharField(20)	split, walk_away, nucleus, swarm_capture, etc.
`parent_hive`	FK(Hive)	Original hive
`new_hive`	FK(Hive)	Resulting hive
`frames_transferred`	IntegerField	Frames moved
`is_successful`	BooleanField	Whether split succeeded

Note

ColonySplit validation prevents splitting BreedingHive instances.

Warehouse App¶

WarehouseLocation¶

Storage locations within an organization.

InventoryItem¶

Inventory tracking for equipment, products, and supplies.

Field	Type	Description
`name`	CharField(200)	Item name
`category`	CharField(20)	equipment, product, supply
`item_type`	CharField(30)	Specific type within category (ConfigurableChoice, code: `item_type`)
`system_item_type`	CharField(30)	System identifier: none, bucket, jar, feeding_material
`quantity`	DecimalField(10,2)	Current quantity
`unit`	CharField(20)	piece, kg, liter, jar, box, frame
`min_quantity`	DecimalField(10,2)	Minimum stock level
`unit_cost`	DecimalField(10,2)	Cost per unit
`organization`	FK(Organization)	Owner

Property: is_low_stock - whether quantity is below minimum

InventoryTransaction¶

All inventory movements (additions and reductions).

Field	Type	Description
`item`	FK(InventoryItem)	Item (CASCADE)
`transaction_type`	CharField(20)	purchase, sale, production, usage, harvest, loss, adjustment, transfer
`quantity_change`	DecimalField(10,2)	Change (±)
`quantity_before`	DecimalField(10,2)	Previous quantity
`quantity_after`	DecimalField(10,2)	New quantity

Automatically updates InventoryItem.quantity on save.

ProductSale¶

Sales tracking with line items.

ProductSaleItem¶

Individual items in a sale. Automatically creates InventoryTransaction on save.

SystemConfig App¶

ChoiceCategory¶

Groups of configurable dropdown choices (e.g., hive_style, honey_type, feeding_type).

ConfigurableChoice¶

Individual choice values with multi-language support.

Field	Type	Description
`category`	FK(ChoiceCategory)	Parent category
`organization`	FK(Organization)	NULL = global, set = org-specific
`value`	CharField(100)	Internal value
`label_en`	CharField(200)	English label
`label_de`	CharField(200)	German label
`is_active`	BooleanField	Available for selection

Constraint: Unique (category, value, organization)

Notifications App¶

Notification¶

In-app notification for users.

DataExchange App¶

ExportJob¶

Organization data export operations.

ImportJob¶

Organization data import operations.

Entity Relationship Summary¶

User ──┬── Profile (1:1)
       │
       └── OrganizationMembership ── Organization ──┬── OrganizationSettings (1:1)
                                                     │
                                                     ├── Hive ──┬── Queen (1:1)
                                                     │          ├── HiveInspection
                                                     │          ├── HarvestRecord → HoneyBatch → HoneyBucket → HoneyJar
                                                     │          ├── HiveFeeding
                                                     │          ├── HiveTreatment
                                                     │          ├── HiveMaintenance
                                                     │          ├── HivePhoto
                                                     │          └── HealthStatusChange
                                                     │
                                                     ├── HiveCombine (refs 2 Hives)
                                                     ├── QueenReplacement (refs Hive + 2 Queens)
                                                     │
                                                     ├── QueenBreeding → Queen.breeding_record
                                                     ├── ColonySplit (refs 2 Hives)
                                                     │
                                                     ├── InventoryItem ── InventoryTransaction
                                                     ├── ProductSale ── ProductSaleItem
                                                     ├── WarehouseLocation
                                                     │
                                                     └── ConfigurableChoice

Architecture Overview - System design patterns
Permissions System - RBAC implementation
App Reference - Per-app detailed documentation
Internal AI Reference: docs/claude/01-MODELS.md for exact field definitions and line numbers