Architekturübersicht¶

Systemarchitektur und Designmuster der Bifolk-Imkereiverwaltungsanwendung.

Zielgruppe: Softwareentwickler, fortgeschrittene Administratoren

Technologie-Stack¶

Backend¶

Komponente	Technologie
Framework	Django 6.x (Python 3.11+)
Authentifizierung	django-allauth (Login, Registrierung, E-Mail-Verifizierung)
Formulare	django-crispy-forms + crispy-bootstrap5
WSGI-Server	Gunicorn (Produktion), Django-Entwicklungsserver (Entwicklung)
Statische Dateien	WhiteNoise

Datenbank¶

Umgebung	Datenbank
Entwicklung	SQLite 3
Produktion	PostgreSQL 15+

Frontend¶

CSS: Bootstrap 5
Icons: Bootstrap Icons
Templates: Django Template Language
JavaScript: Vanilla JS (kein Framework)
PWA: Service Worker mit Offline-Unterstützung
Vendor-Assets: Aus DSGVO-Gründen lokal bereitgestellt — Bootstrap, Bootstrap Icons, Leaflet, Chart.js, chartjs-adapter-date-fns und vis-network sind unter app/home/static/vendor/ im Repository gespeichert und werden lokal ausgeliefert. Es werden weder zur Build-Zeit noch zur Laufzeit CDN-Anfragen gestellt.

Infrastruktur¶

Docker und Docker Compose
Umgebungsvariablen + Docker Secrets für Konfiguration
MkDocs mit Material-Theme für Dokumentation

App-Struktur¶

Bifolk ist in 10 Django-Apps organisiert:

Kern-Apps¶

App	Zweck	Wichtige Modelle
home	Dashboard, Startseite, PWA	Keine (nur Views)
users	Benutzerprofile, Authentifizierung	Profile
organizations	Mandantenfähigkeit, RBAC	Organization, Membership, Invitation, Settings

Geschäfts-Apps¶

App	Zweck	Wichtige Modelle
hives	Kerndomäne Imkerei	Hive, BreedingHive, Queen, Inspection, Operations, Harvests, Honig-Rückverfolgbarkeit
breeding	Königinnenzuchtprogramme	QueenBreeding, ColonySplit
warehouse	Inventar und Verkauf	InventoryItem, Transaction, Sale, WarehouseLocation

Unterstützende Apps¶

App	Zweck	Wichtige Modelle
systemconfig	Konfigurierbare Dropdown-Auswahloptionen	ChoiceCategory, ConfigurableChoice
notifications	In-App-Benachrichtigungen	Notification
dataexchange	Import/Export	ExportJob, ImportJob
reporting	Berichte (Platzhalter)	Keine

Jede App folgt Django-Konventionen: models.py, views.py, forms.py, urls.py, templates/, admin.py.

Mandantenfähige Architektur¶

Alle Geschäftsdaten gehören zu einer Organisation. Dies bietet logische Datenisolierung zwischen Imkereibetrieben.

Organisationskontext¶

Die OrganizationMiddleware (organizations/middleware.py) fügt jeder Anfrage den Organisationskontext hinzu:

request.current_organization  # Aktuelle aktive Organisation
request.user_organizations    # Alle Organisationen, denen der Benutzer angehört

Priorität der Organisationsauswahl:

Session-Variable (Benutzer hat manuell die Organisation gewechselt)
Standard-Organisation (erste Organisation des Benutzers nach Beitrittsdatum)
None (Benutzer nicht authentifiziert oder hat keine Organisation)

Datenfilterung¶

Alle Abfragen in Geschäfts-Apps werden nach Organisation gefiltert:

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

Die Hilfsfunktion filter_by_user_organizations() in organizations/utils.py bietet zentralisierte Filterung.

Organisationswechsel¶

Benutzer können mehreren Organisationen angehören und zwischen ihnen wechseln. Die Seitenleiste bietet einen Organisationswähler. Ein spezieller "Alle anzeigen"-Modus zeigt Daten aus allen Organisationen.

