Reporting App Reference¶

The Reporting app provides centralized reporting and analytics across the Bifolk application. It consolidates hive performance reports, warehouse analytics, operations cost tracking, and honey pipeline traceability into a single reporting hub with date-range filtering and chart visualizations.

Overview¶

Location: app/reporting/

Purpose: Consolidated reporting and analytics with chart visualizations and date-range filtering

Key Models: None (reads from models in hives, warehouse, and organizations apps)

Dependencies: hives, warehouse, organizations, systemconfig

File Structure¶

reporting/
├── apps.py                # AppConfig
├── models.py              # Empty (no own models)
├── admin.py               # Empty
├── tests.py               # Empty
├── utils.py               # Date range utility (get_default_date_range)
├── urls.py                # 8 URL patterns
├── views/
│   ├── __init__.py        # Re-exports all views
│   ├── hive_reports.py    # 4 views (harvest, metrics, health, moisture)
│   ├── honey_reports.py   # 1 view (honey pipeline)
│   ├── warehouse_reports.py  # 2 views (inventory value, sales summary)
│   └── operations_reports.py # 1 view (operations cost)
├── forms/
│   ├── __init__.py        # Re-exports all forms
│   ├── filter_forms.py    # 3 forms (hive report filters)
│   └── warehouse_filters.py  # 4 forms (warehouse/operations/honey filters)
├── templates/reporting/
│   ├── harvest_report.html
│   ├── metrics_dashboard.html
│   ├── health_changes_report.html
│   ├── moisture_report.html
│   ├── honey_pipeline_report.html
│   ├── inventory_value_report.html
│   ├── sales_summary_report.html
│   └── operations_cost_report.html
└── migrations/

Views¶

All views require authentication (@login_required or LoginRequiredMixin) and respect the site-wide organization selector via request.current_organization.

Hive Reports (`views/hive_reports.py`)¶

View	Type	URL Name	Purpose
`harvest_report`	FBV	`reporting:harvest-report`	Harvest statistics with per-hive breakdown and monthly trends
`hive_metrics_dashboard`	FBV	`reporting:hive-metrics-dashboard`	Hive weight and box count trends with seasonal forecasts
`health_changes_report`	FBV	`reporting:health-changes-report`	Timeline of health status changes and inspection observations
`MoistureReportView`	CBV (TemplateView)	`reporting:moisture-report`	Moisture content statistics grouped by batch/charge

Warehouse Reports (`views/warehouse_reports.py`)¶

View	Type	URL Name	Purpose
`inventory_value_report`	FBV	`reporting:inventory-value-report`	Total inventory value by category and location with low stock alerts
`sales_summary_report`	FBV	`reporting:sales-summary-report`	Revenue by date range, payment methods, and top selling products

Operations Reports (`views/operations_reports.py`)¶

View	Type	URL Name	Purpose
`operations_cost_report`	FBV	`reporting:operations-cost-report`	Operations costs by type (feeding, treatment, maintenance) with per-hive breakdown

Honey Reports (`views/honey_reports.py`)¶

View	Type	URL Name	Purpose
`honey_pipeline_report`	FBV	`reporting:honey-pipeline-report`	Full traceability from harvest to jar with pipeline summary

View Details¶

harvest_report¶

Comprehensive harvest reporting with summary statistics, per-hive breakdown, and monthly trends.

Data Provided:

Summary statistics: Total harvests, total weight (kg), average weight, total frames
Per-hive breakdown: Equal-share weight distribution for multi-hive harvests, ordered by total weight
Monthly breakdown: Harvest count, total weight, average weight, total frames per month
Chart data: JSON arrays for monthly weight trends, harvest counts, and hive comparison bar chart
Average harvest per hive: Computed from hive breakdown

Filter Form: HarvestReportFilterForm (date range, hive selection)

hive_metrics_dashboard¶

Dashboard showing hive weight and box count trends over time with seasonal forecasts.

Data Provided:

Summary statistics: Total inspections, inspections with weight, average/min/max weight, average boxes
Per-hive data: Latest weight, latest box count, inspection count per hive (sorted by name)
Monthly breakdown: Inspection count, average weight, average boxes per month
Per-hive weight trends: Time-series data for up to 5 hives (multi-line chart)
Seasonal forecasts: Forecast display data via HoneyForecastService for up to 5 hives

Filter Form: HiveMetricsFilterForm (date range, hive selection)

Special behavior: Redirects to self with default date parameters on first load (no GET parameters).

health_changes_report¶

Health changes report with a combined timeline of hive status changes, queen status changes, and inspections with health issues.

Data Provided:

