Central de Gestão

Sistema modular para gestão de clientes, cobrança (PIX via ExpressPagamentos), infraestrutura (Proxmox + SSH) e automação estilo n8n. Backend em NestJS, frontend Nuxt 3, deploy com PM2 + bare metal.

Pré-requisitos

• Node.js >= 20.11
• pnpm >= 9 (corepack enable && corepack prepare pnpm@9.12.0 --activate)
• Docker + docker compose (apenas para infra de dev: Postgres, Redis, Evolution API)
• PM2 (npm i -g pm2) — apenas para ambiente de produção

Setup rápido (desenvolvimento)

cp .env.example .env
node scripts/generate-keys.mjs > .env.secrets   # inspecione e mescle em .env / /etc/cg/
pnpm install
pnpm infra:up
./install.sh         # gera chaves + aplica migrations + seed (1ª vez)
pnpm dev             # já dispara `ensure-db-ready` automaticamente antes

Migrations são aplicadas automaticamente em pnpm dev, pnpm start, pnpm pm2:start e ./setup.sh via hook predev/prestart que chama scripts/ensure-db-ready.mjs (idempotente — no-op se o schema já está em dia). Para pular em emergência, defina CG_SKIP_DB_READY=1.

Arquitetura

Cada serviço é um processo PM2 independente. Ver docs/adr/0001-monorepo-pnpm.md e docs/runbooks/phase1-ops.md.

Deploy em 1 porta pública (produção): apenas a 3001 precisa estar exposta — o próprio Nuxt Nitro proxia /api/** pro gateway e /ws/** pro ws-gateway. Sem nginx interno. Ver docs/runbooks/single-port-deploy.md.

Processo	Porta	Função
cg-gateway	3000	Edge HTTP público
cg-auth	3101	Auth, 2FA, RBAC
cg-clients	3102	Clientes, contatos, OTP
cg-billing	3103	Cobrança, webhooks
cg-ws-gateway	3200	WebSocket para tempo real
cg-frontend	3001	Nuxt 3
workers	—	BullMQ (notifications, billing)

Segurança

• Zero-trust frontend: validação sempre no backend.
• Credenciais cifradas com envelope AES-256-GCM (KEK + DEK por segredo).
• JWT RS256 access (5min) + refresh rotativo (30min) com detecção de reuso.
• TOTP 2FA obrigatório para admins.
• Auditoria imutável com hash-chain.

Ver SECURITY.md e docs/threat-model.md.