Inmersión Técnica

EOS Core sigue una arquitectura por capas diseñada para modularidad, extensibilidad y cálculos de impacto ambiental auditables.

Visión General del Sistema

acb6d4161e7f8479a6a21114046bbdd4

Capas Arquitectónicas

Capa de API

La capa de API proporciona dos interfaces:

REST API v2 (/v2/* en puerto 8040)

API REST moderna basada en FastAPI
Autenticación con token JWT con grupos de acceso
Soporte para cálculo por lotes
Registro estructurado de solicitudes
Apagado elegante con detección de archivo de drenaje

API Legacy v1 (/api/* en puerto 8050)

Endpoints compatibles con versiones anteriores
Envuelve la funcionalidad de API v2
Soporta métodos de autenticación legacy

Capa Core

CalcGraph - La estructura de cálculo central:

# CalcGraph gestiona todo el cálculo como un grafo dirigido
class CalcGraph:
    root_node_uid: str           # Punto de entrada para el cálculo
    nodes: dict[str, Node]       # Todos los nodos en el grafo
    mutations: list[Mutation]    # Registro de cambios auditable

    def add_graph_observer(observer)  # Activación de GFM
    def apply_mutation(mutation)       # Cambios transparentes

Orquestador - Coordina la ejecución de GFM:

class Orchestrator(AbstractGraphObserver):
    async def run():
        # 1. Inicializar nodos desde raíz o sub-nodos enlazados
        # 2. Generar trabajadores GFM en nodos iniciales
        # 3. Bucle de programación:
        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)

Proveedor de Servicios - Contenedor de inyección de dependencias:

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

Capa de Módulos

Los módulos siguen el patrón Factory/Worker:

3dd35a79758bfd3a6a8c93ad3fc0baa0

Factory (Singleton por servicio):

Inicializado una vez al inicio del servicio
Mantiene conexiones de base de datos y cachés
Genera trabajadores para nodos individuales

Worker (Por nodo):

should_be_scheduled() - ¿Es este GFM relevante para este nodo?
can_run_now() - ¿Están satisfechas las dependencias?
run() - Ejecutar la lógica de relleno de vacíos

Capa de Datos

PostgreSQL con asyncpg:

Pool de conexiones para operaciones asíncronas
Campos JSONB para almacenamiento flexible de propiedades de nodos
Esquema en database/postgres/schema.sql

Clases Manager (patrón DAO):

PostgresGraphMgr - Persistencia de nodos/aristas
PgTermMgr - Operaciones de glosario
PgMatchingMgr - Datos de coincidencia de ingredientes
PostgresAccessMgr - Control de acceso de usuarios/grupos

Tipos de Nodos

EOS utiliza un sistema de tipos rico para nodos del grafo:

2464c9bed53db3ab3ca58b37b386a4a6

Tipo de Nodo	Propósito
`FoodProductFlowNode`	Producto alimentario con composición
`AggregationFoodProductFlowNode`	Cachés de agregación diaria para optimización de rendimiento
`PracticeFlowNode`	Prácticas agrícolas o de procesamiento
`ElementaryResourceEmissionNode`	Emisiones ambientales
`FoodProcessingActivityNode`	Operaciones de procesamiento
`TransportActivityNode`	Transporte
`ModeledActivityNode`	Inventario ACV de Brightway
`LinkingActivityNode`	Enlaza nodos de flujo a nodos de actividad
`SupplySheetActivityNode`	Datos de hoja de suministro de fuentes externas
`AggregationFoodProcessingActivityNode`	Actividades de procesamiento agregadas

Sistema de Propiedades

Los nodos almacenan datos a través de propiedades tipadas:

Tipo de Propiedad	Descripción
`QuantityProp`	Mediciones con unidades
`LocationProp`	Datos geográficos
`GlossaryTermProp`	Enlaces a terminología
`EnvironmentalFlowsProp`	Resultados de impacto
`NamesProp`	Nombrado multilingüe
`GfmStateProp`	Estado de ejecución de GFM

Flujo de Datos

5849053d462fe0af5f229cf4bb50c241

Multi-Tenencia

EOS soporta aislamiento multi-inquilino:

ae6b424edc37f8dc69597ee6d9b88a44

Namespace - Aislamiento de organización/ecosistema
Grupo de Acceso - Equipo/departamento dentro del namespace
Usuario - Individual con autenticación OAuth2/email
Permisos - Control de acceso por nodo

Arquitectura de Mensajería

RabbitMQ permite procesamiento distribuido:

a8fae90006127811d9901c0380531ee2

Cola de alta prioridad - Solicitudes interactivas
Cola de baja prioridad - Procesamiento por lotes
Gestión de prefetch - Programación consciente de recursos

Manejo de Errores

Modelo de error estructurado para errores de dominio:

@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

Mutaciones del Grafo

Todos los cambios del grafo son transparentes y auditables:

Tipo de Mutación	Propósito
`AddNodeMutation`	Insertar nuevo nodo
`PropMutation`	Actualizar propiedad individual
`AddEdgeMutation`	Crear relación entre nodos
`RemoveEdgeMutation`	Eliminar relación
`DuplicateNodeMutation`	Clonar nodo

Beneficios:

Auditabilidad - Registro completo de mutaciones
Determinismo - Cálculos reproducibles
Transparencia - Revisión no técnica posible

Arquitectura de Rendimiento

EOS está optimizado para cálculos de impacto ambiental en tiempo real, con objetivo de tiempos de respuesta inferiores a 2 segundos para aplicaciones interactivas de restaurantes.

Optimizaciones de Rendimiento

Optimización	Impacto
Cálculos Matriciales	Acelerado de 5s a 1s por cálculo (mejora del 80%)
Procesamiento Concurrente	Operación paralela en múltiples pods con cola de solicitudes inteligente
Servicio GADM	Implementación en Rust logrando reducción de memoria 3x y mejora de velocidad 10x
Caché Multinivel	Callbacks en memoria en cada nivel de ACV dentro de la misma instancia
Balanceo de Carga	Distribución de solicitudes basada en RabbitMQ entre pods de trabajo

Escalabilidad

El sistema utiliza Elastic Kubernetes Service (EKS) con escalado automático:

Escalado Dinámico: Hasta 1024 pods basado en carga de trabajo
Karpenter: Aprovisionamiento y escalado automático de nodos
Optimización de Recursos: Despliegues legacy y core separados para uso eficiente de RAM
Arquitectura de Microservicios: Procesamiento en memoria optimizado para minimizar complejidad de mensajería

Estrategia de Caché

La caché multinivel reduce la carga computacional:

┌─────────────────────────────────────────────────┐
│  Nivel de Solicitud  │ Resultados de cálculo    │
│                      │ en caché                 │
├─────────────────────────────────────────────────┤
│  Nivel de GFM        │ Cachés de Factory        │
│                      │ (emisiones, actividades, │
│                      │ términos de glosario)    │
├─────────────────────────────────────────────────┤
│  Nivel de Base       │ Pool de conexiones,      │
│  de Datos            │ caché de resultados      │
│                      │ de consultas             │
└─────────────────────────────────────────────────┘

Invalidación de caché inteligente basada en cambios de datos
Invalidación selectiva para minimizar recálculo
Caché distribuida para despliegues en la nube

Arquitectura de Seguridad

EOS implementa un enfoque de seguridad multicapa:

Autenticación

b524cac028f181330c106b0e2c62612b

Tipos de Token:

Tokens de staff - Acceso administrativo con privilegios elevados
Tokens de namespace - Acceso a nivel de organización
Tokens de usuario - Acceso de usuario individual con períodos de validez limitados

Seguridad de Red

Subredes Privadas: Los nodos de trabajo operan en subredes privadas
Host Bastión: Acceso SSH a VPC a través de bastión
Grupos de Acceso: Roles IAM para control de acceso granular

Monitorización

CloudWatch: Monitorización y registro continuo del sistema
Registro Estructurado: Seguimiento de solicitudes y métricas de rendimiento
Comprobaciones de Salud: Monitorización automatizada de salud del sistema

Integración con Brightway

EOS aprovecha Brightway, un marco de ACV de código abierto:

¿Por qué Brightway?

Capacidad	Beneficio
Flexibilidad	Cálculos de ACV personalizados para diversos productos alimentarios
Integración de Bases de Datos	Fácil integración con ecoinvent, Agribalyse vía rutinas de importación
Análisis de Incertidumbre	Métodos robustos para análisis de sensibilidad
Escalabilidad	Maneja cálculos complejos para evaluaciones detalladas
Comunidad	Código abierto con actualizaciones metodológicas continuas

Transformación Matricial

La Transformación Matricial es el núcleo computacional para cálculos de ACV:

Grafo a Matriz: Convertir redes de cadena de suministro en matrices matemáticas
Modelado Input-Output: Representar relaciones entre procesos
Álgebra Matricial: Calcular impactos ambientales acumulativos
Evaluación de Impacto: Aplicar métodos LCIA (por ejemplo, IPCC GWP100)

# Cálculo matricial conceptual
# A = matriz tecnológica (entradas/salidas de procesos)
# B = matriz de intervención (intercambios ambientales)
# f = vector de demanda final
# s = vector de escala = A^(-1) * f
# g = resultado de inventario = B * s

Infraestructura

Orquestación de Contenedores

Kubernetes: Orquestación y despliegue de contenedores Docker
Karpenter: Aprovisionamiento automático de nodos basado en demanda
Helm Charts: Configuraciones de despliegue estandarizadas

Almacenamiento de Datos

Componente	Tecnología	Propósito
Base de Datos Principal	PostgreSQL	Datos estructurados (productos, recetas, usuarios)
Driver Asíncrono	asyncpg	Acceso asíncrono de alto rendimiento a base de datos
Cola de Mensajes	RabbitMQ	Distribución de solicitudes y balanceo de carga

Sistema de ID Externo (Xid)

El sistema Xid asegura la integridad de datos con sistemas externos:

Identificadores Únicos: Cada entidad tiene un ID externo con ámbito de namespace
Mapeo UUID: Relación 1-1 entre Xid y UUID interno
Referencias Cruzadas: Búsqueda fácil entre namespaces
Versionado: Seguimiento de cambios a lo largo del tiempo

Registro de Mutaciones (Rebobinar/Reproducir)

Todos los cambios del grafo se registran para auditabilidad y depuración:

# Cada mutación se registra
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)

Capacidades:

Rebobinar: Revertir mutaciones para restaurar estado previo
Reproducir: Reconstruir estado del sistema o aplicar cambios a diferentes entornos
Depuración: Rastrear pasos de cálculo para investigación de errores
Transparencia: Registro de auditoría completo para todos los cálculos

Siguientes Pasos

Cómo Funciona - Flujo de cálculo paso a paso
Gap Filling Modules - Detalles del sistema de módulos
GFM SDK (próximamente) - Construir módulos personalizados

Visión General del Sistema​

Capas Arquitectónicas​

Capa de API​

Capa Core​

Capa de Módulos​

Capa de Datos​

Tipos de Nodos​

Sistema de Propiedades​

Flujo de Datos​

Multi-Tenencia​

Arquitectura de Mensajería​

Manejo de Errores​

Mutaciones del Grafo​

Arquitectura de Rendimiento​

Optimizaciones de Rendimiento​

Escalabilidad​

Estrategia de Caché​

Arquitectura de Seguridad​

Autenticación​

Seguridad de Red​

Monitorización​

Integración con Brightway​

¿Por qué Brightway?​

Transformación Matricial​

Infraestructura​

Orquestación de Contenedores​

Almacenamiento de Datos​

Sistema de ID Externo (Xid)​

Registro de Mutaciones (Rebobinar/Reproducir)​

Siguientes Pasos​