> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Estrutura do projeto

> O que há dentro de um app Twenty criado com scaffold — arquivos, pastas e o que cada um faz.

Um novo app gerado por `npx create-twenty-app` se parece com isto:

```text filename="my-twenty-app/" theme={null}
my-twenty-app/
  package.json
  src/
    application-config.ts                   # Required — your app's entry point
    default-role.ts                         # Permissions for logic functions
    constants/
      universal-identifiers.ts              # Auto-generated UUIDs and metadata
    front-components/
      main-page.tsx                         # Welcome page component
    navigation-menu-items/
      main-page.navigation-menu-item.ts     # Sidebar entry for the welcome page
    page-layouts/
      main-page.page-layout.ts              # Standalone page hosting the component
    __tests__/
      application-config.test.ts            # Unit test
      global-setup.ts                       # Integration test setup (sync + uninstall)
      schema.integration-test.ts            # Integration test against a live server
  .github/workflows/
    ci.yml                                  # Lint, typecheck, unit + integration tests
    cd.yml                                  # Deploy + install on push to main
    publish.yml                             # Publish to npm on version tags (with provenance)
  public/
    logo.svg                                # Static assets
  vitest.config.ts                          # Integration test runner config
  vitest.unit.config.ts                     # Unit test runner config
  tsconfig.json, tsconfig.spec.json
  .nvmrc, .yarnrc.yml, .oxlintrc.json
  README.md, AGENTS.md, CLAUDE.md, CHANGELOG.md, SETUP.md
```

## Arquivos principais

| Arquivo / Pasta                                                            | Finalidade                                                                                                                          |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `src/application-config.ts`                                                | **Obrigatório.** O principal arquivo de configuração do seu aplicativo.                                                             |
| `src/default-role.ts`                                                      | Papel padrão que controla o que suas funções de lógica podem acessar.                                                               |
| `src/constants/universal-identifiers.ts`                                   | UUIDs gerados automaticamente e metadados (nome de exibição, descrição).                                                            |
| `src/front-components/`, `src/navigation-menu-items/`, `src/page-layouts/` | Uma página de boas-vindas inicial: um front component renderizado por um page layout autônomo, acessível a partir da barra lateral. |
| `src/__tests__/`                                                           | Um teste de unidade mais um teste de integração (com sua configuração global) que sincroniza o app com um servidor real.            |
| `public/`                                                                  | Recursos estáticos (imagens, fontes) servidos com seu aplicativo.                                                                   |
| `AGENTS.md` / `CLAUDE.md`                                                  | Orientação para agentes de codificação de IA que trabalham no app.                                                                  |
| `CHANGELOG.md` / `SETUP.md`                                                | Registro de alterações importantes e instruções de configuração para desenvolvimento local.                                         |

<Note>
  **A organização de arquivos fica a seu critério.** As pastas acima são convenções — o SDK detecta entidades por meio de análise de AST em chamadas a `export default defineEntity(...)`, independentemente de onde o arquivo esteja.
</Note>

## Dependências

Ambos os pacotes Twenty SDK pertencem a `devDependencies`, não a `dependencies`:

```json filename="package.json" theme={null}
{
  "dependencies": {},
  "devDependencies": {
    "twenty-client-sdk": "2.20.0",
    "twenty-sdk": "2.20.0",
    "twenty-ui": "1.0.0-alpha.1"
  }
}
```

O scaffolder fixa `twenty-sdk` e `twenty-client-sdk` para a sua própria versão — mantenha os dois sincronizados ao atualizar.

* **`twenty-sdk`** inclui a CLI `twenty` e as ferramentas de build/scaffolding. Ele é executado apenas durante o desenvolvimento e o build e nunca é importado pelo runtime do aplicativo publicado.
* **`twenty-client-sdk`** *é* importado pelo código do seu aplicativo (`CoreApiClient`, `MetadataApiClient`, `RestApiClient`), mas a Twenty o fornece em tempo de execução — as funções de lógica o obtêm de uma camada SDK gerada, e os componentes de front o resolvem a partir de módulos servidos pelo servidor. A cópia instalada é usada apenas para verificação de tipos e para o build no momento do deploy, então ela nunca precisa ser incluída no bundle implantado.

Manter qualquer um dos pacotes em `dependencies` o inclui no bundle de runtime do aplicativo instalado, onde ele é peso morto. `twenty dev:build` emite um aviso quando qualquer um deles ainda está listado em `dependencies`.

Adicione as dependências de runtime do próprio aplicativo (bibliotecas que as suas funções de lógica realmente importam em tempo de execução) em `dependencies`, como de costume.