Diagrama de arquitectura

Resumen

Este documento describe la arquitectura técnica del proyecto Pedido Sugerido para los tres Niveles definidos en la propuesta v2. Cada Nivel se presenta como un incremento sobre el anterior: el Nivel 1 establece la operación automatizada con un pipeline parametrizado por país, el Nivel 2 incorpora gestión formal del modelo (Feature Store, Model Registry, CI/CD) y el Nivel 3 cierra con automatización completa (retraining por drift, multi-modelo, gobernanza).

Los nombres de recursos AWS siguen el patrón verbose acordado en DOC-AF-03 (ej. aje-dev-ps-pipeline-codepipeline, aje-dev-ps-pipeline-sagemaker). La arquitectura completa al Nivel 3 se compone de ~45 recursos distintos orquestados como un solo sistema.

Decisiones técnicas transversales

Aplican a los tres Niveles. Documentadas acá para evitar repetición.

Nivel 1 · Automatización · pipeline operativo

Objetivo: pipeline parametrizado por país que corre L-V sin intervención manual, con monitoreo operativo y código/datos versionados.

Diagrama de flujo · alto nivel

                                      [ EventBridge × 7 ]
                                      cron L-V escalonado
                                  CR  EC  GT  MX  NI  PA  PE
                                      │
                                      ▼
                          [ Lambda · aje-dev-ps-triggerfunction ]
                          recibe { code_country } y dispara el SM Pipeline
                                      │
                                      ▼
                         ┌──────────────────────────────────────┐
                         │ SageMaker Pipeline                   │
                         │ aje-dev-ps-pipeline-sagemaker        │
                         │                                      │
                         │  ┌────────────┐                      │
                         │  │ Limpieza   │ ProcessingStep       │
                         │  │ (Docker:   │ image: processing    │
                         │  │ processing)│ instance: ml.m5.4xl  │
                         │  └─────┬──────┘                      │
                         │        │ outputs CSV/parquet         │
                         │        ▼                             │
                         │  ┌────────────┐                      │
                         │  │ Modelado   │ ProcessingStep       │
                         │  │ (Docker:   │ image: spark         │
                         │  │ spark)     │ instance: ml.m5.4xl  │
                         │  └─────┬──────┘                      │
                         │        │ outputs modelo + top-N      │
                         │        ▼                             │
                         │  ┌────────────┐                      │
                         │  │ Reglas     │ ProcessingStep       │
                         │  │ Negocio    │ image: processing    │
                         │  │ (Docker)   │ instance: ml.m5.4xl  │
                         │  └─────┬──────┘                      │
                         │        │ output: recomendaciones     │
                         └────────┼─────────────────────────────┘
                                  │
                                  ▼
                  s3://aje-dev-analytics-artifacts-s3/ps-pipeline/<PAIS>/

                       ─ ─ ─ Monitoreo cross-cutting ─ ─ ─
                                  │
                ┌─────────────────┼──────────────────┐
                ▼                 ▼                  ▼
        CloudWatch        CloudWatch           SNS Topic
        Logs              Dashboard            aje-dev-ps-alert-topic
        (cada step        + 2 Alarms           ↓
        emite logs)       (failed/stopped)   suscripciones email
                                              (definidas en DOC-AF-08)

Componentes Nivel 1 · tabla detallada

Total componentes Nivel 1: 16

Nivel 2 · Gestión del modelo · trazabilidad y calidad

Objetivo: separar el flujo de entrenamiento (semanal) del de inferencia (diaria); registrar modelos con métricas en Model Registry; configurar Feature Store para features compartidas entre países; agregar CI/CD con gates de calidad.

Incremento sobre Nivel 1

                       ────── NUEVOS componentes del Nivel 2 ──────

                  ┌────────────────────────────────────────────┐
                  │   Pipeline de ENTRENAMIENTO (semanal)      │
                  │   aje-dev-ps-trainpipeline-sagemaker       │
                  │                                            │
                  │  Limpieza → ALS Train → Eval → Register   │
                  │                            │               │
                  └────────────────────────────┼───────────────┘
                                               │
                                               ▼
                            ┌──────────────────────────────────┐
                            │ Model Registry × 7 países        │
                            │ aje-dev-ps-recmodel-EC-sagemaker │
                            │ aje-dev-ps-recmodel-MX-sagemaker │
                            │ ... (uno por país)               │
                            │                                  │
                            │ Status: PendingApproval →        │
                            │         Approved / Rejected      │
                            └──────────────┬───────────────────┘
                                           │ approval (Gate 3 humano)
                                           ▼
                            ┌──────────────────────────────────┐
                            │   Pipeline de INFERENCIA (diario)│
                            │   aje-dev-ps-infpipeline-sagemaker│
                            │                                  │
                            │   Carga modelo → Inferencia →    │
                            │   Reglas → Output                │
                            └────────┬─────────────────────────┘
                                     │
                                     ▼
                          Outputs (mismo que Nivel 1)


                          ────── Feature Store ──────

                  ┌──────────────────────────────────────────────┐
                  │ SageMaker Feature Store                      │
                  │                                              │
                  │ aje-dev-ps-cliente-features-featurestore     │
                  │   - id_cliente, frecuencia, recencia,        │
                  │     ticket_promedio, categoria_principal     │
                  │                                              │
                  │ aje-dev-ps-producto-features-featurestore    │
                  │   - cod_articulo_magic, popularidad,         │
                  │     elasticidad, sustitutos                  │
                  └──────────────────────────────────────────────┘


                          ────── CI/CD enriquecido ──────

                  ┌──────────────────────────────────────────────┐
                  │ CodePipeline ya existente · stages nuevos:   │
                  │                                              │
                  │ Build → Test → Staging → Approval → Prod    │
                  │                            ↑                 │
                  │                  Aprobación humana           │
                  │                  manual notificada por SNS   │
                  └──────────────────────────────────────────────┘


                          ────── Model Monitor ──────

                  ┌──────────────────────────────────────────────┐
                  │ SageMaker Model Monitor                      │
                  │                                              │
                  │ Baseline · estadísticas del último           │
                  │            entrenamiento aprobado            │
                  │                                              │
                  │ Schedule diario · compara producción vs      │
                  │                   baseline (data drift)      │
                  └──────────────────────────────────────────────┘

