Skip to content

Architecture Overview

System architecture and design patterns of the Bifolk beekeeping management application.

Target Audience: Software developers, advanced administrators

Technology Stack

Backend

Component Technology
Framework Django 6.x (Python 3.11+)
Authentication django-allauth (login, registration, email verification)
Forms django-crispy-forms + crispy-bootstrap5
WSGI Server Gunicorn (production), Django dev server (development)
Static Files WhiteNoise

Database

Environment Database
Development SQLite 3
Production PostgreSQL 15+

Frontend

  • CSS: Bootstrap 5
  • Icons: Bootstrap Icons
  • Templates: Django Template Language
  • JavaScript: Vanilla JS (no framework)
  • PWA: Service worker with offline support
  • Vendor assets: Self-hosted for GDPR compliance — Bootstrap, Bootstrap Icons, Leaflet, Chart.js, chartjs-adapter-date-fns, and vis-network are committed to app/home/static/vendor/ and served locally. No CDN requests are made at build time or runtime.

Infrastructure

  • Docker and Docker Compose
  • Environment variables + Docker Secrets for configuration
  • MkDocs with Material theme for documentation

App Structure

Bifolk is organized into 10 Django apps:

Core Apps

App Purpose Key Models
home Dashboard, landing page, PWA None (views only)
users User profiles, authentication Profile
organizations Multi-tenancy, RBAC Organization, Membership, Invitation, Settings

Business Apps

App Purpose Key Models
hives Core beekeeping domain Hive, BreedingHive, Queen, Inspection, Operations, Harvests, Honey traceability
breeding Queen breeding programs QueenBreeding, ColonySplit
warehouse Inventory and sales InventoryItem, Transaction, Sale, WarehouseLocation

Support Apps

App Purpose Key Models
systemconfig Configurable dropdown choices ChoiceCategory, ConfigurableChoice
notifications In-app notifications Notification
dataexchange Import/export ExportJob, ImportJob
reporting Reports (placeholder) None

Each app follows Django conventions: models.py, views.py, forms.py, urls.py, templates/, admin.py.

Multi-Tenant Architecture

All business data belongs to an Organization. This provides logical data isolation between beekeeping operations.

Organization Context

The OrganizationMiddleware (organizations/middleware.py) adds organization context to every request:

request.current_organization  # Current active organization
request.user_organizations    # All organizations user belongs to

Organization selection priority:

  1. Session variable (user manually switched organizations)
  2. Default organization (user's first organization by join date)
  3. None (user not authenticated or has no organization)

Data Filtering

All querysets in business apps are filtered by organization:

hives = Hive.objects.filter(organization=request.current_organization)

The utility function filter_by_user_organizations() in organizations/utils.py provides centralized filtering.

Organization Switching

Users can belong to multiple organizations and switch between them. The sidebar provides an organization selector. A special "View All" mode shows data from all organizations.

Permission System

Bifolk uses Role-Based Access Control (RBAC) at the organization level.

Role Hierarchy

Owner > Admin > Member > Viewer
Action Owner Admin Member Viewer
View data Yes Yes Yes Yes
Create data Yes Yes Yes No
Edit own data Yes Yes Yes No
Edit all data Yes Yes No No
Delete data Yes Yes No No
Manage members Yes Yes No No
Delete organization Yes No No No

Permissions are enforced at three levels:

  1. Model-level: user_can_view(), user_can_edit(), user_can_delete() methods
  2. View-level: Permission checks in views, mixins
  3. Template-level: Conditional rendering of UI elements

See Permissions System for details.

Configuration System

Bifolk uses a three-tier configuration system:

Docker Secrets (highest priority)
  → Environment Variables
    → Defaults (lowest priority)

Startup Flow

Container starts
  → docker-entrypoint.sh
    → generate_config.py reads secrets, env vars, defaults
      → Writes bifolk.json
        → Django settings.py loads bifolk.json
          → Application starts

See Configuration for the full environment variable reference.

Signal-Driven Automation

Bifolk uses Django signals for event-driven automation:

Event Action Location
User registered Auto-create Profile users/signals.py
User registered Auto-create default Organization organizations/signals.py
Harvest created Auto-create HoneyBatch hives/signals.py
Health status changed Create HealthStatusChange record hives/signals.py
Export/import completed Send notification notifications/signals.py

Request Flow

HTTP Request
  → SecurityMiddleware
  → SessionMiddleware
  → LocaleMiddleware (browser language detection)
  → CommonMiddleware
  → CsrfViewMiddleware
  → AuthenticationMiddleware
  → UserLanguageMiddleware (user profile language)
  → OrganizationMiddleware (organization context)
  → MessageMiddleware
  → URL Routing
  → View (permission checks, org filtering, business logic)
  → Template Rendering
  → HTTP Response

Progressive Web App

Bifolk is installable as a PWA on mobile and desktop:

  • Service worker with network-first and cache-first strategies
  • IndexedDB offline operation queue for form submissions
  • Automatic sync when connection is restored
  • Manifest for installability

Key files: - home/views_pwa.py - Manifest and service worker views - home/static/pwa/ - Service worker scripts

Honey Traceability Chain

A key domain feature is full traceability from hive to jar:

HarvestRecord → HoneyBatch → HoneyBucket → HoneyJar
  (from hive)     (Topf)       (Eimer)      (Glas)

Each level tracks quantity, origin, and processing details.

URL Routing

/                          → Dashboard (home app)
/hives/                    → Hive management
/hives/queens/             → Queen management
/hives/inspections/        → Hive inspections
/hives/operations/         → Beekeeping operations
/hives/harvest/            → Harvest tracking
/hives/batches/            → Honey batches
/breeding/                 → Breeding programs
/warehouse/                → Inventory and sales
/organizations/            → Organization management
/notifications/            → Notification center
/dataexchange/             → Import/export
/system/                   → System configuration
/accounts/                 → Authentication (django-allauth)
/admin/                    → Django admin interface
/manifest.json             → PWA manifest
/service-worker.js         → PWA service worker