Introdução
Visão Geral
Monorepo unificado contendo dois produtos verticais (CMS e Hub) sobre três bounded contexts cross-cutting (Platform, Tenant, User):
- CMS — Site builder automotivo com editor visual. Permite criar, editar e publicar sites multi-tenant com páginas customizáveis via editor drag-and-drop (React + Puck). Inclui gestão de templates, blocos, menus e media.
- Hub — Plataforma para integração bidirecional entre o CRM Hypergestor e sistemas externos (montadoras, ERPs, parceiros). Permite receber e enviar dados de forma automatizada (schedule, webhook, fila externa) ou manual, com rastreabilidade completa de cada item processado.
Os produtos compartilham três bounded contexts "de plataforma" que vivem no banco public:
- Platform — catálogo cross-tenant: marcas (
plt_brands), tipos de integração (plt_types), blocos (plt_blocks), catálogo de veículos (plt_catalogs), media de plataforma (plt_media). - Tenant — gestão dos tenants em si (
tnt_tenants). - User — autenticação (argon2 + sessions Redis) e usuários (
usr_users,usr_sessions).
O Admin Web (adm/web/) é uma UI casca que consome esses três BCs via API REST.
Princípios
- Modularidade: CMS e Hub compartilham infraestrutura (
@hg/core, banco, cache) mas são módulos independentes. Platform/Tenant/User são BCs de plataforma, consumidos pelos dois. - Multi-tenant: banco compartilhado com isolamento lógico via Row Level Security (RLS), com suporte a banco dedicado para tenants enterprise (campo
databaseJSONB emtnt_tenants). - Geração de código: YAMLs de domínio são fonte única de verdade — tipos, Zod schemas, dicionários, rotas, base action classes e clients tipados são gerados automaticamente.
- Action-oriented backend: toda rota é uma action declarada no YAML. Nomes canônicos (
fetch/findById/create/update/delete) recebem template CRUD; qualquer outro nome gera throw-stub que o concreto precisa sobrescrever.
Stack Tecnológica
| Camada | Tecnologia | Justificativa |
|---|---|---|
| Runtime | Node.js + TypeScript | Ecossistema unificado, async I/O, tipagem end-to-end |
| Framework HTTP | Fastify 5 | Alto desempenho, schema validation nativa, plugins |
| Banco de dados | PostgreSQL 16 | Particionamento nativo, RLS, jsonb, maturidade |
| Fila | BullMQ (Redis 7) | Parent/child jobs, retry/backoff, rate limiting, dashboard |
| Monorepo | Nx + pnpm workspaces | Dependency graph, affected builds, generators |
| Query builder | Kysely | Type-safe, suporte a SQL raw (particionamento, SET LOCAL, RLS) |
| Frontend | Angular 21 | Dashboard admin (CMS + Hub + Admin) |
| Editor visual | React 19 + Puck | Editor drag-and-drop embarcado via iframe (CMS) |
| SSR | React + Fastify | Server-side rendering de páginas publicadas (CMS) |
| Object storage | MinIO (S3) | Upload de media (imagens, vídeos, PDFs) para CMS |
| Auth | argon2 + Redis | Hashing de senhas + sessions com TTL |