Componentes nuevos Nivel 2 · tabla

Total nuevos Nivel 2: 13 → Total acumulado Nivel 2: 29 componentes

Nivel 3 · Automatización completa · replicable y autónomo

Objetivo: reentrenamiento automático cuando se detecta drift, multi-modelo por país con experimentos en grid, gobernanza completa (Model Cards + CloudTrail), e IaC final como plantilla replicable.

Incremento sobre Nivel 2

                       ────── NUEVOS componentes del Nivel 3 ──────

                  ┌────────────────────────────────────────────────┐
                  │ Retraining loop · automático por drift         │
                  │                                                │
                  │  Model Monitor → Alarm → EventBridge → Lambda  │
                  │  detecta drift   activa  trigger    dispara    │
                  │                                                │
                  │  ↓                                             │
                  │                                                │
                  │  Lambda invoca aje-dev-ps-trainpipeline-       │
                  │  sagemaker en modo retraining                  │
                  │                                                │
                  │  ↓                                             │
                  │                                                │
                  │  Nuevo modelo registrado · pasa Gate 1 (regr.) │
                  │  + Gate 2 (métricas) · Gate 3 (humano si       │
                  │  drift fue por concept) → deploy automático    │
                  └────────────────────────────────────────────────┘


                  ┌────────────────────────────────────────────────┐
                  │ Multi-modelo · SageMaker Experiments           │
                  │                                                │
                  │ Grid de hiperparámetros ALS por país           │
                  │   rank ∈ {10, 20, 50, 100}                     │
                  │   regParam ∈ {0.01, 0.1, 1.0}                  │
                  │   alpha ∈ {1, 10, 40}                          │
                  │                                                │
                  │ Selección automática por mejor NDCG@10         │
                  └────────────────────────────────────────────────┘


                  ┌────────────────────────────────────────────────┐
                  │ Gobernanza                                     │
                  │                                                │
                  │ Model Cards · metadata estandarizada por       │
                  │   modelo (training data, métricas, owner,      │
                  │   intended use, limitations)                   │
                  │                                                │
                  │ CloudTrail · trail dedicado del proyecto       │
                  │   audit log: quién aprobó qué modelo,          │
                  │   con qué datos, en qué momento                │
                  └────────────────────────────────────────────────┘


                  ┌────────────────────────────────────────────────┐
                  │ IaC final · CDK app completa                   │
                  │                                                │
                  │ aje-analytics-model-pedido-sugerido/infra/     │
                  │   ↳ Stack único parametrizable por stage       │
                  │     y por country list                         │
                  │                                                │
                  │ → Replicable: nuevo modelo de AJE en días,     │
                  │   no semanas                                   │
                  └────────────────────────────────────────────────┘

Componentes nuevos Nivel 3 · tabla

Total nuevos Nivel 3: 10 → Total acumulado Nivel 3: 39 componentes (más recursos auxiliares como log groups y bucket policies = ~45 recursos total)

Patrones recurrentes

Pattern 1 · Multi-país parametrizado

Todos los componentes que tienen versión por país siguen el mismo patrón:

• DynamoDB config table (aje-dev-ps-configtable-dynamodb) con una fila por code_country
• Lambda recibe {code_country} como event payload
• SM Pipeline acepta code_country como parámetro
• Outputs en S3 segregados por país: s3://aje-dev-analytics-artifacts-s3/ps-pipeline/<PAIS>/
• En Nivel 2-3, Model Registry, Feature Store y experimentos también scoped por país

Pattern 2 · Gates de calidad en serie

En Nivel 2-3, los modelos pasan por tres gates antes de promoción a producción:

1. Tests de regresión (automático) — schema, volumen, latencia, costo
2. Métricas vs baseline (automático) — NDCG@10 > baseline + 0.01
3. Aprobación humana (opcional según contexto) — analista de Athenea aprueba en consola SageMaker

Las reglas exactas se documentan en DOC-AF-04.

Pattern 3 · Observabilidad por capas

Cada Nivel agrega capa de observabilidad sobre el anterior:

• Nivel 1 · operacional (success/failure de pipeline) — DOC-AF-08 cataloga las alarmas
• Nivel 2 · de modelo (data drift + métricas de calidad) — Model Monitor
• Nivel 3 · de gobernanza (audit trail con CloudTrail + Model Cards)

Decisiones técnicas anotadas

Próximos pasos

1. Sesión 2 (Mié 20-may) · validar con AJE el diagrama de Nivel 1 (el menos cambiable) y aprobar conceptualmente los Niveles 2-3 (que se concretan en Touchpoints).
2. Generar diagramas visuales (PNG + fuente draw.io) antes del cierre de la fase. La descripción ASCII de este documento queda como referencia de lectura, pero el entregable final es un PNG por Nivel.
3. Touchpoint Nivel 2 (Lun 15-jun) · confirmar componentes propuestos del Nivel 2 (Feature Store schema, separación train/inference, gates de aprobación).
4. Touchpoint Nivel 3 (Lun 6-jul) · confirmar mecánica multi-modelo y workflow de retraining con data observada de Niveles 1-2.