Naming conventions¶

Recursos AWS¶

Prefijo obligatorio: zen-{env}-{servicio-o-recurso}. Donde env ∈ {dev, qa, prod}. Account: 450972188274. Región principal: us-east-2. ACM y WAF (CloudFront): us-east-1.

Recurso	Pattern	Ejemplo
Lambda function	`zen-{env}-{servicio}`	`zen-dev-tenant-mgmt`
Lambda function variant	`zen-{env}-{servicio}-{variant}`	`zen-dev-inbound-router-webchat`
API Gateway HTTP API	`zen-{env}-{servicio}-api`	`zen-dev-tenant-mgmt-api`
ECR repository	`zen-{env}-{servicio}`	`zen-dev-flow-engine`
DynamoDB table	`zen-{env}-{nombre-lógico}`	`zen-dev-tenants`, `zen-dev-flow-state`, `zen-dev-dedup`
S3 bucket general	`zen-{env}-{nombre}-{account_id}`	`zen-dev-flows-450972188274`
S3 bucket CDN	`zen-{env}-{name}-cdn-{account_id}`	`zen-dev-widget-cdn-450972188274`
S3 bucket CDN logs	`zen-{env}-{name}-cdn-logs-{account_id}`	`zen-dev-widget-cdn-logs-450972188274`
SQS queue	`zen-{env}-{servicio}-{propósito}`	`zen-dev-flow-engine-msg-received`
SQS DLQ	`zen-{env}-{servicio}-{propósito}-dlq`	`zen-dev-flow-engine-msg-received-dlq`
EventBridge bus	`zen-{env}-domain-events`	(único por env)
EventBridge rule	`zen-{env}-{source}-to-{target}`	`zen-dev-message-received-to-flow-engine`
KMS key alias	`alias/zen-{env}-platform`	(único por env)
Secrets Manager	`/zen/{env}/{categoría}/{recurso}`	`/zen/dev/connectors/360dialog/example`
IAM role	`zen-{env}-{servicio}-role`	`zen-dev-inbound-router-role`
CloudWatch log group	`/aws/lambda/zen-{env}-{servicio}`	`/aws/lambda/zen-dev-flow-engine`

Tags obligatorios¶

Todo recurso debe tener (vía default_tags del provider AWS + tags en el recurso):

tags = {
  Project            = "zengine-v2"
  Environment        = var.env
  ManagedBy          = "terraform"
  Service            = "..."  # nombre del servicio o recurso lógico
}

Para multi-tenant físico (V1.2):

tags = {
  Tenant             = "physical-tenant-id"  # solo en recursos por-tenant
  Tier               = "physical"
  DataClassification = "internal" | "pii" | "confidential"
}

DynamoDB single-table¶

Pattern: pk (HASH) + sk (RANGE). GSIs según necesidad.

Tabla	pk pattern	sk pattern	Notas
`zen-dev-tenants`	`TENANT#{tenantId}`	`METADATA` (item raíz) o `CHANNEL#{channel}` (sub-items)	GSI `gsi-slug` con `slugKey`. Stream NEW_AND_OLD_IMAGES (outbox).
`zen-dev-flow-state`	`TENANT#{tenantId}#CONV#{conversationId}`	`STATE`	TTL en `expiresAt`.
`zen-dev-dedup`	`{provider}#{externalMessageId}`	`(none)`	TTL 7 días.

EventBridge detail types¶

Convención: {Aggregate}.{Event} (Pascal case). Schemas en packages/event-contracts/src/index.ts.

Detail type	Source	Producer
`Tenant.Created`	`ze.tenant-mgmt`	tenant-mgmt
`Tenant.Updated`	`ze.tenant-mgmt`	tenant-mgmt
`Conversation.MessageReceived`	`ze.inbound-router`	inbound-router
`Conversation.FlowStepCompleted`	`ze.flow-engine`	flow-engine
`Conversation.FlowCompleted`	`ze.flow-engine`	flow-engine
`Conversation.HandoffRequested`	`ze.flow-engine`	flow-engine
`Channel.OutboundRequested`	`ze.flow-engine`	flow-engine
`Channel.OutboundDispatched`	`ze.connectors-social`	connectors-social
`Channel.OutboundFailed`	`ze.connectors-social`	connectors-social
`Channel.AgentAssigned`	`ze.connectors-cc`	connectors-cc
`Survey.Started`	`ze.encuesta-service`	encuesta-service
`Survey.Completed`	`ze.encuesta-service`	encuesta-service

Identificadores en código¶

Step IDs (flow): kebab-case, regex ^[a-z][a-z0-9-]{0,63}$ (ej. greet-user, validate-input-2).
Flow IDs: mismo regex (ej. iplacex-rematricula).
Tenant IDs: lowercase, alfanuméricos + guiones (ej. iplacex-demo).
Conversation IDs: {channel}:{externalId} (ej. whatsapp:573176923588, webchat:visitor-001).
Correlation IDs: UUID v4.

Branches y commits Git¶

Branches: main (protected), feature feat/, bugfix fix/, chore chore/.
Commits: Conventional Commits (feat:, fix:, chore:, docs:, refactor:, test:, ci:).
Co-Authored-By cuando aplique.

Workspaces npm¶

Pattern: @zengine/{nombre}. Privados ("private": true). Tres categorías:

packages/*: libraries reutilizables (errors, eventing, flow-schema, etc.).
services/*: Lambdas (tenant-mgmt, flow-engine, etc.).
apps/*: SPAs (widget-spa, builder-spa).

Ver developers/repo-map.md y el archivo docs/REPO_MAP.md canónico.