Skip to content

Technical Documentation

Technical documentation for developers and advanced administrators working with the Bifolk codebase.

Target Audience: Software developers, DevOps engineers, advanced administrators

Architecture & Design

App Reference

Detailed technical documentation for each Django app:

App Purpose Key Models
Home Dashboard, PWA, shared mixins None (views only)
Users User profiles, authentication Profile
Organizations Multi-tenancy, RBAC Organization, Membership, Invitation, Settings
Hives Core beekeeping domain Hive, Queen, Inspection, Harvest, Operations
Breeding Queen breeding programs QueenBreeding, ColonySplit
Warehouse Inventory and sales InventoryItem, Transaction, Sale
SystemConfig Configurable choices ChoiceCategory, ConfigurableChoice
Notifications In-app notifications Notification
DataExchange Import/export ExportJob, ImportJob

Technology Stack

Core

  • Framework: Django 6.x
  • Language: Python 3.11+
  • Database: PostgreSQL 15+ (production), SQLite 3 (development)
  • Frontend: Bootstrap 5, Crispy Forms, Bootstrap Icons
  • Server: Gunicorn (production), Django dev server (development)
  • Containerization: Docker and Docker Compose

Key Dependencies

  • django >= 6.0, < 7.0 - Web framework
  • django-allauth - Authentication (login, registration, email verification)
  • django-crispy-forms + crispy-bootstrap5 - Form rendering
  • Pillow - Image processing (profile photos, hive photos)
  • psycopg2-binary - PostgreSQL adapter
  • gunicorn - WSGI HTTP server
  • whitenoise - Static file serving

Architecture Principles

Multi-Tenant Design

  • All data models have an organization foreign key
  • Users can belong to multiple organizations
  • Organization-based query filtering via filter_by_user_organizations()
  • Middleware manages current organization context (request.current_organization)

Permission System

  • 4-role RBAC: Owner > Admin > Member > Viewer
  • Centralized permission functions in organizations/utils.py
  • Model-level methods: user_can_view(), user_can_edit(), user_can_delete()
  • View mixins enforce permissions automatically
  • Template tags for conditional rendering

Signal-Driven Automation

  • User registration triggers auto-creation of Profile and default Organization
  • Harvest creation can auto-create HoneyBatch
  • Health status changes create HealthStatusChange records
  • Export/import completion triggers notifications

Progressive Web App

  • Service worker with network-first and cache-first strategies
  • IndexedDB-based offline operation queue
  • Automatic sync when connection is restored
  • Installable on mobile and desktop

Development Setup

Prerequisites

  • Docker Engine 20.10+
  • Docker Compose 2.0+
  • Git
  • Python 3.11+ (for local development)

Quick Start

# Clone repository
git clone <repo-url>
cd bifolk

# Set up development environment
cd docker/compose-developement
cp .env.example .env
docker compose up

# Create superuser
docker compose exec bifolk-app python manage.py createsuperuser

# Load sample data (optional)
docker compose exec bifolk-app python manage.py load_sample_data

Access at http://localhost:8000

Local Development (without Docker)

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run migrations
cd app
python manage.py migrate

# Create superuser
python manage.py createsuperuser

# Start development server
python manage.py runserver

Running Tests

# All tests
cd app
DJANGO_SETTINGS_MODULE=bifolk.settings_test python manage.py test

# Single app
DJANGO_SETTINGS_MODULE=bifolk.settings_test python manage.py test hives

# With parallel execution
DJANGO_SETTINGS_MODULE=bifolk.settings_test python manage.py test --parallel=4

Type Checking

mypy app/ --exclude migrations --ignore-missing-imports

Configuration System

Bifolk uses a three-tier configuration system:

  1. Docker Secrets (highest priority) - Sensitive data in /run/secrets/
  2. Environment Variables - Non-sensitive configuration in .env
  3. Defaults (lowest priority) - Safe defaults in generate_config.py
Container Startup → docker-entrypoint.sh → generate_config.py
  reads: Secrets → Environment → Defaults
  generates: bifolk.json → Django settings.py

See Configuration for details.

URL Routing Overview

/                          → 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 (charges)
/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
  • User Guide - For beekeepers and end users
  • Admin Guide - For administrators and deployment
  • Internal AI Reference: docs/claude/ - Detailed model and app reference