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 systeme

Couches architecturales

Couche API

La couche API fournit deux interfaces :

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

• API REST moderne basee sur FastAPI
• Authentification par jeton JWT avec groupes d'acces
• Prise en charge du calcul par lots
• Journalisation structuree des requetes
• Arret gracieux avec detection du fichier de drainage

API heritee v1 (/api/* sur le port 8050)

• Points de terminaison retrocompatibles
• Encapsule les fonctionnalites de l'API v2
• Prend en charge les methodes 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'execution 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 dependances :

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 demarrage du service
• Detient les connexions a la base de donnees et les caches
• Cree des workers pour les noeuds individuels

Worker (Par noeud) :

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

Couche de donnees

PostgreSQL avec asyncpg :

• Pool de connexions pour les operations asynchrones
• Champs JSONB pour le stockage flexible des proprietes de noeuds
• Schema dans database/postgres/schema.sql

Classes Manager (patron DAO) :

• PostgresGraphMgr - Persistance des noeuds/aretes
• PgTermMgr - Operations sur le glossaire
• PgMatchingMgr - Donnees de correspondance des ingredients
• PostgresAccessMgr - Controle d'acces utilisateurs/groupes

Types de noeuds

EOS utilise un systeme 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

Systeme de proprietes

Les noeuds stockent les donnees via des proprietes typees :

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 donnees

Multi-location

EOS prend en charge l'isolation multi-locataire :

• Espace de noms - Isolation organisation/ecosysteme
• Groupe d'acces - Equipe/departement au sein de l'espace de noms
• Utilisateur - Individu avec authentification OAuth2/courriel
• Permissions - Controle d'acces par noeud

Architecture de messagerie

RabbitMQ permet le traitement distribue :

• File haute priorite - Requetes interactives
• File basse priorite - Traitement par lots
• Gestion du prefetch - Planification tenant compte des ressources

Gestion des erreurs

Modele 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 a jour une seule propriete
AddEdgeMutation	Creer 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 optimise pour les calculs d'incidence environnementale en temps reel, visant des temps de reponse inferieurs a 2 secondes pour les applications de restauration interactives.

Optimisations de performance

Optimisation	Incidence
Calculs matriciels	Acceleration de 5s a 1s par calcul (amelioration de 80%)
Traitement concurrent	Operation parallele sur plusieurs pods avec mise en file d'attente intelligente des requetes
Service GADM	Implementation Rust atteignant une reduction de memoire de 3x et une amelioration de vitesse de 10x
Mise en cache multi-niveau	Rappels en memoire a chaque niveau ACV au sein de la meme instance
Equilibrage de charge	Distribution des requetes basee sur RabbitMQ entre les pods workers

Evolutivite

Le systeme utilise Elastic Kubernetes Service (EKS) avec mise a l'echelle automatique :

• Mise a l'echelle dynamique : Jusqu'a 1024 pods selon la charge de travail
• Karpenter : Provisionnement et mise a l'echelle automatiques des noeuds
• Optimisation des ressources : Deployements heritage et core separes pour une utilisation efficace de la RAM
• Architecture de microservices : Traitement en memoire rationalise pour minimiser la complexite de la messagerie

Strategie de mise en cache

La mise en cache multi-niveau reduit 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 basee sur les changements de donnees
• Invalidation selective pour minimiser le recalcul
• Mise en cache distribuee pour les deployements cloud

Architecture de securite

EOS implemente une approche de securite multicouche :

Authentification

Types de jetons :

• Jetons personnel - Acces administratif avec privileges eleves
• Jetons espace de noms - Acces au niveau de l'organisation
• Jetons utilisateur - Acces utilisateur individuel avec periodes de validite limitees

Securite reseau

• Sous-reseaux prives : Les noeuds workers operent dans des sous-reseaux prives
• Hote bastion : Acces SSH au VPC via bastion
• Groupes d'acces : Roles IAM pour un controle d'acces granulaire

Surveillance

• CloudWatch : Surveillance et journalisation continues du systeme
• Journalisation structuree : Suivi des requetes et metriques de performance
• Verification de l'etat : Surveillance automatisee de l'etat du systeme

Integration Brightway

EOS exploite Brightway, un cadre ACV open source :

Pourquoi Brightway ?

Capacite	Avantage
Flexibilite	Calculs ACV personnalises pour divers produits alimentaires
Integration de bases de donnees	Integration facile avec ecoinvent, Agribalyse via routines d'importation
Analyse d'incertitude	Methodes robustes pour l'analyse de sensibilite
Evolutivite	Gere des calculs complexes pour des evaluations detaillees
Communaute	Open source avec mises a jour methodologiques continues

Transformation matricielle

La transformation matricielle est le coeur computationnel des calculs ACV :

1. Graphe vers matrice : Convertir les reseaux de chaine d'approvisionnement en matrices mathematiques
2. Modelisation entree-sortie : Representer les relations entre processus
3. Algebre matricielle : Calculer les incidences environnementales cumulees
4. Evaluation de l'incidence : Appliquer les methodes 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 deploiement de conteneurs Docker
• Karpenter : Provisionnement automatique des noeuds selon la demande
• Charts Helm : Configurations de deploiement standardisees

Stockage de donnees

Composant	Technologie	Objectif
Base de donnees principale	PostgreSQL	Donnees structurees (produits, recettes, utilisateurs)
Pilote asynchrone	asyncpg	Acces asynchrone haute performance a la base de donnees
File de messages	RabbitMQ	Distribution des requetes et equilibrage de charge

Systeme d'identifiant externe (Xid)

Le systeme Xid assure l'integrite des donnees avec les systemes externes :

• Identifiants uniques : Chaque entite a un identifiant externe a portee d'espace de noms
• Correspondance UUID : Relation 1-1 entre Xid et UUID interne
• Reference croisee : Recherche facile entre les espaces de noms
• Versionnage : Suivi des changements dans le temps

Journal des mutations (Retour arriere/Rejouer)

Toutes les modifications du graphe sont journalisees pour l'auditabilite et le debogage :

# 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)

Capacites :

• Retour arriere : Inverser les mutations pour restaurer l'etat precedent
• Rejouer : Reconstruire l'etat du systeme ou appliquer des changements a differents environnements
• Debogage : Tracer les etapes de calcul pour l'investigation des erreurs
• Transparence : Piste d'audit complete pour tous les calculs

Prochaines etapes

• Fonctionnement - Flux de calcul etape par etape
• Gap Filling Modules - Details du systeme de modules
• SDK GFM (bientot disponible) - Construire des modules personnalises