Mapa del repositorio¶

El mapa canónico vive en docs/REPO_MAP.md. Esta página lo incluye sin duplicar.

REPO_MAP — ZEngine Platform (target monorepo)¶

Estado: propuesto en Fase 1 (docs/adr/0006-iac-cicd.md). Repo único: zerviz/zengine-platform (organización por confirmar). Branching: trunk-based con envs dev | qa | prod orquestados desde infra/envs/<env>/.

zengine-platform/
├── CLAUDE.md                          # Reglas de la plataforma (ya en este repo)
├── CLAUDE_PLAYBOOK.md                 # Playbook (ya en este repo)
├── .claude/
│   ├── agents/                        # Subagentes especializados
│   ├── commands/                      # Slash commands
│   └── settings.json
├── docs/
│   ├── adr/                           # ADRs MADR numerados (0001..)
│   ├── diagrams/                      # C4 (Mermaid) y export PNG
│   ├── compliance/                    # iso27001-mapping.md
│   ├── runbooks/                      # Operación / incident response
│   └── discovery/                     # Output de Fase 0 (read-only history)
│
├── infra/
│   ├── modules/                       # Módulos Terraform reutilizables
│   │   ├── lambda-service/            # Patrón Lambda + APIGW + role + log-group
│   │   ├── eventing/                  # EventBridge bus + SNS topic + SQS+DLQ
│   │   ├── persistence-postgres/      # RDS Postgres + secret + RLS bootstrap
│   │   ├── persistence-dynamodb/      # DDB on-demand + GSIs estándar
│   │   ├── tenant-account/            # Bootstrap cuenta tenant físico (cross-account roles)
│   │   ├── observability/             # CloudWatch dashboards, alarms, X-Ray sampling
│   │   ├── waf-cloudfront/            # WebACL estándar
│   │   └── kms-tenant-key/            # CMK por tenant + alias `alias/ze/<tenant>`
│   ├── envs/
│   │   ├── dev/                       # Cuenta `ze-dev` (única). Single-AZ, sin HA.
│   │   ├── qa/                        # Cuenta `ze-qa`. Multi-AZ.
│   │   └── prod/                      # Cuenta `ze-prod` + control-plane.
│   ├── global/                        # IAM, KMS, OIDC para GitHub Actions, Route53
│   └── tenants/                       # Stacks dedicados por tenant enterprise (físico)
│       └── _template/                 # Plantilla aplicada con var `tenant_id`
│
├── services/
│   ├── _template/                     # Scaffold para nuevos servicios (slash command lo copia)
│   ├── tenant-mgmt/                   # Control plane: catálogo de tenants, billing, registry
│   ├── auth-bff/                      # Cognito federation + token exchange + tenant-context
│   ├── inbound-router/                # Webhook receiver (Meta/360/Five9), firma + dedup
│   ├── flow-engine/                   # FSM + step executors + persistencia de estado
│   ├── connector-orchestrator/        # Strategy dispatch, circuit breaker, retry
│   ├── connectors-social/             # Strategies: WhatsApp Cloud, 360dialog, Messenger, Instagram, Email
│   ├── connectors-cc/                 # Strategies: Five9 (V1), Genesys, Amazon Connect (futuras)
│   ├── outbound-dispatcher/           # Campañas + templates + Saga (Step Functions Express)
│   ├── reporting-api/                 # Queries sobre RDS histórico
│   └── encuesta-service/              # NPS FSM post-conversación
│
├── packages/                          # Workspaces npm
│   ├── tenant-context/                # Resolver tenant_id desde JWT/event, propagar
│   ├── observability/                 # Powertools wrappers (logger, tracer, metrics)
│   ├── errors/                        # BaseError + jerarquía (DomainError, IntegrationError, etc.)
│   ├── connector-sdk/                 # Strategy Pattern base + tests de contrato
│   ├── eventing/                      # Publishers EventBridge + SNS + outbox pattern helpers
│   ├── auth-utils/                    # Validación JWT Cognito, claim `custom:tenant_id`
│   └── flow-schema/                   # Zod schemas del catálogo de flows
│
├── apps/
│   ├── builder-spa/                   # SPA platform-ops (Vite + React 18, sucesor de BuilderHub.jsx)
│   ├── customer-spa/                  # SPA tenant-admin servida en {tenant-slug}.app.{env}.zen.zervizdev.com
│   └── widget-spa/                    # Widget de chat embebible (sucesor de src/widget)
│
├── tests/
│   ├── contract/                      # Pact (productor ↔ consumidor)
│   ├── e2e/                           # Playwright (golden paths IPLACEX fixture)
│   ├── load/                          # k6 (10k msg/día smoke)
│   └── parity/                        # Fixture-based parity vs legacy (cutover gate)
│
├── fixtures/
│   ├── tenants/iplacex-demo/          # Datos de prueba IPLACEX (no cliente real)
│   ├── tenants/zerviz-internal/       # Datos del tenant interno
│   └── flows/                         # Catálogos de flow para tests
│
└── .github/
    └── workflows/
        ├── ci.yml                     # Lint + test + tfsec + checkov + semgrep en cada PR
        ├── cd-dev.yml                 # Deploy auto a dev en merge a main
        ├── cd-qa.yml                  # Deploy a qa con aprobación + smoke tests
        ├── cd-prod.yml                # Deploy a prod con aprobación + canary
        ├── tenant-onboard.yml         # Aprovisionamiento de tenant enterprise
        └── parity-gate.yml            # Bloquea cutover si parity tests fallan

