Approfondimento Tecnico

EOS Core segue un'architettura a livelli progettata per modularita, estensibilita e calcoli di impatto ambientale verificabili.

Panoramica del Sistema

Livelli Architetturali

Livello API

Il livello API fornisce due interfacce:

API REST v2 (/v2/* sulla porta 8040)

• API REST moderna basata su FastAPI
• Autenticazione con token JWT e gruppi di accesso
• Supporto per calcoli batch
• Logging strutturato delle richieste
• Spegnimento controllato con rilevamento file di drain

API Legacy v1 (/api/* sulla porta 8050)

• Endpoint retrocompatibili
• Incapsula le funzionalita dell'API v2
• Supporto per metodi di autenticazione legacy

Livello Core

CalcGraph - La struttura di calcolo centrale:

# CalcGraph gestisce l'intero calcolo come un grafo orientato
class CalcGraph:
    root_node_uid: str           # Punto di ingresso per il calcolo
    nodes: dict[str, Node]       # Tutti i nodi nel grafo
    mutations: list[Mutation]    # Log delle modifiche verificabili

    def add_graph_observer(observer)  # Attivazione GFM
    def apply_mutation(mutation)       # Modifiche trasparenti

Orchestratore - Coordina l'esecuzione dei GFM:

class Orchestrator(AbstractGraphObserver):
    async def run():
        # 1. Inizializza i nodi dal root o dai sotto-nodi collegati
        # 2. Crea worker GFM sui nodi iniziali
        # 3. Ciclo di pianificazione:
        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 - Contenitore di dependency injection:

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

Livello Moduli

I moduli seguono il pattern Factory/Worker:

Factory (Singleton per servizio):

• Inizializzato una volta all'avvio del servizio
• Mantiene connessioni al database e cache
• Crea worker per i singoli nodi

Worker (Per nodo):

• should_be_scheduled() - Questo GFM e rilevante per questo nodo?
• can_run_now() - Le dipendenze sono soddisfatte?
• run() - Esegue la logica di gap-filling

Livello Dati

PostgreSQL con asyncpg:

• Connection pooling per operazioni asincrone
• Campi JSONB per memorizzazione flessibile delle proprieta dei nodi
• Schema in database/postgres/schema.sql

Classi Manager (pattern DAO):

• PostgresGraphMgr - Persistenza nodi/archi
• PgTermMgr - Operazioni sul glossario
• PgMatchingMgr - Dati di matching ingredienti
• PostgresAccessMgr - Controllo accessi utenti/gruppi

Tipi di Nodo

EOS utilizza un ricco sistema di tipi per i nodi del grafo:

Tipo di Nodo	Scopo
FoodProductFlowNode	Prodotto alimentare con composizione
AggregationFoodProductFlowNode	Cache di aggregazione giornaliera per ottimizzazione prestazioni
PracticeFlowNode	Pratiche agricole o di lavorazione
ElementaryResourceEmissionNode	Emissioni ambientali
FoodProcessingActivityNode	Operazioni di trasformazione
TransportActivityNode	Trasporto
ModeledActivityNode	Inventario LCA Brightway
LinkingActivityNode	Collega nodi di flusso a nodi di attivita
SupplySheetActivityNode	Dati della scheda di fornitura da fonti esterne
AggregationFoodProcessingActivityNode	Attivita di trasformazione aggregate

Sistema di Proprieta

I nodi memorizzano dati attraverso proprieta tipizzate:

Tipo di Proprieta	Descrizione
QuantityProp	Misurazioni con unita
LocationProp	Dati geografici
GlossaryTermProp	Link alla terminologia
EnvironmentalFlowsProp	Risultati di impatto
NamesProp	Denominazione multilingue
GfmStateProp	Stato di esecuzione GFM

Flusso dei Dati

Multi-Tenancy

EOS supporta l'isolamento multi-tenant:

• Namespace - Isolamento organizzazione/ecosistema
• Gruppo di Accesso - Team/dipartimento all'interno del namespace
• Utente - Individuo con autenticazione OAuth2/email
• Permessi - Controllo accessi per nodo

Architettura di Messaggistica

RabbitMQ abilita l'elaborazione distribuita:

• Coda alta priorita - Richieste interattive
• Coda bassa priorita - Elaborazione batch
• Gestione prefetch - Pianificazione consapevole delle risorse

Gestione degli Errori

Modello di errore strutturato per errori di dominio:

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

Mutazioni del Grafo

Tutte le modifiche al grafo sono trasparenti e verificabili:

Tipo di Mutazione	Scopo
AddNodeMutation	Inserisci nuovo nodo
PropMutation	Aggiorna singola proprieta
AddEdgeMutation	Crea relazione tra nodi
RemoveEdgeMutation	Elimina relazione
DuplicateNodeMutation	Clona nodo

Vantaggi:

• Verificabilita - Log completo delle mutazioni
• Determinismo - Calcoli riproducibili
• Trasparenza - Revisione non tecnica possibile

Architettura delle Prestazioni

EOS e ottimizzato per calcoli di impatto ambientale in tempo reale, puntando a tempi di risposta inferiori a 2 secondi per applicazioni interattive nei ristoranti.

Ottimizzazioni delle Prestazioni

Ottimizzazione	Impatto
Calcoli Matriciali	Accelerati da 5s a 1s per calcolo (miglioramento dell'80%)
Elaborazione Concorrente	Operazione parallela su piu pod con accodamento intelligente delle richieste
Servizio GADM	Implementazione Rust che raggiunge riduzione memoria 3x e miglioramento velocita 10x
Cache Multi-livello	Callback in memoria a ogni livello LCA nella stessa istanza
Bilanciamento del Carico	Distribuzione richieste basata su RabbitMQ tra pod worker

Scalabilita

Il sistema utilizza Elastic Kubernetes Service (EKS) con scalabilita automatica:

• Scaling Dinamico: Fino a 1024 pod in base al carico di lavoro
• Karpenter: Provisioning e scaling automatico dei nodi
• Ottimizzazione Risorse: Deployment separati legacy e core per uso efficiente della RAM
• Architettura a Microservizi: Elaborazione in memoria semplificata per minimizzare la complessita della messaggistica

Strategia di Caching

Il caching multi-livello riduce il carico computazionale:

┌─────────────────────────────────────────────────┐
│  Livello Richiesta  │ Risultati calcolo in cache │
├─────────────────────────────────────────────────┤
│  Livello GFM        │ Cache Factory (emissioni,  │
│                     │ attivita, termini glossario)│
├─────────────────────────────────────────────────┤
│  Livello Database   │ Connection pooling,        │
│                     │ cache risultati query      │
└─────────────────────────────────────────────────┘

• Invalidazione cache intelligente basata su modifiche dati
• Invalidazione selettiva per minimizzare il ricalcolo
• Caching distribuito per deployment cloud

Architettura di Sicurezza

EOS implementa un approccio di sicurezza multi-livello:

Autenticazione

Tipi di Token:

• Token staff - Accesso amministrativo con privilegi elevati
• Token namespace - Accesso a livello organizzazione
• Token utente - Accesso utente individuale con periodi di validita limitati

Sicurezza di Rete

• Subnet Private: I nodi worker operano in subnet private
• Host Bastion: Accesso SSH al VPC attraverso bastion
• Gruppi di Accesso: Ruoli IAM per controllo accessi granulare

Monitoraggio

• CloudWatch: Monitoraggio e logging continuo del sistema
• Logging Strutturato: Tracciamento richieste e metriche di prestazione
• Health Check: Monitoraggio automatico della salute del sistema

Integrazione Brightway

EOS sfrutta Brightway, un framework LCA open-source:

Perche Brightway?

Funzionalita	Beneficio
Flessibilita	Calcoli LCA personalizzati per diversi prodotti alimentari
Integrazione Database	Facile integrazione con ecoinvent, Agribalyse tramite routine di importazione
Analisi di Incertezza	Metodi robusti per analisi di sensibilita
Scalabilita	Gestisce calcoli complessi per valutazioni dettagliate
Comunita	Open-source con aggiornamenti metodologici continui

Trasformazione Matriciale

La Trasformazione Matriciale e il nucleo computazionale per i calcoli LCA:

1. Grafo a Matrice: Converti reti della catena di fornitura in matrici matematiche
2. Modellazione Input-Output: Rappresenta le relazioni tra processi
3. Algebra Matriciale: Calcola gli impatti ambientali cumulativi
4. Valutazione di Impatto: Applica metodi LCIA (es. IPCC GWP100)

# Calcolo matriciale concettuale
# A = matrice tecnologica (input/output dei processi)
# B = matrice di intervento (scambi ambientali)
# f = vettore della domanda finale
# s = vettore di scaling = A^(-1) * f
# g = risultato inventario = B * s

Infrastruttura

Orchestrazione Container

• Kubernetes: Orchestrazione e deployment di container Docker
• Karpenter: Provisioning automatico dei nodi in base alla domanda
• Helm Charts: Configurazioni di deployment standardizzate

Archiviazione Dati

Componente	Tecnologia	Scopo
Database Primario	PostgreSQL	Dati strutturati (prodotti, ricette, utenti)
Driver Asincrono	asyncpg	Accesso database asincrono ad alte prestazioni
Coda Messaggi	RabbitMQ	Distribuzione richieste e bilanciamento del carico

Sistema ID Esterno (Xid)

Il sistema Xid garantisce l'integrita dei dati con sistemi esterni:

• Identificatori Unici: Ogni entita ha un ID esterno con scope nel namespace
• Mapping UUID: Relazione 1-1 tra Xid e UUID interno
• Cross-referencing: Ricerca facile tra namespace
• Versionamento: Tracciamento delle modifiche nel tempo

Log delle Mutazioni (Rewind/Replay)

Tutte le modifiche al grafo sono registrate per verificabilita e debug:

# Ogni mutazione viene registrata
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)

Funzionalita:

• Rewind: Inverti le mutazioni per ripristinare lo stato precedente
• Replay: Ricostruisci lo stato del sistema o applica modifiche ad ambienti diversi
• Debug: Traccia i passaggi di calcolo per investigare errori
• Trasparenza: Traccia di audit completa per tutti i calcoli

Prossimi Passi

• Come Funziona - Flusso di calcolo passo dopo passo
• Gap Filling Module - Dettagli del sistema modulare
• GFM SDK (in arrivo) - Costruisci moduli personalizzati