Berechtigungssystem¶

Bifolk verwendet Rollenbasierte Zugriffskontrolle (RBAC) auf Organisationsebene.

Rollenhierarchie¶

Besitzer > Admin > Mitglied > Betrachter

Aktion	Besitzer	Admin	Mitglied	Betrachter
Daten ansehen	Ja	Ja	Ja	Ja
Daten erstellen	Ja	Ja	Ja	Nein
Eigene Daten bearbeiten	Ja	Ja	Ja	Nein
Alle Daten bearbeiten	Ja	Ja	Nein	Nein
Daten löschen	Ja	Ja	Nein	Nein
Mitglieder verwalten	Ja	Ja	Nein	Nein
Organisation löschen	Ja	Nein	Nein	Nein

Berechtigungen werden auf drei Ebenen durchgesetzt:

Modellebene: user_can_view(), user_can_edit(), user_can_delete() Methoden
View-Ebene: Berechtigungsprüfungen in Views, Mixins
Template-Ebene: Bedingte Darstellung von UI-Elementen

Siehe Berechtigungssystem für Details.

Konfigurationssystem¶

Bifolk verwendet ein dreistufiges Konfigurationssystem:

Docker Secrets (höchste Priorität)
  → Umgebungsvariablen
    → Standardwerte (niedrigste Priorität)

Startablauf¶

Container startet
  → docker-entrypoint.sh
    → generate_config.py liest Secrets, Umgebungsvariablen, Standardwerte
      → Schreibt bifolk.json
        → Django settings.py lädt bifolk.json
          → Anwendung startet

Siehe Konfiguration für die vollständige Umgebungsvariablen-Referenz.

Signalgesteuerte Automatisierung¶

Bifolk verwendet Django-Signale für ereignisgesteuerte Automatisierung:

Ereignis	Aktion	Ort
Benutzer registriert	Profil automatisch erstellen	`users/signals.py`
Benutzer registriert	Standard-Organisation automatisch erstellen	`organizations/signals.py`
Ernte erstellt	HoneyBatch automatisch erstellen	`hives/signals.py`
Gesundheitsstatus geändert	HealthStatusChange-Eintrag erstellen	`hives/signals.py`
Export/Import abgeschlossen	Benachrichtigung senden	`notifications/signals.py`

Anfrage-Ablauf¶

HTTP-Anfrage
  → SecurityMiddleware
  → SessionMiddleware
  → LocaleMiddleware (Browser-Spracherkennung)
  → CommonMiddleware
  → CsrfViewMiddleware
  → AuthenticationMiddleware
  → UserLanguageMiddleware (Benutzerprofil-Sprache)
  → OrganizationMiddleware (Organisationskontext)
  → MessageMiddleware
  → URL-Routing
  → View (Berechtigungsprüfungen, Org-Filterung, Geschäftslogik)
  → Template-Rendering
  → HTTP-Antwort

Progressive Web App¶

Bifolk ist als PWA auf Mobilgeräten und Desktop installierbar:

Service Worker mit Network-First- und Cache-First-Strategien
IndexedDB Offline-Warteschlange für Formularübermittlungen
Automatische Synchronisation bei Wiederherstellung der Verbindung
Manifest für Installierbarkeit

Wichtige Dateien: - home/views_pwa.py - Manifest- und Service-Worker-Views - home/static/pwa/ - Service-Worker-Skripte

Honig-Rückverfolgbarkeitskette¶

Ein wichtiges Domänen-Feature ist die vollständige Rückverfolgbarkeit vom Bienenstock bis zum Glas:

HarvestRecord → HoneyBatch → HoneyBucket → HoneyJar
  (vom Stock)     (Topf)       (Eimer)      (Glas)

Jede Ebene verfolgt Menge, Herkunft und Verarbeitungsdetails.

URL-Routing¶

/                          → 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