Docs › Introdução

Estrutura do projeto

O que cada arquivo e pasta da Central gerada faz, o que é seu e o que pertence ao Core.

O gerador cria apenas a base estrutural _base. Rotas, menus, páginas, componentes, layouts e temas pertencem ao código do App e funcionam da mesma forma para todos os valores de appKind.

minha-central/
├── AGENTS.md                 # (opcional) instruções do seu projeto para Agents — preservado
├── central.app.json          # manifesto do App: identidade, RBAC, capabilities, compatibilidade
├── oon.deploy.json           # contrato de publicação: runtime, componentes, health, recursos
├── package.json              # scripts: dev, check, ooncore:docs, ooncore:conformance
├── .github/workflows/
│   └── publish-dev.yml       # ponte para solicitar publicação em Dev
├── .ooncore/                 # cache da documentação do Core (gerado; não edite)
├── backend/
│   ├── central.config.js     # extensões exclusivamente de runtime
│   ├── central.domain.json   # (opcional) models, fórmulas e validações declarativas
│   ├── central.process.json  # (opcional) esteiras, bindings, invariantes
│   ├── .env.example
│   └── src/
│       ├── models/           # defineModel(...)            ← autocarregado
│       ├── validations/      # defineValidation(...)       ← autocarregado
│       ├── triggers/         # defineTrigger(...)          ← autocarregado
│       ├── routes/           # defineRoutes(...)           ← autocarregado
│       ├── pipelines/        # definePipeline(...)         ← autocarregado
│       ├── documents/        # defineDocument(...)         ← autocarregado
│       ├── hooks/            #                              ← autocarregado
│       ├── services/         # regras reutilizáveis (importadas)
│       ├── controllers/      # (importados)
│       ├── mappings/         # (importados)
│       └── collections/      # (importados)
└── frontend/
    ├── index.html
    ├── vite.config.ts        # 127.0.0.1:5173 + proxy /api → 127.0.0.1:4000
    ├── .env.example          # VITE_API_URL=/api
    └── src/
        ├── main.tsx          # startOonApp(app)
        ├── app/
        │   ├── app.tsx       # defineOonApp({...})
        │   ├── routes.tsx    # defineOonRoutes([...])
        │   ├── navigation.ts # defineOonNavigation([...])
        │   └── theme.ts      # createOonTheme({...})
        ├── pages/
        ├── components/
        ├── features/
        └── layouts/

Arquivos da raiz

Arquivo Dono Para que serve
central.app.json App Identidade (id, name, slug), tipo (appKind), arquitetura (tenancyModel, availability, accessMode, authorizationMode), módulos, capabilities, compatibilidade com o Core, ativação e RBAC. Veja Manifesto do App.
oon.deploy.json App Contrato lido pela publicação: appCode, runtime: "ooncore-node-react", componentes, resourceProfile, capabilities de infraestrutura (ex.: pdfRendering) e caminhos de health.
.ooncore/ Core Cópia versionada da documentação canônica do pacote instalado. Regenere com npm run ooncore:docs; nunca edite à mão.
AGENTS.md App Instruções próprias do projeto para IA. O gerador e o sync não sobrescrevem.

Scripts da raiz

Script O que faz
npm run dev Orquestrador local: backend em 127.0.0.1:4000, frontend em 127.0.0.1:5173, sessão local automática.
npm run check Executa o doctor (versões, lockfiles, manifestos, docs check e conformance).
npm run ooncore:docs Sincroniza .ooncore/ com a versão instalada.
npm run ooncore:docs:check Valida versão e hashes do cache de documentação.
npm run ooncore:conformance Verifica as fronteiras de segurança e de arquitetura do App.

Autocarregamento do backend

O bootstrap carrega, nesta ordem:

  1. central.config.js;
  2. central.domain.json e depois central.process.json;
  3. arquivos .js/.cjs recursivos de src/models, src/validations, src/triggers, src/routes, src/pipelines, src/documents e src/hooks.

Não é preciso exportar uma função de registro: basta executar defineModel, defineRoutes etc. no módulo carregado. Outros diretórios — src/services, src/assets — entram pelos require desses módulos; não são carregados só por existirem.

Onde colocar cada coisa

Necessidade Lugar
Nova entidade com CRUD backend/src/models/ ou backend/central.domain.json
Campo calculado / regra entre campos central.domain.json (computed, validations)
Etapas, bloqueios, agregações backend/central.process.json
Regra de negócio em JavaScript backend/src/validations/
Efeito antes/depois de salvar backend/src/triggers/
Endpoint de ação ou integração backend/src/routes/ + backend/src/services/
Nova permissão ou perfil central.app.json → rbac
Nova página frontend/src/pages/ + app/routes.tsx + app/navigation.ts
Identidade visual frontend/src/app/theme.ts