Home App Reference¶
The Home app provides the main dashboard, Progressive Web App (PWA) functionality, shared view and form mixins, template tags, a health check endpoint, and legal pages used across the entire application.
Overview¶
Location: app/home/
Purpose: Dashboard, PWA support, shared mixins, template tags, health check, legal pages
URL Namespace: home:
Dependencies: hives, breeding, warehouse, organizations, notifications, systemconfig, users, dataexchange
Models¶
The Home app has no database models. It aggregates data from other apps.
File Structure¶
home/
├── views.py # Dashboard views (home, work)
├── views_pwa.py # PWA views (manifest, offline, CSRF)
├── views_health.py # Health check endpoint for container orchestration
├── views_legal.py # Legal pages (cookie policy)
├── mixins.py # Shared view mixins for all apps
├── form_mixins.py # Shared form mixins (date range validation)
├── urls.py # URL routing + PWA routes
├── context_processors.py # Global template context (10 processors)
├── templatetags/
│ ├── icon_tags.py # Centralized entity icon registry
│ ├── status_tags.py # Status badge colors
│ └── table_helpers.py # Sortable table header tags
├── management/
│ └── commands/
│ └── load_sample_data.py # Sample data loader
├── static/home/
│ ├── main.css # Main application styles
│ ├── sidebar.css # Sidebar navigation styles
│ ├── sidebar.js # Sidebar toggle logic
│ └── quick_create.js # Quick operation creation + offline support
├── static/vendor/ # Self-hosted third-party libraries (GDPR compliance)
│ ├── bootstrap/ # Bootstrap CSS + JS bundle
│ ├── bootstrap-icons/ # Bootstrap Icons font (CSS + woff/woff2)
│ ├── chart.js/ # Chart.js UMD bundle
│ ├── chartjs-adapter-date-fns/ # Chart.js date/time adapter
│ ├── leaflet/ # Leaflet maps (CSS, JS, marker images)
│ └── vis-network/ # vis-network graph library (standalone UMD)
├── static/pwa/
│ ├── service-worker.js # Service worker with caching strategies
│ ├── pwa-init.js # PWA registration & update handling
│ ├── offline-sync.js # IndexedDB offline operation queue
│ └── icons/ # PWA app icons (192x192, 512x512)
├── templates/home/
│ ├── base.html # Main layout with PWA meta tags
│ ├── _sidebar.html # Sidebar navigation with pending ops badge
│ ├── _quick_create_panel.html
│ ├── home.html # Dashboard view
│ └── cookie_policy.html # Cookie policy page
└── templates/pwa/
├── manifest.json # Dynamic PWA manifest (Django template)
└── offline.html # Offline fallback page
Views¶
Dashboard Views¶
home(request) (views.py)
Main dashboard view showing aggregated statistics across all user organizations.
- URL:
/-- Name:home-home - Authentication: Optional (landing page for anonymous, dashboard for authenticated)
- Template:
home/home.html
Context Data (authenticated users):
| Variable | Type | Description |
|---|---|---|
total_hives |
int | Total hives across user organizations |
active_hives |
int | Active hives (is_active=True) |
hives_needing_inspection |
int | Hives not inspected in last 7 days |
total_honey_harvested |
Decimal | Total honey (kg) harvested this year |
recent_harvests |
QuerySet | Last 5 harvest records |
batches_this_year |
dict | Batch count stats: total, open_count |
jars_in_inventory |
int | Jars with status 'in_inventory' |
upcoming_activities |
list | Next 5 upcoming operations (sorted by scheduled_date) |
overdue_activities |
int | Count of overdue operations |
hives_by_health |
dict | Hive count by health status |
health_status_choices |
QuerySet | Configured health status options |
queens_by_health |
dict | Queen count by health status |
total_queens |
int | Total active queens |
queens_young |
int | Queens less than 1 year old |
queens_prime |
int | Queens 1-2 years old |
aging_queens |
int | Queens older than 2 years |
recent_inspections |
QuerySet | Last 5 inspections |
active_breeding |
int | Active breeding programs |
recent_splits |
int | Colony splits in last 7 days |
low_stock_items |
int | Inventory items below minimum quantity |
total_sales |
Decimal | Total sales amount this year |
recent_sales |
QuerySet | Last 5 product sales |
current_year |
int | Current year |
work(request) (views.py)
Work dashboard view. Currently a placeholder for task/project management.
- URL:
/work-- Name:home-work
Health Check View¶
health_check(request) (views_health.py)
Lightweight health check endpoint for container orchestration (Docker, Kubernetes).
- URL:
/health/-- Name:health-check - Authentication: None required
- CSRF: Exempt
- Response: JSON with health status and database connectivity
- HTTP Status: 200 (healthy) or 503 (unhealthy)
- Cache: 10 seconds (
Cache-Control: public, max-age=10)
Legal Views¶
cookie_policy(request) (views_legal.py)
Displays the cookie policy page for GDPR compliance.
- URL:
/cookie-policy/-- Name:cookie-policy - Authentication: None required
PWA Views¶
manifest_json(request) (views_pwa.py)
Serves a dynamic PWA web app manifest.
- URL:
/pwa/manifest.json-- Name:pwa-manifest - Injects
org_colors.primaryastheme_color - Supports i18n (language-specific descriptions)
- Content-Type:
application/manifest+json
offline_view(request) (views_pwa.py)
Offline fallback page served when user has no network connection.
- URL:
/pwa/offline/-- Name:pwa-offline - Lists available cached pages
- Auto-reloads when connection is restored
csrf_token_view(request) (views_pwa.py)
Provides fresh CSRF tokens for offline form sync.
- URL:
/accounts/csrf/-- Name:csrf-token - Never cached (
Cache-Control: no-store) - Returns JSON response
Shared View Mixins¶
Location: app/home/mixins.py
These mixins are used across all apps for consistent permission checking and list functionality.
Permission Mixins¶
| Mixin | Purpose | Used By |
|---|---|---|
| OrgCreatePermissionMixin | Check org-level create permission | CreateViews |
| ViewPermissionMixin | Check object-level view permission | DetailViews |
| EditPermissionMixin | Check object-level edit permission | UpdateViews |
| DeletePermissionMixin | Check object-level delete permission | DeleteViews |
| OrgFilterMixin | Filter queryset by user organizations | ListViews |
List View Mixins¶
| Mixin | Purpose | Used By |
|---|---|---|
| SortableListMixin | Column sorting via GET params (sort, order) | Sortable tables |
| FilterableListMixin | Filter form support for ListViews | Filtered lists |
| SortableFilterableListMixin | Combined sorting + filtering | Lists needing both |
Shared Form Mixins¶
Location: app/home/form_mixins.py
Reusable form mixins for common validation and initialization patterns.
| Mixin | Purpose | Used By |
|---|---|---|
| DateRangeValidationMixin | Validates end_date is not before start_date | Filter forms with date ranges |
| DefaultDateRangeMixin | Sets default start_date (1 year ago) and end_date (today) | Filter forms needing defaults |
| DateRangeFilterMixin | Combined defaults + validation (recommended) | All date-range filter forms |
Template Tags¶
Icon Tags (templatetags/icon_tags.py)¶
Centralized entity icon registry for consistent visual language.
Tags:
| Tag | Purpose | Usage |
|---|---|---|
entity_icon |
Get icon class string | {% entity_icon 'hive' %} returns bi-hexagon |
entity_icon_html |
Get full HTML element | {% entity_icon_html 'queen' 'me-1' %} |
get_entity_icon_map |
Get full map for JS/iteration | {% get_entity_icon_map as icons %} |
Icon Map (complete):
| Entity | Icon |
|---|---|
| hive | bi-hexagon |
| queen | bi-star |
| breeding_hive | bi-hexagon-half |
| harvest | bi-droplet |
| batch | bi-archive |
| bucket | bi-bucket |
| jar | bi-cup |
| feeding | bi-cup-straw |
| treatment | bi-capsule |
| maintenance | bi-tools |
| inspection | bi-clipboard-check |
| breeding | bi-diagram-3 |
| split | bi-diagram-2 |
| lineage | bi-diagram-3 |
| warehouse | bi-box-seam |
| inventory | bi-box-seam |
| location | bi-geo-alt |
| transaction | bi-arrow-left-right |
| sale | bi-currency-dollar |
| organization | bi-building |
| weight | bi-speedometer2 |
| info | bi-info-circle |
| notes | bi-journal-text |
| reports | bi-graph-up |
| dashboard | bi-speedometer2 |
| settings | bi-gear |
| system | bi-gear |
Status Tags (templatetags/status_tags.py)¶
Status badge colors for consistent styling across all templates.
Tags:
| Tag/Filter | Purpose | Usage |
|---|---|---|
status_color |
Get Bootstrap color class | {% status_color 'completed' %} returns success |
status_badge |
Full HTML badge | {% status_badge jar.status jar.get_status_display %} |
priority_badge |
Priority badge (convenience wrapper) | {% priority_badge feeding.priority %} |
get_item (filter) |
Dictionary access with dynamic key | {{ hives_by_health|get_item:choice.value }} |
Table Helpers (templatetags/table_helpers.py)¶
Tags for creating sortable table headers and preserving query strings across pagination.
Tags:
| Tag/Filter | Purpose | Usage |
|---|---|---|
sortable_header |
Sortable <th> with link and sort icon |
{% sortable_header 'name' 'Item Name' current_sort current_order %} |
query_string |
Build query string preserving GET params | {% query_string page=2 %} |
table_sort_icon |
Get sort icon class only | {% table_sort_icon 'name' current_sort current_order %} |
next_sort_order (filter) |
Toggle between asc/desc | {{ current_order|next_sort_order }} |
Context Processors¶
Location: app/home/context_processors.py
10 context processors registered in settings.py. Available in all templates:
| Variable | Description |
|---|---|
DOCS_URL |
Documentation link with language suffix (/de/ for German) |
user_role |
User's role in current organization |
user_is_org_manager |
True if user is owner/admin of any org |
user_is_org_owner |
True if user is owner of current org |
user_is_org_admin |
True if user is admin of current org |
org_colors |
Organization color scheme (primary, secondary) |
VERSION |
Application version |
allow_self_registration |
Whether self-registration is enabled |
disable_standard_login |
Hides standard login form for OIDC-only setups |
COOKIE_CONSENT_VERSION |
Cookie consent version for GDPR banner |
COOKIE_CONSENT_ANALYTICS_ENABLED |
Whether analytics cookies are configured |
user_theme_preference |
User's theme: 'light', 'dark', or 'system' |
show_changelog_modal |
True when user has not seen current version's changelog |
changelog_version |
Current application version string |
Management Commands¶
load_sample_data¶
Loads sample data for development and demonstration purposes.
Creates 5 users, 2 organizations, and comprehensive beekeeping data including hives, queens, inspections, harvests, honey batches, breeding records, inventory items, operations, and notifications. Delegates to dataexchange.services.sample_data_service.
Progressive Web App (PWA)¶
Service Worker (static/pwa/service-worker.js)¶
Caching Strategies:
- Network-First: HTML pages (3-second timeout, then cache fallback)
- Cache-First: Static assets (CSS, JS, images, fonts, CDN resources)
- Network-Only: Admin, auth, mutation requests (POST/PUT/DELETE)
Pre-Cached Assets: Home dashboard, work dashboard, offline page, main CSS, logo, local vendor assets
Message Handlers:
ORG_SWITCH: Clears dynamic cache, re-caches pages for new orgLANG_CHANGE: Clears HTML cache to refresh translationsSKIP_WAITING: Forces immediate activation on update
Offline Sync (static/pwa/offline-sync.js)¶
IndexedDB Schema:
- Database:
bifolk-offline - Store:
pending-operations - Supported types: feeding, treatment, maintenance, inspection, harvest
Sync Behavior:
- Syncs on page load (if online)
- Syncs on connection restore (
onlineevent) - Manual sync via sidebar button
- Retry with exponential backoff (max 3 retries)
- CSRF token auto-refresh on 403 response
Global API: window.bifolkOfflineSync provides addOperation(), getPendingOperations(), getPendingCount(), syncPendingOperations()
Quick Create Offline Support (static/home/quick_create.js)¶
When offline, operation creation shows a modal instead of redirecting. The user fills in date and notes, and the operation is queued in IndexedDB for later sync.