Servicios V1 (9)¶

Bounded contexts decididos en Fase 1. Cada uno es un microservicio independiente con su propia carpeta services/<name>/{handler,domain,infrastructure,tests} (hexagonal).

#	Servicio	Responsabilidad	Persistencia primaria	Eventos publicados
1	`tenant-mgmt`	CRUD tenants, registry de strategies, feature flags	DDB `ze-tenants`, RDS `ze_control_plane`	`TenantCreated`, `TenantSuspended`
2	`auth-bff`	Cognito hosted UI, token exchange, refresh	(sin estado propio)	`UserAuthenticated`
3	`inbound-router`	Recibe webhooks Meta/360/Five9, valida firma, normaliza, dedup, fan-out	DDB `ze-dedup` (TTL 24h)	`MessageReceived`
4	`flow-engine`	FSM por conversación, evalúa pasos, integra con connectors	DDB `ze-flow-state` (PK `TENANT#<id>#CONV#<id>`)	`FlowStepCompleted`, `FlowCompleted`
5	`connector-orchestrator`	Strategy dispatch a conectores, circuit breaker, retry	(SSM Parameter Store para CB)	`OutboundDispatched`, `OutboundFailed`
6	`connectors-social`	Strategies WhatsApp/360/Messenger/Instagram/Email	(sin estado, secrets en SM)	`MessageDelivered`
7	`connectors-cc`	Strategy Five9 (V1)	DDB `ze-five9-sessions` (TTL 1h, ex `chat-widget-auth-sessions`)	`AgentAssigned`, `ConversationClosed`
8	`outbound-dispatcher`	Campañas masivas con Saga (SFN Express)	RDS `ze_app.campaigns`, DDB `ze-outbound-runs`	`CampaignStarted`, `CampaignCompleted`
9	`reporting-api`	Queries de históricos para SPA admin	RDS `ze_app` (read-only role)	(consumidor de eventos para materializar read-models)
(extra)	`encuesta-service`	NPS FSM post-conversación	DDB `ze-encuesta-state`	`SurveyCompleted`

10 servicios contando encuesta-service. Cabe en el rango "6-10" del playbook §1.3.

Decisiones cruzadas¶

Naming AWS: prefijo ze- (consistente con cuenta legacy). Sufijo de env: ze-{env}-<resource>.
Tags obligatorios: Project=zengine, Environment={dev|qa|prod}, Tenant=<id>|shared|control-plane, Service=<bounded-context>, CostCenter=<>, DataClassification={public|internal|confidential}, ManagedBy=terraform.
Capa SPA: apps/builder-spa y apps/widget-spa se sirven desde S3 split (ze-{env}-spa) detrás de CloudFront con OAC + custom domain + WAF.
Cero código en apps/ depende del legacy: greenfield total, decisión asentada en docs/discovery/00-phase1-prerequisites.md §0.

Fuentes¶

Decisiones del checklist docs/discovery/00-phase1-prerequisites.md (aprobado 2026-04-30) + Anexo de aclaraciones.
Playbook §1.3 (estructura target) y §6 (subagentes).
Lab golden path → docs/discovery/07-lab-golden-path.md.