Saltar a contenido

Arquitectura general

ZEngine v2 es una plataforma multi-tenant event-driven sobre AWS, construida con Lambda (Node.js 24, ARM64, container image), API Gateway HTTP, EventBridge, SQS, DynamoDB, RDS PostgreSQL, Cognito y Secrets Manager. IaC con Terraform; CI/CD con GitHub Actions OIDC.

Las decisiones canónicas viven en los 14 ADRs.

C4 — Container

flowchart LR
    User[Visitante del sitio]
    Admin[Operador tenant]
    User -->|carga widget.js| CDN_W[CloudFront
cdn.zen.zervizdev.com]
    Admin -->|navega| CDN_A[CloudFront
admin.dev.zen.zervizdev.com]
    Admin -->|PKCE| Cognito[(Cognito User Pool
zen-dev-app-users)]
    User -->|POST /v1/webchat/messages| APIGW_IB[API Gateway
inbound-router]
    APIGW_IB --> InRouter[Lambda
inbound-router]
    InRouter --> FlowEng[Lambda
flow-engine]
    FlowEng --> DDB_State[(DDB
zen-dev-flow-state)]
    FlowEng -->|emite| EB[(EventBridge
zen-dev-domain-events)]
    EB --> Orchestrator[Lambda
connector-orchestrator]
    Orchestrator --> CSocial[connectors-social]
    Orchestrator --> CCC[connectors-cc]
    Orchestrator --> OutDisp[outbound-dispatcher]
    EB --> Encuesta[encuesta-service]
    EB --> Reporting[reporting-api]
    EB --> EvPub[event-publisher]
    Admin -->|REST + JWT| APIGW_TM[API Gateway
tenant-mgmt]
    APIGW_TM --> TenMgmt[Lambda
tenant-mgmt]
    TenMgmt --> DDB_Ten[(DDB
zen-dev-tenants)]
    Admin -->|REST + JWT| APIGW_AB[API Gateway
auth-bff]
    APIGW_AB --> AuthBFF[Lambda
auth-bff]
    AuthBFF --> Cognito

Flujo end-to-end de un mensaje webchat

sequenceDiagram
    participant W as Widget
    participant IR as inbound-router
    participant FE as flow-engine
    participant DDB as DDB flow-state
    participant EB as EventBridge
    participant CO as connector-orchestrator
    participant S as Strategy webchat-http
    W->>IR: POST /v1/webchat/messages (x-tenant-id, x-idempotency-key)
    IR->>IR: valida tenant + dedup
    IR->>FE: invoke flow.handleMessage
    FE->>DDB: GetItem state (PK=TENANT##CONV#)
    FE->>FE: ejecuta step actual + transiciones
    FE->>DDB: PutItem nuevo estado (optimistic concurrency)
    FE->>EB: PutEvents (Conversation.MessageReceived, ...)
    FE-->>IR: replies[]
    IR-->>W: 200 con replies
    EB->>CO: regla → connector-orchestrator
    CO->>S: dispatch strategy
    S->>EB: emite Conversation.MessageDelivered

Tenancy

Híbrida: logical (la mayoría) con partición por tenantId en DDB y Postgres + RLS; physical disponible para tenants enterprise con stack dedicado. Ver ADR-0002.

Persistencia

  • DynamoDB on-demand para estado caliente: tenants, flow-state, dedup, five9-sessions, encuesta-state, outbound-runs.
  • RDS PostgreSQL para histórico y read-models reportables (control plane + por tenant cuando aplique).
  • KMS CMK alias/zen-dev-platform para encrypt at rest.

Detalle en ADR-0003.

Eventing

Bus único zen-dev-domain-events. Outbox pattern desde tenant-mgmt (transaccional DDB → relay → EB). Garantías at-least-once; consumidores idempotentes por event.id. Ver ADR-0004.

Seguridad

  • Cognito user pool por env. PKCE para SPAs, client_credentials para M2M.
  • Secrets Manager para todos los secretos; rotación automática habilitada donde el proveedor lo permite.
  • IaC scans bloqueantes desde qa/prod (tfsec, checkov). En dev, soft-fail por la deuda conocida documentada en CLAUDE.md.

Ver ADR-0005, ADR-0010 y ADR-0008.

Observabilidad

Powertools (logger, tracer, metrics) en todos los handlers. Logs JSON con tenant_id, correlation_id, service. X-Ray sampling configurable por env. CloudWatch dashboards por servicio.