Setup local

Pre-requisitos

Tool	Versión	Notas
Node.js	24 LTS	Ver .nvmrc. nvm use para alinear.
npm	10+	Bundled con Node 24.
Terraform	≥ 1.9	Sólo si tocas IaC.
Docker	≥ 25	Para LocalStack y para builds de Lambda.
AWS CLI	v2	Para inspeccionar recursos.
Python	3.11+	Sólo para construir docs (mkdocs).

Clonar y bootstrap

git clone git@github.com:zerviz/zengine-platform.git
cd zengine-platform
nvm use
npm ci --no-audit --no-fund

Comandos raíz (workspaces npm)

npm run typecheck         # tsc --noEmit en todos los packages/services
npm run lint              # eslint flat config (placeholder en Fase 2 dev)
npm run test:unit         # Jest unit tests (400 tests verdes)
npm run test:integration  # requiere LocalStack en :4566
npm run test:parity --workspace=@zengine/flow-engine
npm run build             # tsc + esbuild de todos los services

Levantar LocalStack

docker run --rm -d --name localstack \
  -p 4566:4566 \
  -e SERVICES=dynamodb,s3,sqs,events,secretsmanager,ssm,iam,kms,sts \
  -e DEFAULT_REGION=us-east-2 \
  -e EAGER_SERVICE_LOADING=1 \
  localstack/localstack:3.8

bash scripts/localstack-init.sh

localstack-init.sh crea las tablas DDB, el bus EventBridge, secrets mock y SQS necesarios para los integration tests.

Correr el Admin SPA local

npm run dev --workspace=@zengine/admin

Levanta Vite en http://localhost:5173. El SPA lee public/config.js para apuntar a APIs y Cognito; por defecto apunta a dev. Para usar LocalStack o un endpoint custom, edita apps/admin/public/config.js:

window.ZEN_CONFIG = {
  apiTenantMgmt: 'http://localhost:4566/...',
  cognitoDomain: 'https://zen-dev-auth.auth.us-east-2.amazoncognito.com',
  cognitoClientId: '4mr4vrvcvklm81m8gp2mb2eb72',
  redirectUri: 'http://localhost:5173/callback'
};

No commitees config.js con valores locales: hay un override en config.local.js ignorado por git para esto.

Correr el widget local

npm run dev --workspace=@zengine/widget

Sirve dev/index.html con el widget en hot-reload. Apunta por defecto al inbound-router de dev.

Estructura de un servicio

services/<name>/
  src/
    handler.ts          # AWS Lambda handler (1 por servicio)
    domain/             # Lógica pura, sin AWS SDK
    infrastructure/     # Adapters: DDB, EB, secrets
    application/        # Use cases / orchestrators
  tests/
    unit/               # Jest
    integration/        # Jest + LocalStack
  Dockerfile            # node:24-alpine ARM64
  package.json

Convención de commits

Conventional commits (feat:, fix:, chore:, docs:, refactor:, test:). Pre-commit hooks via husky corren lint-staged + typecheck.