Technische Vertiefung
EOS Core folgt einer geschichteten Architektur, die auf Modularität, Erweiterbarkeit und nachvollziehbare Umweltauswirkungsberechnungen ausgelegt ist.
Systemüberblick
Architekturschichten
API-Schicht
Die API-Schicht bietet zwei Schnittstellen:
REST API v2 (/v2/* auf Port 8040)
- FastAPI-basierte moderne REST-API
- JWT-Token-Authentifizierung mit Zugriffsgruppen
- Batch-Berechnungsunterstützung
- Strukturierte Anfragenprotokollierung
- Graceful Shutdown mit Drain-File-Erkennung
Legacy API v1 (/api/* auf Port 8050)
- Abwärtskompatible Endpunkte
- Umhüllt v2-API-Funktionalität
- Unterstützt ältere Authentifizierungsmethoden
Core-Schicht
CalcGraph - Die zentrale Berechnungsstruktur:
# CalcGraph verwaltet die gesamte Berechnung als gerichteten Graphen
class CalcGraph:
root_node_uid: str # Einstiegspunkt für Berechnung
nodes: dict[str, Node] # Alle Knoten im Graphen
mutations: list[Mutation] # Nachvollziehbares Änderungsprotokoll
def add_graph_observer(observer) # GFM-Auslösung
def apply_mutation(mutation) # Transparente Änderungen
Orchestrator - Koordiniert die GFM-Ausführung:
class Orchestrator(AbstractGraphObserver):
async def run():
# 1. Knoten vom Root oder verknüpften Unterknoten initialisieren
# 2. GFM-Worker auf initialen Knoten starten
# 3. Scheduler-Schleife:
while gfms_pending:
for gfm in scheduled_gfms:
if gfm.should_be_scheduled():
status = gfm.can_run_now()
if status == ready:
await gfm.run(calc_graph)
elif status == reschedule:
reschedule(gfm)
Service Provider - Dependency Injection Container:
class ServiceProvider:
postgres_db: PostgresDb
glossary_service: GlossaryService
matching_service: MatchingService
node_service: NodeService
calc_service: CalcService
gap_filling_module_loader: GapFillingModuleLoader
# ... weitere Dienste
Modulschicht
Module folgen dem Factory/Worker-Muster:
Factory (Singleton pro Service):
- Einmal beim Service-Start initialisiert
- Hält Datenbankverbindungen und Caches
- Erzeugt Worker für einzelne Knoten
Worker (Pro Knoten):
should_be_scheduled()- Ist dieses GFM für diesen Knoten relevant?can_run_now()- Sind Abhängigkeiten erfüllt?run()- Führt die Gap-Filling-Logik aus
Datenschicht
PostgreSQL mit asyncpg:
- Connection Pooling für asynchrone Operationen
- JSONB-Felder für flexible Knoteneigenschaftsspeicherung
- Schema in
database/postgres/schema.sql
Manager-Klassen (DAO-Muster):
PostgresGraphMgr- Knoten-/KantenpersistenzPgTermMgr- Glossar-OperationenPgMatchingMgr- Zutaten-Matching-DatenPostgresAccessMgr- Benutzer-/Gruppenzugriffskontrolle
Knotentypen
EOS verwendet ein reichhaltiges Typsystem für Graphknoten:
| Knotentyp | Zweck |
|---|---|
FoodProductFlowNode | Lebensmittelprodukt mit Zusammensetzung |
AggregationFoodProductFlowNode | Tägliche Aggregations-Caches zur Leistungsoptimierung |
PracticeFlowNode | Landwirtschaftliche oder Verarbeitungspraktiken |
ElementaryResourceEmissionNode | Umweltemissionen |
FoodProcessingActivityNode | Verarbeitungsoperationen |
TransportActivityNode | Transport |
ModeledActivityNode | Brightway LCA-Inventar |
LinkingActivityNode | Verbindet Flussknoten mit Aktivitätsknoten |
SupplySheetActivityNode | Lieferdaten aus externen Quellen |
AggregationFoodProcessingActivityNode | Aggregierte Verarbeitungsaktivitäten |
Eigenschaftssystem
Knoten speichern Daten durch typisierte Eigenschaften:
| Eigenschaftstyp | Beschreibung |
|---|---|
QuantityProp | Messungen mit Einheiten |
LocationProp | Geografische Daten |
GlossaryTermProp | Verknüpfungen zur Terminologie |
EnvironmentalFlowsProp | Auswirkungsergebnisse |
NamesProp | Mehrsprachige Benennung |
GfmStateProp | GFM-Ausführungsstatus |
Datenfluss
Mandantenfähigkeit
EOS unterstützt mandantenisolierte Umgebungen:
- Namespace - Organisations-/Ökosystem-Isolation
- Zugriffsgruppe - Team/Abteilung innerhalb des Namespace
- Benutzer - Einzelperson mit OAuth2/E-Mail-Authentifizierung
- Berechtigungen - Knotenbasierte Zugriffskontrolle
Messaging-Architektur
RabbitMQ ermöglicht verteilte Verarbeitung:
- Hochprioritäts-Queue - Interaktive Anfragen
- Niedrigprioritäts-Queue - Batch-Verarbeitung
- Prefetch-Verwaltung - Ressourcenbewusste Planung
Fehlerbehandlung
Strukturiertes Fehlermodell für Domänenfehler:
@dataclass
class DataError:
node_uid: str
gfm_name: str
message: str
classification: ErrorClassification # missing_matching, missing_lca_inventory usw.
log_level: LogLevel # INFO, WARNING, ERROR
Graph-Mutationen
Alle Graphänderungen sind transparent und nachvollziehbar:
| Mutationstyp | Zweck |
|---|---|
AddNodeMutation | Neuen Knoten einfügen |
PropMutation | Einzelne Eigenschaft aktualisieren |
AddEdgeMutation | Knotenbeziehung erstellen |
RemoveEdgeMutation | Beziehung löschen |
DuplicateNodeMutation | Knoten klonen |
Vorteile:
- Nachvollziehbarkeit - Vollständiges Mutationsprotokoll
- Determinismus - Reproduzierbare Berechnungen
- Transparenz - Nicht-technische Überprüfung möglich
Leistungsarchitektur
EOS ist für Echtzeit-Umweltauswirkungsberechnungen optimiert, mit dem Ziel von Antwortzeiten unter 2 Sekunden für interaktive Restaurantanwendungen.
Leistungsoptimierungen
| Optimierung | Auswirkung |
|---|---|
| Matrix-Berechnungen | Beschleunigt von 5s auf 1s pro Berechnung (80% Verbesserung) |
| Parallele Verarbeitung | Parallelbetrieb über mehrere Pods mit intelligenter Anfragen-Warteschlange |
| GADM-Service | Rust-Implementierung mit 3x Speicherreduktion und 10x Geschwindigkeitssteigerung |
| Mehrstufiges Caching | In-Memory-Callbacks auf jeder LCA-Ebene innerhalb derselben Instanz |
| Lastverteilung | RabbitMQ-basierte Anfrageverteilung über Worker-Pods |
Skalierbarkeit
Das System verwendet Elastic Kubernetes Service (EKS) mit automatischer Skalierung:
- Dynamische Skalierung: Bis zu 1024 Pods basierend auf Arbeitslast
- Karpenter: Automatische Knotenbereitstellung und -skalierung
- Ressourcenoptimierung: Getrennte Legacy- und Core-Bereitstellungen für effiziente RAM-Nutzung
- Microservice-Architektur: Optimierte In-Memory-Verarbeitung zur Minimierung der Messaging-Komplexität
Caching-Strategie
Mehrstufiges Caching reduziert die Berechnungslast:
┌─────────────────────────────────────────────────┐
│ Anfrageebene │ Gecachte Berechnungsergebnisse │
├─────────────────────────────────────────────────┤
│ GFM-Ebene │ Factory-Caches (Emissionen, │
│ │ Aktivitäten, Glossarbegriffe) │
├─────────────────────────────────────────────────┤
│ Datenbankebene │ Connection Pooling, │
│ │ Abfrageergebnis-Caching │
└─────────────────────────────────────────────────┘
- Intelligente Cache-Invalidierung basierend auf Datenänderungen
- Selektive Invalidierung zur Minimierung von Neuberechnungen
- Verteiltes Caching für Cloud-Bereitstellungen
Sicherheitsarchitektur
EOS implementiert einen mehrschichtigen Sicherheitsansatz:
Authentifizierung
Token-Typen:
- Staff-Tokens - Administrativer Zugriff mit erhöhten Rechten
- Namespace-Tokens - Zugriff auf Organisationsebene
- Benutzer-Tokens - Individueller Benutzerzugriff mit begrenzter Gültigkeitsdauer
Netzwerksicherheit
- Private Subnetze: Worker-Knoten operieren in privaten Subnetzen
- Bastion Host: SSH-Zugang zum VPC über Bastion
- Zugriffsgruppen: IAM-Rollen für feingranulare Zugriffskontrolle
Monitoring
- CloudWatch: Kontinuierliche Systemüberwachung und Protokollierung
- Strukturierte Protokollierung: Anfragenverfolgung und Leistungsmetriken
- Health Checks: Automatisierte Systemzustandsüberwachung
Brightway-Integration
EOS nutzt Brightway, ein Open-Source-LCA-Framework:
Warum Brightway?
| Fähigkeit | Vorteil |
|---|---|
| Flexibilität | Maßgeschneiderte LCA-Berechnungen für diverse Lebensmittelprodukte |
| Datenbankintegration | Einfache Integration mit ecoinvent, Agribalyse über Import-Routinen |
| Unsicherheitsanalyse | Robuste Methoden für Sensitivitätsanalysen |
| Skalierbarkeit | Bewältigt komplexe Berechnungen für detaillierte Bewertungen |
| Community | Open-Source mit kontinuierlichen Methodik-Updates |
Matrix-Transformation
Die Matrix-Transformation ist der Berechnungskern für LCA-Berechnungen:
- Graph zu Matrix: Lieferkettennetzwerke in mathematische Matrizen konvertieren
- Input-Output-Modellierung: Beziehungen zwischen Prozessen darstellen
- Matrixalgebra: Kumulative Umweltauswirkungen berechnen
- Auswirkungsbewertung: LCIA-Methoden anwenden (z.B. IPCC GWP100)
# Konzeptionelle Matrixberechnung
# A = Technologiematrix (Prozessin-/outputs)
# B = Interventionsmatrix (Umweltaustausche)
# f = Endnachfragevektor
# s = Skalierungsvektor = A^(-1) * f
# g = Inventarergebnis = B * s
Infrastruktur
Container-Orchestrierung
- Kubernetes: Docker-Container-Orchestrierung und -Bereitstellung
- Karpenter: Automatische Knotenbereitstellung basierend auf Bedarf
- Helm Charts: Standardisierte Bereitstellungskonfigurationen
Datenspeicherung
| Komponente | Technologie | Zweck |
|---|---|---|
| Primärdatenbank | PostgreSQL | Strukturierte Daten (Produkte, Rezepte, Benutzer) |
| Async-Treiber | asyncpg | Hochleistungs-Async-Datenbankzugriff |
| Message Queue | RabbitMQ | Anfrageverteilung und Lastausgleich |
Externes ID-System (Xid)
Das Xid-System gewährleistet Datenintegrität mit externen Systemen:
- Eindeutige Identifier: Jede Entität hat eine namespace-bezogene externe ID
- UUID-Mapping: 1-1-Beziehung zwischen Xid und interner UUID
- Querverweise: Einfache Suche über Namespaces hinweg
- Versionierung: Änderungsverfolgung über die Zeit
Mutationsprotokoll (Rewind/Replay)
Alle Graphänderungen werden für Nachvollziehbarkeit und Debugging protokolliert:
# Jede Mutation wird aufgezeichnet
mutation = PropMutation(
node_uid="abc123",
property_type="OriginProp",
old_value=None,
new_value=origin_data,
gfm_name="origin_gfm",
timestamp=datetime.now()
)
calc_graph.apply_mutation(mutation)
Fähigkeiten:
- Rewind: Mutationen rückgängig machen, um vorherigen Zustand wiederherzustellen
- Replay: Systemzustand rekonstruieren oder Änderungen auf andere Umgebungen anwenden
- Debugging: Berechnungsschritte zur Fehleruntersuchung nachverfolgen
- Transparenz: Vollständiger Audit-Trail für alle Berechnungen
Nächste Schritte
- Funktionsweise - Schrittweiser Berechnungsablauf
- Gap Filling Modules - Details zum Modulsystem
- GFM SDK (in Kürze) - Eigene Module erstellen