Timeline events: Merged and reverse-chronologically sorted list of:
- Hive health status changes (type: hive_status_change)
- Queen health status changes (type: queen_status_change)
- Inspections with issues: disease, pests, or aggressive temperament (type: inspection)
Summary statistics: Hives monitored, health change counts, inspections with issues, days monitored
Status distribution: Current health status counts across selected hives
Per-hive summaries: Change count, inspection count, last inspection (limited to 20 hives)
Health trend charts: Numeric health status values over time for up to 5 hives (hive and queen)

Filter Form: HealthChangesReportFilterForm (date range, hive selection, include inspections toggle)

MoistureReportView¶

Class-based view for displaying moisture content report across honey buckets.

Data Provided:

Overall statistics: Total bucket count, average/min/max moisture percentage
Bucket list: All buckets with moisture data, ordered by filled date (descending)
By charge: Moisture statistics grouped by charge identifier, honey type, and year

Filtering: Simple date range via GET parameters (start_date, end_date), no dedicated form class.

inventory_value_report¶

Inventory value report showing total value by category and location with low stock alerts.

Data Provided:

Summary statistics: Total items, total quantity, total value, low stock count
Value by category: Total value, item count, total quantity per category (equipment, product, supply)
Value by location: Total value and item count per warehouse location
Low stock items: Items where quantity is below minimum (limited to 20)
Chart data: JSON arrays for category breakdown pie/bar chart

Filter Form: InventoryValueFilterForm (category, location, show low stock only)

sales_summary_report¶

Sales summary report showing revenue, payment methods, and top selling products.

Data Provided:

Summary statistics: Total sales count, total revenue, unpaid count/total, average sale amount
Revenue by payment method: Total and count per payment method
Monthly revenue: Monthly total and count trend
Top products: Top 10 products by total revenue (quantity, revenue, sale count)
Unpaid sales: Most recent 10 unpaid sales
Chart data: JSON arrays for monthly revenue trend chart

Filter Form: SalesSummaryFilterForm (date range, payment status)

operations_cost_report¶

Operations cost report showing costs by operation type with per-hive breakdown and monthly trends.

Data Provided:

Summary statistics: Total cost, cost per type, hive count, average cost per hive, operation count
Cost by type: Feeding, treatment, and maintenance cost and count
Cost per hive: Per-hive breakdown of feeding/treatment/maintenance costs (limited to 20 hives, sorted by total)
Monthly cost trend: Stacked bar chart data with feeding/treatment/maintenance per month
Pie chart data: Cost distribution by operation type

Filter Form: OperationsCostFilterForm (date range, operation type, hive)

honey_pipeline_report¶

Honey pipeline report showing full traceability from harvest to final jar status.

Data Provided:

Pipeline summary: Total kg harvested, in buckets, in jars; counts of harvests, batches, buckets, jars
Harvest by type: Total weight, harvest count, average weight per honey type
Batch summary: Open/closed batch counts by honey type
Bucket summary: Total buckets, total weight, average moisture per honey type
Jar status distribution: Count and total weight per jar status (with display names)
Recent batches: Last 5 batches with related data
Chart data: JSON arrays for harvest-by-type and jar status distribution charts

Filter Form: HoneyPipelineFilterForm (date range)

Forms¶

Hive Report Filters (`forms/filter_forms.py`)¶

Form	Fields	Purpose
`HarvestReportFilterForm`	start_date, end_date, hives (multi-select)	Filter harvest reports by date range and hive
`HealthChangesReportFilterForm`	start_date, end_date, hives (multi-select), include_inspections (checkbox)	Filter health reports with inspection toggle
`HiveMetricsFilterForm`	start_date, end_date, hives (multi-select)	Filter metrics dashboard by date range and hive

Common patterns:

All forms accept user and current_organization in the constructor
Hive querysets are dynamically filtered by user's accessible organizations
Default date range is set from user's profile preference via get_default_date_range()
All forms validate that start date is before end date

Warehouse and Operations Filters (`forms/warehouse_filters.py`)¶

Form	Fields	Purpose
`InventoryValueFilterForm`	category (choice), location (model choice), show_low_stock_only (checkbox)	Filter inventory value report
`SalesSummaryFilterForm`	start_date, end_date, payment_status (choice: all/paid/unpaid)	Filter sales summary report
`OperationsCostFilterForm`	start_date, end_date, operation_type (choice: all/feeding/treatment/maintenance), hive (model choice)	Filter operations cost report
`HoneyPipelineFilterForm`	start_date, end_date	Filter honey pipeline report

Utilities (`utils.py`)¶

get_default_date_range(user)¶

Calculates the default date range based on the user's profile preference.

Parameters:

Parameter	Type	Description
`user`	User (optional)	Current user to read preferences from

Returns: Tuple[date, date] (start_date, end_date)

Behavior:

Reads user.profile.default_report_date_range preference
'current_year' (default): January 1^st of current year to today
'last_365_days': 365 days ago to today

