Approfondissement technique

Le EOS Core suit une architecture en couches concue pour la modularite, l'extensibilite et des calculs d'incidence environnementale auditables.

Vue d'ensemble du système

Couches architecturales

Couche API

La couche API fournit deux interfaces :

API REST v2 (/v2/* sur le port 8040)

• API REST moderne basée sur FastAPI
• Authentification par jeton JWT avec groupes d'accès
• Prise en charge du calcul par lots
• Journalisation structurée des requêtes
• Arret gracieux avec détection du fichier de drainage

API héritée v1 (/api/* sur le port 8050)

• Points de terminaison retrocompatibles
• Encapsule les fonctionnalités de l'API v2
• Prend en charge les méthodes d'authentification heritees

Couche centrale

CalcGraph - La structure de calcul centrale :

# CalcGraph gere l'ensemble du calcul sous forme de graphe oriente
class CalcGraph:
    root_node_uid: str           # Point d'entree du calcul
    nodes: dict[str, Node]       # Tous les noeuds du graphe
    mutations: list[Mutation]    # Journal des modifications auditable

    def add_graph_observer(observer)  # Declenchement des GFM
    def apply_mutation(mutation)       # Modifications transparentes

Orchestrateur - Coordonne l'exécution des GFM :

class Orchestrator(AbstractGraphObserver):
    async def run():
        # 1. Initialiser les noeuds depuis la racine ou les sous-noeuds lies
        # 2. Creer des workers GFM sur les noeuds initiaux
        # 3. Boucle de planification :
        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)

Fournisseur de services - Conteneur d'injection de dépendances :

class ServiceProvider:
    postgres_db: PostgresDb
    glossary_service: GlossaryService
    matching_service: MatchingService
    node_service: NodeService
    calc_service: CalcService
    gap_filling_module_loader: GapFillingModuleLoader
    # ... services supplementaires

Couche de modules

Les modules suivent le patron Factory/Worker :

Factory (Singleton par service) :

• Initialise une fois au démarrage du service
• Detient les connexions à la base de données et les caches
• Crée des workers pour les noeuds individuels

Worker (Par noeud) :

• should_be_scheduled() - Ce GFM est-il pertinent pour ce noeud ?
• can_run_now() - Les dépendances sont-elles satisfaites ?
• run() - Execute la logique de comblement des lacunes

Couche de données

PostgreSQL avec asyncpg :

• Pool de connexions pour les opérations asynchrones
• Champs JSONB pour le stockage flexible des propriétés de noeuds
• Schéma dans database/postgres/schema.sql

Classés Manager (patron DAO) :

• PostgresGraphMgr - Persistance des noeuds/aretes
• PgTermMgr - Opérations sur le glossaire
• PgMatchingMgr - Données de correspondance des ingrédients
• PostgresAccessMgr - Controle d'accès utilisateurs/groupes

Types de noeuds

EOS utilise un système de types riche pour les noeuds du graphe :

Type de noeud	Objectif
FoodProductFlowNode	Produit alimentaire avec composition
AggregationFoodProductFlowNode	Caches d'agregation quotidienne pour l'optimisation des performances
PracticeFlowNode	Pratiques agricoles ou de transformation
ElementaryResourceEmissionNode	Emissions environnementales
FoodProcessingActivityNode	Operations de transformation
TransportActivityNode	Transport
ModeledActivityNode	Inventaire ACV Brightway
LinkingActivityNode	Lie les noeuds de flux aux noeuds d'activite
SupplySheetActivityNode	Donnees de fiche d'approvisionnement provenant de sources externes
AggregationFoodProcessingActivityNode	Activites de transformation agregees

Système de propriétés

Les noeuds stockent les données via des propriétés typées :

Type de propriete	Description
QuantityProp	Mesures avec unites
LocationProp	Donnees geographiques
GlossaryTermProp	Liens vers la terminologie
EnvironmentalFlowsProp	Resultats d'incidence
NamesProp	Denomination multilingue
GfmStateProp	Etat d'execution du GFM

Flux de données

Multi-location

EOS prend en charge l'isolation multi-locataire :

• Espace de noms - Isolation organisation/ecosysteme
• Groupe d'accès - Équipe/departement au sein de l'espace de noms
• Utilisateur - Individu avec authentification OAuth2/courriel
• Permissions - Controle d'accès par noeud

Architecture de messagerie

RabbitMQ permet le traitement distribue :

• File haute priorité - Requêtes interactives
• File basse priorité - Traitement par lots
• Gestion du prefetch - Planification tenant compte des ressources

Gestion des erreurs

Modèle d'erreur structure pour les erreurs de domaine :

@dataclass
class DataError:
    node_uid: str
    gfm_name: str
    message: str
    classification: ErrorClassification  # missing_matching, missing_lca_inventory, etc.
    log_level: LogLevel  # INFO, WARNING, ERROR

Mutations du graphe

Toutes les modifications du graphe sont transparentes et auditables :

Type de mutation	Objectif
AddNodeMutation	Inserer un nouveau noeud
PropMutation	Mettre à jour une seule propriété
AddEdgeMutation	Créer une relation entre noeuds
RemoveEdgeMutation	Supprimer une relation
DuplicateNodeMutation	Cloner un noeud

Avantages :

• Auditabilite - Journal complet des mutations
• Determinisme - Calculs reproductibles
• Transparence - Revue non technique possible

Architecture de performance

EOS est optimisé pour les calculs d'incidence environnementale en temps réel, visant des temps de réponse inferieurs à 2 secondes pour les applications de restauration interactives.

Optimisations de performance

Optimisation	Incidence
Calculs matriciels	Acceleration de 5s à 1s par calcul (amélioration de 80%)
Traitement concurrent	Operation parallele sur plusieurs pods avec mise en file d'attente intelligente des requêtes
Service GADM	Implémentation Rust atteignant une réduction de memoire de 3x et une amélioration de vitesse de 10x
Mise en cache multi-niveau	Rappels en memoire à chaque niveau ACV au sein de la même instance
Equilibrage de charge	Distribution des requêtes basée sur RabbitMQ entre les pods workers

Évolutivité

Le système utilise Elastic Kubernetes Service (EKS) avec mise à l'échelle automatique :

• Mise à l'échelle dynamique : Jusqu'à 1024 pods selon la charge de travail
• Karpenter : Provisionnement et mise à l'échelle automatiques des noeuds
• Optimisation des ressources : Deployements héritage et core séparés pour une utilisation efficace de la RAM
• Architecture de microservices : Traitement en memoire rationalise pour minimiser la complexité de la messagerie

Stratégie de mise en cache

La mise en cache multi-niveau réduit la charge de calcul :

┌─────────────────────────────────────────────────┐
│  Niveau requete   │ Resultats de calcul caches │
├─────────────────────────────────────────────────┤
│  Niveau GFM       │ Caches Factory (emissions, │
│                   │ activites, termes glossaire)│
├─────────────────────────────────────────────────┤
│  Niveau base      │ Pool de connexions,         │
│  de donnees       │ cache des resultats requete │
└─────────────────────────────────────────────────┘

• Invalidation intelligente du cache basée sur les changements de données
• Invalidation selective pour minimiser le recalcul
• Mise en cache distribuee pour les deployements cloud

Architecture de sécurité

EOS implémente une approche de sécurité multicouche :

Authentification

Types de jetons :

• Jetons personnel - Accès administratif avec privileges eleves
• Jetons espace de noms - Accès au niveau de l'organisation
• Jetons utilisateur - Accès utilisateur individuel avec périodes de validite limitées

Sécurité réseau

• Sous-réseaux prives : Les noeuds workers operent dans des sous-réseaux prives
• Hote bastion : Accès SSH au VPC via bastion
• Groupes d'accès : Roles IAM pour un controle d'accès granulaire

Surveillance

• CloudWatch : Surveillance et journalisation continues du système
• Journalisation structurée : Suivi des requêtes et métriques de performance
• Vérification de l'état : Surveillance automatisée de l'état du système

Intégration Brightway

EOS exploite Brightway, un cadre ACV open source :

Pourquoi Brightway ?

Capacité	Avantage
Flexibilite	Calculs ACV personnalisés pour divers produits alimentaires
Intégration de bases de données	Intégration facile avec ecoinvent, Agribalyse via routines d'importation
Analyse d'incertitude	Méthodes robustes pour l'analyse de sensibilité
Évolutivité	Gère des calculs complexes pour des évaluations détaillées
Communaute	Open source avec mises à jour méthodologiques continues

Transformation matricielle

La transformation matricielle est le coeur computationnel des calculs ACV :

1. Graphe vers matrice : Convertir les réseaux de chaîne d'approvisionnement en matrices mathematiques
2. Modélisation entrée-sortie : Representer les relations entre processus
3. Algebre matricielle : Calculer les incidences environnementales cumulées
4. Évaluation de l'incidence : Appliquer les méthodes EICV (par exemple, GIEC GWP100)

# Calcul matriciel conceptuel
# A = matrice technologique (entrees/sorties de processus)
# B = matrice d'intervention (echanges environnementaux)
# f = vecteur de demande finale
# s = vecteur de mise a l'echelle = A^(-1) * f
# g = resultat de l'inventaire = B * s

Infrastructure

Orchestration de conteneurs

• Kubernetes : Orchestration et déploiement de conteneurs Docker
• Karpenter : Provisionnement automatique des noeuds selon la demande
• Charts Helm : Configurations de déploiement standardisées

Stockage de données

Composant	Technologie	Objectif
Base de données principale	PostgreSQL	Données structurées (produits, recettes, utilisateurs)
Pilote asynchrone	asyncpg	Accès asynchrone haute performance à la base de données
File de messages	RabbitMQ	Distribution des requêtes et equilibrage de charge

Système d'identifiant externe (Xid)

Le système Xid assure l'integrite des données avec les systèmes externes :

• Identifiants uniques : Chaque entite à un identifiant externe à portée d'espace de noms
• Correspondance UUID : Relation 1-1 entre Xid et UUID interne
• Référence croisée : Recherche facile entre les espaces de noms
• Versionnage : Suivi des changements dans le temps

Journal des mutations (Retour arrière/Rejouer)

Toutes les modifications du graphe sont journalisees pour l'auditabilite et le débogage :

# Chaque mutation est enregistree
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)

Capacités :

• Retour arrière : Inverser les mutations pour restaurer l'état precedent
• Rejouer : Reconstruire l'état du système ou appliquer des changements a différents environnements
• Débogage : Tracer les étapes de calcul pour l'investigation des erreurs
• Transparence : Piste d'audit complete pour tous les calculs

Prochaines étapes

• Fonctionnement - Flux de calcul étape par étape
• Gap Filling Modules - Détails du système de modules
• SDK GFM (bientot disponible) - Construire des modules personnalisés