# Arquitetura

> Como a Central, o oon-core-back, o oon-core-front e a Plataforma Oon dividem responsabilidades — e por que a fonte de verdade é sempre o backend.

## Separação de responsabilidades

```txt
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

```txt
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

1. `central.domain.json` ou `defineModel` registra model, campos, CRUD, permissões e metadata.
2. O backend expõe `/core/metadata`, `/core/models` e o router CRUD do `basePath`.
3. Escopo de tenant/usuário, validação, fórmulas, referências, auditoria e triggers são aplicados no servidor.
4. O objeto code-first do App compõe coleções, formulários, filtros, relações, esteiras, documentos e dashboards.
5. 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](/docs/fundamentos/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 |

> [!DANGER]
> Não importe caminhos internos dos pacotes nem copie código de outros Apps como base. A conformance reprova imports de subpaths não públicos do `oon-core-front`.

## 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.

Fonte: https://sdk.oonapps.com/docs/introducao/arquitetura