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

```txt
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](/docs/fundamentos/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.

> [!WARNING]
> Não mantenha scripts executáveis de teste nos diretórios autocarregados, e não importe arquivos fora de `backend/` (como `../../docs/...`): eles não existem na imagem publicada. Veja [Empacotamento](/docs/operacao/empacotamento).

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

Fonte: https://sdk.oonapps.com/docs/introducao/estrutura-do-projeto