Arquitetura · OonCore SDK

Separação de responsabilidades

Central
├── backend/   domínio, regras, validações, integrações e esteiras
└── frontend/  composição de telas, coleções, documentos e overrides

OonCore Back                    OonCore Front
├── boot Express                ├── shell React
├── Mongo/Mongoose              ├── providers
├── autenticação                ├── roteamento e guards
├── RBAC                        ├── menu
├── CRUD metadata-driven        ├── datagrid e formulários
├── auditoria                   ├── documentos e dashboards
├── triggers/hooks              ├── esteiras
└── APIs padrão                 └── SDK REST

Plataforma Oon
├── Central de Ativações (identidade, tenant, licença, grants)
├── Workspace (código, publicação)
└── Delivery (imagem, Kubernetes, ambientes Dev/HML/Produção)

Fonte de verdade

Dados e regras ficam no backend.
Metadata operacional é exposta pelo backend em /core/metadata e /core/models.
O frontend renderiza a experiência a partir da metadata — formulários, colunas e tipos vêm do servidor.
Permissões são decididas no backend. O frontend usa permissões somente para experiência.
Integrações são tratadas como rotas, serviços, mappings, triggers e esteiras de integração do App.

Fluxo de uma requisição

Navegador ──► /api/pessoas ──► Nginx (imagem) ──► backend /pessoas
                                                   │
                     auth ── verifica token/sessão no escopo do App
                     tenant ── resolve tenant e acesso → req.accessContext
                     rbac ── aplica requirePermission(crud.permissions.read)
                     crud ── filtro de escopo + paginação + busca
                     audit ── (mutações) ControleAlteracao

O proxy remove o prefixo /api: no backend a rota é /pessoas; no navegador, /api/pessoas. Com useOonApi e baseUrl: "/api", você chama http.get("/pessoas").

Camada	Exemplo da mesma operação
Registro no backend	`defineRoutes("/demo", …)` + `router.private.post("/saudacao", options, handler)`
Backend direto	`POST /demo/saudacao`
URL pública / proxy Vite	`POST /api/demo/saudacao`
`useOonApi` com baseUrl `/api`	`http.post("/demo/saudacao", body)`

Metadata ponta a ponta

central.domain.json ou defineModel registra model, campos, CRUD, permissões e metadata.
O backend expõe /core/metadata, /core/models e o router CRUD do basePath.
Escopo de tenant/usuário, validação, fórmulas, referências, auditoria e triggers são aplicados no servidor.
O objeto code-first do App compõe coleções, formulários, filtros, relações, esteiras, documentos e dashboards.
O frontend consulta a metadata e monta os componentes do Core.

Disponibilidade, tenancy e implantação

Três dimensões independentes descrevem um App:

Disponibilidade (system, common, self, licensed) — a finalidade.
Tenancy (none, single_tenant, multi_tenant) — o isolamento dos dados.
Implantação — derivada do tenancy: none → singleton, single_tenant → dedicated, multi_tenant → shared.

Detalhes e a matriz válida em Tipos de App e tenancy.

O que é contrato e o que não é

Estado	Exemplos
Público e estável	exports de `@oondemand/oon-core-back`, subpaths `ui`, `routing`, `theme`, `hooks`, `testing` do front, manifestos, CRUD/metadata, validações/fórmulas, processo, auditoria, PDF, e-mail, segredos
Interno	stores, transports, registries internos, worker de e-mail, jobs de recálculo, arquivos dentro de `dist/`
Proposta futura	execução durável genérica de integrações (outbox/inbox, retry), diagnóstico padronizado de integrações

Por que mini-monólitos

Cada Central começa pequena, coesa e isolada — um banco dedicado (em single_tenant), um deployment, um domínio. Quando algo se torna reutilizável ou crítico, evolui para conector, serviço compartilhado ou micro-serviço, sem reescrever a base.