Zum Inhalt

Technische Dokumentation

Technische Dokumentation für Entwickler und fortgeschrittene Administratoren, die mit der Bifolk-Codebasis arbeiten.

Zielgruppe: Softwareentwickler, DevOps-Ingenieure, fortgeschrittene Administratoren

Architektur & Design

App-Referenz

Detaillierte technische Dokumentation für jede Django-App:

App Zweck Wichtige Modelle
Home Dashboard, PWA, gemeinsame Mixins Keine (nur Views)
Users Benutzerprofile, Authentifizierung Profile
Organizations Mandantenfähigkeit, RBAC Organization, Membership, Invitation, Settings
Hives Kerndomäne Imkerei Hive, Queen, Inspection, Harvest, Operations
Breeding Königinnenzuchtprogramme QueenBreeding, ColonySplit
Warehouse Inventar und Verkauf InventoryItem, Transaction, Sale
SystemConfig Konfigurierbare Auswahloptionen ChoiceCategory, ConfigurableChoice
Notifications In-App-Benachrichtigungen Notification
DataExchange Import/Export ExportJob, ImportJob

Technologie-Stack

Kern

  • Framework: Django 6.x
  • Sprache: Python 3.11+
  • Datenbank: PostgreSQL 15+ (Produktion), SQLite 3 (Entwicklung)
  • Frontend: Bootstrap 5, Crispy Forms, Bootstrap Icons
  • Server: Gunicorn (Produktion), Django-Entwicklungsserver (Entwicklung)
  • Containerisierung: Docker und Docker Compose

Wichtige Abhängigkeiten

  • django >= 6.0, < 7.0 - Web-Framework
  • django-allauth - Authentifizierung (Login, Registrierung, E-Mail-Verifizierung)
  • django-crispy-forms + crispy-bootstrap5 - Formular-Rendering
  • Pillow - Bildverarbeitung (Profilfotos, Bienenstockfotos)
  • psycopg2-binary - PostgreSQL-Adapter
  • gunicorn - WSGI HTTP-Server
  • whitenoise - Statische Dateibereitstellung

Architekturprinzipien

Mandantenfähiges Design

  • Alle Datenmodelle haben einen organization-Fremdschlüssel
  • Benutzer können mehreren Organisationen angehören
  • Organisationsbasierte Abfragefilterung über filter_by_user_organizations()
  • Middleware verwaltet den aktuellen Organisationskontext (request.current_organization)

Berechtigungssystem

  • 4-Rollen RBAC: Besitzer > Admin > Mitglied > Betrachter
  • Zentralisierte Berechtigungsfunktionen in organizations/utils.py
  • Methoden auf Modellebene: user_can_view(), user_can_edit(), user_can_delete()
  • View-Mixins erzwingen Berechtigungen automatisch
  • Template-Tags für bedingtes Rendering

Signalgesteuerte Automatisierung

  • Benutzerregistrierung löst automatische Erstellung von Profil und Standard-Organisation aus
  • Ernteerstellung kann automatisch HoneyBatch erstellen
  • Gesundheitsstatusänderungen erstellen HealthStatusChange-Einträge
  • Export-/Import-Abschluss löst Benachrichtigungen aus

Progressive Web App

  • Service Worker mit Network-First- und Cache-First-Strategien
  • IndexedDB-basierte Offline-Warteschlange
  • Automatische Synchronisation bei Wiederherstellung der Verbindung
  • Installierbar auf Mobilgeräten und Desktop

Entwicklungsumgebung

Voraussetzungen

  • Docker Engine 20.10+
  • Docker Compose 2.0+
  • Git
  • Python 3.11+ (für lokale Entwicklung)

Schnellstart

# Repository klonen
git clone <repo-url>
cd bifolk

# Entwicklungsumgebung einrichten
cd docker/compose-developement
cp .env.example .env
docker compose up

# Superuser erstellen
docker compose exec bifolk-app python manage.py createsuperuser

# Beispieldaten laden (optional)
docker compose exec bifolk-app python manage.py load_sample_data

Zugriff unter http://localhost:8000

Lokale Entwicklung (ohne Docker)

# Virtuelle Umgebung erstellen
python -m venv venv
source venv/bin/activate

# Abhängigkeiten installieren
pip install -r requirements.txt

# Migrationen ausführen
cd app
python manage.py migrate

# Superuser erstellen
python manage.py createsuperuser

# Entwicklungsserver starten
python manage.py runserver

Tests ausführen

# Alle Tests
cd app
DJANGO_SETTINGS_MODULE=bifolk.settings_test python manage.py test

# Einzelne App
DJANGO_SETTINGS_MODULE=bifolk.settings_test python manage.py test hives

# Mit paralleler Ausführung
DJANGO_SETTINGS_MODULE=bifolk.settings_test python manage.py test --parallel=4

Typprüfung

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

Konfigurationssystem

Bifolk verwendet ein dreistufiges Konfigurationssystem:

  1. Docker Secrets (höchste Priorität) - Sensible Daten in /run/secrets/
  2. Umgebungsvariablen - Nicht-sensible Konfiguration in .env
  3. Standardwerte (niedrigste Priorität) - Sichere Standardwerte in generate_config.py
Container-Start → docker-entrypoint.sh → generate_config.py
  liest: Secrets → Umgebungsvariablen → Standardwerte
  generiert: bifolk.json → Django settings.py

Siehe Konfiguration für Details.

URL-Routing-Übersicht

/                          → Dashboard (Home-App)
/hives/                    → Bienenstockverwaltung
/hives/queens/             → Königinnenverwaltung
/hives/inspections/        → Bienenstockkontrollen
/hives/operations/         → Imkereiarbeiten
/hives/harvest/            → Ernteverfolgung
/hives/batches/            → Honigchargen
/breeding/                 → Zuchtprogramme
/warehouse/                → Inventar und Verkauf
/organizations/            → Organisationsverwaltung
/notifications/            → Benachrichtigungszentrale
/dataexchange/             → Import/Export
/system/                   → Systemkonfiguration
/accounts/                 → Authentifizierung (django-allauth)
/admin/                    → Django-Admin-Oberfläche
/manifest.json             → PWA-Manifest
/service-worker.js         → PWA-Service-Worker

Verwandte Dokumentation