upstream-twenty/packages/twenty-docs/l/pt/developers/extend/apps/getting-started/concepts.mdx

---
title: Conceitos
description: Como as aplicações Twenty funcionam — modelo de entidade, sandboxing e ciclo de vida da instalação.
icon: sitemap
---

As aplicações Twenty são pacotes TypeScript que estendem seu espaço de trabalho com objetos personalizados, lógica, componentes de UI e recursos de IA. Elas são executadas na plataforma Twenty com sandboxing completo e controles de permissão.

## Como as aplicações funcionam

Uma aplicação é uma coleção de **entidades** declaradas usando funções `defineEntity()` do pacote `twenty-sdk`. O SDK detecta essas declarações via análise de AST no momento da compilação e produz um **manifesto** — uma descrição completa do que seu aplicativo adiciona a um espaço de trabalho. Essas funções validam sua configuração em tempo de compilação e oferecem autocompletar na IDE e segurança de tipos.

```
your-app/
├── src/
│   ├── application-config.ts    ← defineApplication (required, one per app)
│   ├── roles/                   ← defineRole
│   ├── objects/                 ← defineObject
│   ├── fields/                  ← defineField
│   ├── logic-functions/         ← defineLogicFunction
│   ├── front-components/        ← defineFrontComponent
│   ├── skills/                  ← defineSkill
│   ├── agents/                  ← defineAgent
│   ├── views/                   ← defineView
│   ├── navigation-menu-items/   ← defineNavigationMenuItem
│   └── page-layouts/            ← definePageLayout
├── public/                      ← Static assets (images, icons)
└── package.json
```

<Note>
  **A organização de arquivos fica a seu critério.** A detecção de entidades é baseada em AST — o SDK encontra chamadas a `export default defineEntity(...)` independentemente de onde o arquivo esteja. A estrutura de pastas acima é uma convenção, não um requisito.
</Note>

## Tipos de entidade

| Entidade                        | Finalidade                                                                                    | Documentação                                                                                                                |
| ------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Aplicação**                   | Identidade da aplicação, função padrão, variáveis                                             | [Configuração da aplicação](/l/pt/developers/extend/apps/config/application)                                                     |
| **Papel**                       | Conjuntos de permissões para objetos e campos                                                 | [Papéis e permissões](/l/pt/developers/extend/apps/config/roles)                                                                 |
| **Objeto**                      | Tipos de registro personalizados com campos                                                   | [Objetos](/l/pt/developers/extend/apps/data/objects)                                                                             |
| **Campo**                       | Adicionar campos a objetos de outros apps                                                     | [Extensão de objetos](/l/pt/developers/extend/apps/data/extending-objects)                                                       |
| **Relação**                     | Links bidirecionais entre objetos                                                             | [Relações](/l/pt/developers/extend/apps/data/relations)                                                                          |
| **Função lógica**               | TypeScript no lado do servidor com gatilhos                                                   | [Funções lógicas](/l/pt/developers/extend/apps/logic/logic-functions)                                                            |
| **Habilidade**                  | Instruções reutilizáveis para agentes de IA                                                   | [Habilidades e Agentes](/l/pt/developers/extend/apps/logic/skills-and-agents)                                                    |
| **Agente**                      | Assistentes de IA com prompts personalizados                                                  | [Habilidades e Agentes](/l/pt/developers/extend/apps/logic/skills-and-agents)                                                    |
| **Provedor de conexão**         | Credenciais OAuth para APIs de terceiros                                                      | [Conexões](/l/pt/developers/extend/apps/logic/connections)                                                                       |
| **Vista**                       | Vistas de lista de registros pré-configuradas                                                 | [Vistas](/l/pt/developers/extend/apps/layout/views)                                                                              |
| **Item do menu de navegação**   | Entradas personalizadas na barra lateral                                                      | [Itens do menu de navegação](/l/pt/developers/extend/apps/layout/navigation-menu-items)                                          |
| **Layout da Página**            | Abas e widgets na página de detalhes de um registro                                           | [Layouts de página](/l/pt/developers/extend/apps/layout/page-layouts)                                                            |
| **Componente de front-end**     | UI React em sandbox dentro do Twenty                                                          | [Componentes de front-end](/l/pt/developers/extend/apps/layout/front-components)                                                 |
| **Dependências compartilhadas** | Dependências compartilhadas pelos componentes de front-end do app, declaradas em package.json | [Dependências compartilhadas](/l/pt/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components) |
| **Item do menu de comandos**    | Ações rápidas e entradas Cmd+K                                                                | [Itens do menu de comandos](/l/pt/developers/extend/apps/layout/command-menu-items)                                              |

## Sandboxing

* **Funções lógicas** são executadas em processos Node.js isolados no servidor. Eles acessam dados apenas por meio do cliente de API tipado, que atua como a pessoa que disparou a execução ou como o próprio app. Consulte [Qual acesso uma chamada usa](/l/pt/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).
* **Componentes de front-end** executam em Web Workers usando Remote DOM — isolados da página principal, mas renderizando elementos DOM nativos (não iframes). Eles se comunicam com o Twenty por meio de uma API de host com passagem de mensagens.
* **Permissões** são aplicadas no nível da API. Dois tokens de runtime são inseridos, ambos derivados da função declarada com `defineApplicationRole()`; o padrão é ainda mais limitado ao que a pessoa que disparou a execução pode fazer quando há alguém por trás da execução.

## Ciclo de vida do aplicativo

```
┌─────────────────────────────────────────────────────────┐
│ Development                                             │
│   npx create-twenty-app → yarn twenty dev (live sync)   │
├─────────────────────────────────────────────────────────┤
│ Build & Deploy                                          │
│   yarn twenty dev:build → yarn twenty app:publish        │
├─────────────────────────────────────────────────────────┤
│ Install flow                                            │
│   upload → [pre-install] → metadata migration →         │
│   generate SDK → [post-install] → … → [uninstall]       │
├─────────────────────────────────────────────────────────┤
│ Publish                                                 │
│   npm publish → appears in Twenty marketplace           │
└─────────────────────────────────────────────────────────┘
```

* **`yarn twenty dev`** — observa seus arquivos-fonte e sincroniza ao vivo as alterações com um servidor Twenty conectado. O cliente de API tipado é regenerado automaticamente quando o esquema muda.
* **`yarn twenty dev:build`** — compila TypeScript, empacota funções de lógica e componentes de front-end com o esbuild e produz um manifesto.
* **Hooks de pré/pós-instalação e desinstalação** — funções opcionais que são executadas durante a instalação ou logo antes da remoção. Veja [Hooks de instalação](/l/pt/developers/extend/apps/config/install-hooks) para detalhes.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Configuração" icon="screwdriver-wrench" href="/l/pt/developers/extend/apps/config/overview">
    Identidade da aplicação, função padrão e hooks de instalação e desinstalação.
  </Card>
  <Card title="Dados" icon="database" href="/l/pt/developers/extend/apps/data/overview">
    Objetos, campos e relações bidirecionais.
  </Card>
  <Card title="Lógica" icon="bolt" href="/l/pt/developers/extend/apps/logic/overview">
    Funções lógicas, habilidades, agentes e conexões OAuth.
  </Card>
  <Card title="Layout" icon="table-columns" href="/l/pt/developers/extend/apps/layout/overview">
    Vistas, navegação, layouts de página, componentes de front-end.
  </Card>
  <Card title="Operações" icon="rocket" href="/l/pt/developers/extend/apps/operations/overview">
    CLI, testes, remotos, CI e publicação do seu aplicativo.
  </Card>
</CardGroup>