Arquitectura

Frontera Nilo ↔ nosotros (vista lógica)

mermaid

flowchart TB
    subgraph Cliente["Cliente final (ferretería)"]
        WA[WhatsApp en smartphone]
        PWA[PWA B2B 'light']
    end

    subgraph NiloLayer["Capa Nilo Commerce (no la tocamos)"]
        WACA[WhatsApp Business Cloud API]
        Agent[Agente conversacional IA<br/>NLP · ASR · Vision · RAG]
        Flows[WhatsApp Flows]
    end

    subgraph EchoLayer["Capa ECHO Backend - NUESTRA"]
        Gateway[API Gateway / Auth]
        SvcCust[Servicio Clientes]
        SvcCatalog[Servicio Catálogo y Precios]
        SvcCredit[Servicio Crédito]
        SvcOrders[Servicio Órdenes]
        SvcFiscal[Servicio Fiscal MX]
        SvcKB[Servicio Base de Conocimiento]
        Orchestrator[Orquestador<br/>Application Integration GCP]
        Audit[(Audit Trail<br/>Bucket inmutable)]
    end

    subgraph SAPLayer["SAP - Core empresarial"]
        BTP[SAP BTP Integration Suite<br/>iPaaS]
        SAP[SAP ERP<br/>SD · MDM]
    end

    subgraph PartnerLayer["Operador logístico 3PL"]
        DT[DispatchTrack]
    end

    WA --> WACA
    PWA -.opcional.-> Gateway
    WACA <--> Agent
    Agent <--> Flows
    Agent -->|HTTPS| Gateway

    Gateway --> SvcCust
    Gateway --> SvcCatalog
    Gateway --> SvcCredit
    Gateway --> SvcOrders
    Gateway --> SvcKB

    SvcOrders --> SvcFiscal
    SvcOrders --> Orchestrator
    Orchestrator <-->|JSON| BTP
    BTP <-->|IDoc · BAPI| SAP

    Orchestrator -->|IDoc SHPORD| DT
    DT -->|Webhook POD| Gateway
    Gateway --> SvcOrders
    SvcOrders --> Audit
    SvcOrders -->|PGI| BTP

Lectura rápida: el agente Nilo (gris) consume nuestras APIs (azul). Nosotros traducimos esas llamadas a SAP (vía BTP) y a DispatchTrack. El POD entra como webhook desde 3PL, dispara PGI en SAP y se archiva como evidencia inmutable.

El "Camino del Dato" (storyboard ALCOA+)

Mapeo del storyboard del PR/FAQ §2.2 a quién hace qué de nuestro lado:

#	Acción de negocio	Pieza nuestra que actúa	Pilar ALCOA
1	El ferretero envía "5 codos de media" por WhatsApp; el agente identifica al cliente.	`GET /customers?bsuid=…` o `?phone=…` (HU-07) — registra timestamp + GPS de la petición.	Atribuible
2	El agente valida descuento por graduación y límite de crédito.	`GET /products/{sku}/price?customerCode=…` + `POST /credit/validate` — precios derivados de SAP MDM, jamás hardcoded.	Exacto
3	El cliente confirma. El pedido se inyecta en SAP.	`POST /orders` → Orquestador → BTP iFlow → SAP SD. SLA <60 s.	Contemporáneo
4	SAP confirma disponibilidad; se dispara el despacho al 3PL.	Orquestador emite IDoc `SHPORD` vía API a DispatchTrack (HU-05).	Original
5	El repartidor entrega; el cliente firma; se toma foto.	Webhook POD de DispatchTrack → `SvcOrders` almacena evidencia en bucket + dispara PGI (HU-06).	Legible · Completo
6	Cierre del día: Finanzas revisa el log de cambios.	Audit trail vivo en SAP + nuestro bucket inmutable, retención 5 años.	Disponible · Duradero

Mapeo a la infraestructura GCP del onboarding

Las cajas siguientes son hipótesis razonables basadas en lo que se mencionó en el onboarding (GCP Cloud Functions, containers, VMs, Buckets, Application Integration + GitLab/GitHub) y en la naturaleza de cada función. Validar con arquitectura — anotadas en 06-pendientes.md.