URL Configuration¶

All URLs are under the /reports/ prefix (included via path('reports/', include('reporting.urls'))).

URL Pattern	View	Name
`harvest/`	`harvest_report`	`reporting:harvest-report`
`health-changes/`	`health_changes_report`	`reporting:health-changes-report`
`metrics/`	`hive_metrics_dashboard`	`reporting:hive-metrics-dashboard`
`moisture/`	`MoistureReportView`	`reporting:moisture-report`
`inventory-value/`	`inventory_value_report`	`reporting:inventory-value-report`
`sales-summary/`	`sales_summary_report`	`reporting:sales-summary-report`
`operations-cost/`	`operations_cost_report`	`reporting:operations-cost-report`
`honey-pipeline/`	`honey_pipeline_report`	`reporting:honey-pipeline-report`

Chart Visualizations¶

All reports pass chart data as JSON-serialized arrays to templates for client-side rendering. The following chart types are used across reports:

Report	Chart Types	Data Format
Harvest Report	Line chart (monthly weight), bar chart (hive comparison)	Labels + values arrays
Metrics Dashboard	Line chart (avg weight, avg boxes over time), multi-line per-hive weight	Labels + values arrays, per-hive dict
Health Changes	Line chart (health status numeric values over time, per hive and queen)	Per-hive dict with date/value pairs
Operations Cost	Stacked bar chart (monthly costs by type), pie chart (cost distribution)	Labels + per-type value arrays
Honey Pipeline	Pie/bar chart (harvest by type), pie chart (jar status distribution)	Labels + values arrays
Inventory Value	Pie/bar chart (value by category)	Labels + values arrays
Sales Summary	Line chart (monthly revenue)	Labels + values arrays

Organization Filtering¶

All reports respect the site-wide organization selector:

If request.current_organization is set, data is filtered to that organization
Otherwise, data is filtered to all organizations the user has access to (via get_user_organizations())

This ensures multi-tenant data isolation across all reports.

Cross-App Dependencies¶

Dependency	Models Used	Purpose
hives	Hive, HiveInspection, HarvestRecord, HealthStatusChange, QueenHealthStatusChange, HoneyBatch, HoneyBucket, HoneyJar, HiveFeeding, HiveTreatment, HiveMaintenance	Core beekeeping data for hive reports, health reports, honey pipeline
hives.services	HoneyForecastService	Seasonal harvest forecasts in metrics dashboard
warehouse	InventoryItem, ProductSale, ProductSaleItem, WarehouseLocation	Inventory and sales data for warehouse reports
organizations	get_user_organizations, filter_by_user_organizations	Organization-scoped data access
systemconfig	get_queryset_for_category	Health status choice configuration lookup

Key Features¶

8 Report Types: Covering hive performance, health monitoring, honey traceability, warehouse inventory, sales, and operations costs
Date Range Filtering: All reports support configurable date ranges with user preference defaults
Chart Visualizations: JSON-serialized data for client-side chart rendering (line, bar, pie, stacked bar)
Organization-Aware: All reports respect the site-wide organization selector for multi-tenant data isolation
Per-Hive Breakdown: Harvest, metrics, health, and cost reports include per-hive detail
Honey Traceability: Pipeline report traces honey from harvest through batch, bucket, to jar status
Seasonal Forecasts: Metrics dashboard includes weight-based harvest forecasts via HoneyForecastService
User Preference Defaults: Default date range respects user profile setting (current year or last 365 days)

Reporting App Reference¶

Overview¶

File Structure¶

Views¶

Hive Reports (views/hive_reports.py)¶

Warehouse Reports (views/warehouse_reports.py)¶

Operations Reports (views/operations_reports.py)¶

Honey Reports (views/honey_reports.py)¶

View Details¶

harvest_report¶

hive_metrics_dashboard¶

health_changes_report¶

MoistureReportView¶

inventory_value_report¶

sales_summary_report¶

operations_cost_report¶

honey_pipeline_report¶

Forms¶

Hive Report Filters (forms/filter_forms.py)¶

Warehouse and Operations Filters (forms/warehouse_filters.py)¶

Utilities (utils.py)¶

get_default_date_range(user)¶

URL Configuration¶

Chart Visualizations¶

Organization Filtering¶

Cross-App Dependencies¶

Key Features¶

See Also¶

Hive Reports (`views/hive_reports.py`)¶

Warehouse Reports (`views/warehouse_reports.py`)¶

Operations Reports (`views/operations_reports.py`)¶

Honey Reports (`views/honey_reports.py`)¶

Hive Report Filters (`forms/filter_forms.py`)¶

Warehouse and Operations Filters (`forms/warehouse_filters.py`)¶

Utilities (`utils.py`)¶