Glosario

Términos del dominio ZEngine en orden alfabético.

A

ADR (Architecture Decision Record). Documento canónico de una decisión arquitectural. Formato MADR. Carpeta docs/adr/NNNN-titulo.md.

Amazon Connect Chat. Servicio AWS de contact center. ZEngine lo integra como target de handoff via strategy amazon-connect (ADR-0007 + 0014).

ARN (Amazon Resource Name). Identificador único de recurso AWS. Format: arn:aws:{service}:{region}:{account}:{resource}.

B

BSP (Business Solution Provider). Proveedor autorizado por Meta para enviar mensajes WhatsApp Business. Ejemplos en uso: Meta Cloud API directo, 360dialog.

Bulkhead. Patrón de aislamiento de recursos. En ZEngine se materializa como SQS dedicada por consumer, evitando que la saturación de un consumer afecte a otros (ADR-0009 §resiliencia).

C

C4 model. Modelo de diagramas arquitecturales (Context, Containers, Components, Code). Diagramas en docs/diagrams/.

Cognito hosted UI. UI de login pre-construida por AWS Cognito. ZEngine la usa para PKCE+code flow del admin SPA.

Connector. Adaptador hacia un proveedor externo (WhatsApp BSP, SES, SNS, etc.). Cada connector implementa una strategy.

conversationId. Identificador único de conversación. Format: {channel}:{externalId} (ej. whatsapp:573176923588). Sticky por canal+usuario.

D

Dedup table. DDB que evita procesar el mismo externalMessageId dos veces (idempotencia inbound). Key {provider}#{externalMessageId} con TTL 7 días.

DDB Streams. Captura de cambios en tabla DynamoDB. ZEngine lo usa para outbox pattern: event-publisher Lambda lee streams de tenants y publica eventos a EventBridge.

E

Encuesta (Survey). Encuesta NPS post-conversación. Servicio encuesta-service.

EventBridge bus. Bus único zen-{env}-domain-events. Todos los eventos de dominio pasan por aquí.

F

FSM (Finite State Machine). El flow-engine ejecuta cada conversación como una FSM: cada step es una transición y el state se persiste en zen-dev-flow-state.

Flow. Grafo dirigido de steps que define el flujo conversacional de un tenant para un canal. Almacenado en S3 (s3://zen-dev-flows-{account}/flows/{tenantId}/{channel}/active.json).

H

Handoff. Transferencia de conversación de bot a agente humano (Five9, Amazon Connect). Step type handoff en flow-engine + strategy en connectors-cc.

HMAC SHA256. Verificación de firmas de webhooks inbound (Meta, 360dialog). Header típico: X-Hub-Signature-256.

I

Idempotency. Procesar la misma operación N veces produce el mismo resultado. ZEngine usa: - externalMessageId + dedup table (inbound). - idempotencyKey en payload outbound (provider-side). - If-Match: <version> optimistic concurrency (tenant-mgmt PATCH). - ConditionExpression: attribute_exists(pk) DDB.

J

JWT. Token Cognito (id_token, access_token). Vida útil: id/access 60 min, refresh 30 días (ADR-0005).

K

KMS CMK. Customer Managed Key. ZEngine usa una sola CMK por env (alias/zen-dev-platform) para SSE de DDB, S3, Secrets Manager y CloudWatch Logs.

L

Lambda Powertools. Suite oficial de utilidades AWS Lambda (logger JSON, tracer X-Ray, metrics). Usado en todos los servicios.

LocalStack. Emulador local de AWS para tests de integración. Service localstack/localstack:3.8 con services DDB+S3+SQS+EB+Secrets+SSM+IAM+KMS+STS.

M

Multi-tenant logical. Un solo conjunto de recursos compartido por todos los tenants. Tier por defecto.

Multi-tenant physical. Recursos dedicados por tenant (DDB partition, KMS key, etc.). Tier opt-in para clientes con compliance estricto.

O

OAC (Origin Access Control). Nuevo mecanismo de CloudFront para acceder a S3 (reemplaza OAI legacy). Usa SigV4 con condition AWS:SourceArn.

OIDC (OpenID Connect). Federación de auth para GitHub Actions → AWS. ZEngine usa rol zen-dev-github-deployer asumido vía OIDC desde workflows.

Outbox pattern. Transaccionalidad eventual entre cambios DDB y publicación de eventos. Persiste evento como atributo _outbox en el item DDB. event-publisher lee el stream, publica el evento y elimina el campo _outbox. ADR-0009.

P

Parity gate. Suite que valida que el flow-engine v2 produce los mismos outputs canónicos que el flow builder legacy. 21 flows transpilados × 65 fixtures input→expected. ADR-0012.

PKCE (Proof Key for Code Exchange). Extensión OAuth2 que SPA pueden usar sin client secret. Admin SPA + Cognito hosted UI.

Powertools. Ver Lambda Powertools.

Projector. Lambda que consume EventBridge y proyecta a un read-model en DDB. reporting-api proyecta Channel.OutboundDispatched → campaign-stats.

R

Retry con jitter. Backoff exponencial con jitter ±20% para reintentos resilientes. packages/resilience (ADR-0009).

Runner self-hosted. GitHub Actions runner desplegado en infraestructura propia. ZEngine corre 3 runners en host Rexxar (Linux Mint 22.3) para evitar costos billing.

S

SES (Simple Email Service). Envío de email transaccional. Strategy email-ses (V1.1 #8).

SNS (Simple Notification Service). Envío de SMS directo. Strategy sms-sns (V1.1 #8).

SPA mode (CloudFront). Reescribe 403/404 → /index.html para soportar client-side routing. Flag del módulo cdn-static-site.

Step. Nodo del flow. Tipos en V1: text, condition, set-context, handoff, encuesta, http, llm.

Strategy pattern. Cada connector (canal/provider) implementa una interfaz uniforme (packages/connector-sdk). Mandatorio (ADR-0007).

strategyHint. Campo opcional en Channel.OutboundRequested que permite seleccionar una strategy específica cuando hay múltiples para el mismo canal (ej. meta-cloud vs 360dialog para WhatsApp). ADR-0014.

T

Tenant. Cuenta/cliente lógico del sistema. Identificado por tenantId.

Tier. Modo de aislamiento (logical | physical). Ver multi-tenant.

TTL (DDB). Time To Live. Items con atributo expiresAt (epoch seconds) se eliminan automáticamente.

V

Versioning (DDB). Campo version (int) en items mutables. Incremento atómico vía ConditionExpression: version = :expected. Endpoint PATCH requiere header If-Match.

W

WAF (Web Application Firewall). Capa AWS WAFv2 sobre CloudFront. Flag enable_waf en módulo CDN (off en dev, on en qa/prod).

Widget. Bundle distribuible @zengine/widget (Preact + Vite, 23 KB UMD). Embebible vía <script src="https://cdn.zen.zervizdev.com/widget.js">.

Z

ZEngine. Plataforma multi-tenant event-driven de conversational AI. Zerviz + Engine.