Componente GCP	Para qué lo usamos	HU / función relacionada
Cloud Functions	Webhooks de Nilo (eventos del agente) y de DispatchTrack (POD). Disparadores breves, sin estado, picos impredecibles.	HU-06 webhook POD, eventos Nilo.
Cloud Run / containers	Servicios de dominio (clientes, catálogo, pricing, órdenes, fiscal, KB) y API Gateway. Stateless, autoescalables, latencia baja.	HU-01 a HU-10 (lado nuestro).
VMs (Compute Engine)	Procesos batch (factura global diaria/quincenal), workers de larga duración, posibles componentes legacy auditados.	HU-04 facturas globales, auditoría VB6.
Cloud Storage (Buckets)	Evidencia POD (firma + foto) inmutable, fotos de anaquel si Nilo nos las envía para auditoría, exports fiscales, audit trail crudo.	HU-06, HU-08 (opcional), retención 5 años.
Application Integration (GCP)	Orquestación interna entre servicios y reintentos con backoff. Es nuestro pegamento del lado GCP.	Orquestador del diagrama.
Cloud SQL / Firestore (probable)	Persistencia de estado nuestro (vínculo `clientes ↔ BSUID/teléfono` — ver HU-07, idempotency keys, ledger de pedidos para audit).	Transversal.
Secret Manager + IAM	Credenciales SAP, DispatchTrack, claves de firma de Nilo.	Transversal.
Cloud Logging + Monitoring	Observabilidad ALCOA+, alertas SLA <60 s, dashboards adopción/OTIF.	Transversal.

SAP BTP Integration Suite (iPaaS) — el puente al core

El principio Clean Core prohíbe meter código custom dentro de SAP. Todo va por BTP Integration Suite:

iFlows transforman JSON ↔ IDoc / BAPI.
SAP SD valida límite de crédito y stock en tiempo real al crear la orden.
SAP MDM es la verdad única para productos, clientes y precios por graduación; ECHO los lee desde aquí.

Decisión arquitectónica pendiente: el onboarding mencionó Application Integration (GCP) como pieza de orquestación. El PR/FAQ habla de SAP BTP Integration Suite. Coexisten, pero el reparto no está claro:

Hipótesis A: BTP solo para el último hop a SAP; Application Integration orquesta todo lo demás (Nilo, DispatchTrack, eventos internos).
Hipótesis B: BTP es el orquestador maestro; Application Integration solo para tareas locales GCP.

Esta decisión condiciona el diseño completo. Ver 06-pendientes.md #6.

Decisión Build vs Buy (Nilo)

El scorecard del PR/FAQ §4.1 favorece Nilo Commerce Suite sobre Salesforce CG Cloud y VTEX B2B:

Criterio	Nilo	Salesforce	VTEX
Especialización VaB	Alta (POS móvil nativo)	Media	Baja
Integración SAP	Conectores probados	MuleSoft (costo alto)	Vía middleware
Offline mode	Nativo y robusto	Parcial	Limitado
Time-to-Market	8–12 semanas	12–16 semanas	10–14 semanas

Para nosotros como dev esto significa: menos código custom en la capa frontal, pero más enfoque en la calidad del contrato API que exponemos a Nilo y en la integración limpia con SAP. Si la frontera se mueve (ej. Nilo no entrega la PWA), nuestra carga sube — por eso es pendiente alto.

Repositorios

GitLab y GitHub existen en paralelo (mencionado en onboarding). Convención por confirmar (06-pendientes.md #7). Posibles divisiones:
- GitLab para integraciones SAP/BTP (alineado con prácticas SAP corporativas).
- GitHub para servicios GCP/API públicas (alineado con stack moderno).
El repo del backend/integración probablemente vive en uno de los dos — verificar al primer push.

Arquitectura ​

Frontera Nilo ↔ nosotros (vista lógica) ​

El "Camino del Dato" (storyboard ALCOA+) ​

Mapeo a la infraestructura GCP del onboarding ​

SAP BTP Integration Suite (iPaaS) — el puente al core ​

Decisión Build vs Buy (Nilo) ​

Repositorios ​