twenty/packages/twenty-docs/developers/extend/apps/building.mdx

---
title: Architecture
description: How Twenty apps work — sandboxing, lifecycle, and the building blocks.
icon: "sitemap"
---

<Warning>
  Apps are currently in alpha. The feature works but is still evolving.
</Warning>

Twenty apps are TypeScript packages that extend your workspace with custom objects, logic, UI components, and AI capabilities. They run on the Twenty platform with full sandboxing and permission controls.

## How apps work

An app is a collection of **entities** declared using `defineEntity()` functions from the `twenty-sdk` package. The SDK detects these declarations via AST analysis at build time and produces a **manifest** — a complete description of what your app adds to a workspace.

```
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>
  **File organization is up to you.** Entity detection is AST-based — the SDK finds `export default defineEntity(...)` calls regardless of where the file lives. The folder structure above is a convention, not a requirement.
</Note>

## Entity types

| Entity | Purpose | Docs |
|--------|---------|------|
| **Application** | App identity, permissions, variables | [Data Model](/developers/extend/apps/data-model) |
| **Role** | Permission sets for objects and fields | [Data Model](/developers/extend/apps/data-model) |
| **Object** | Custom data tables with fields | [Data Model](/developers/extend/apps/data-model) |
| **Field** | Extend existing objects, define relations | [Data Model](/developers/extend/apps/data-model) |
| **Logic Function** | Server-side TypeScript with triggers | [Logic Functions](/developers/extend/apps/logic-functions) |
| **Front Component** | Sandboxed React UI in Twenty's page | [Front Components](/developers/extend/apps/front-components) |
| **Skill** | Reusable AI agent instructions | [Skills & Agents](/developers/extend/apps/skills-and-agents) |
| **Agent** | AI assistants with custom prompts | [Skills & Agents](/developers/extend/apps/skills-and-agents) |
| **View** | Pre-configured record list views | [Layout](/developers/extend/apps/layout) |
| **Navigation Menu Item** | Custom sidebar entries | [Layout](/developers/extend/apps/layout) |
| **Page Layout** | Custom record page tabs and widgets | [Layout](/developers/extend/apps/layout) |

## Sandboxing

- **Logic functions** run in isolated Node.js processes on the server. They only access data through the typed API client, scoped to the app's role permissions.
- **Front components** run in Web Workers using Remote DOM — sandboxed from the main page but rendering native DOM elements (not iframes). They communicate with Twenty via a message-passing host API.
- **Permissions** are enforced at the API level. The runtime token (`TWENTY_APP_ACCESS_TOKEN`) is derived from the role defined in `defineApplication()`.

## App lifecycle

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

- **`yarn twenty dev`** — watches your source files and live-syncs changes to a connected Twenty server. The typed API client is regenerated automatically when the schema changes.
- **`yarn twenty build`** — compiles TypeScript, bundles logic functions and front components with esbuild, and produces a manifest.
- **Pre/post-install hooks** — optional logic functions that run during installation. See [Logic Functions](/developers/extend/apps/logic-functions) for details.

## Next steps

<CardGroup cols={2}>
  <Card title="Data Model" icon="database" href="/developers/extend/apps/data-model">
    Define objects, fields, roles, and relations.
  </Card>
  <Card title="Logic Functions" icon="bolt" href="/developers/extend/apps/logic-functions">
    Server-side functions with HTTP, cron, and event triggers.
  </Card>
  <Card title="Front Components" icon="window-maximize" href="/developers/extend/apps/front-components">
    Sandboxed React components inside Twenty's UI.
  </Card>
  <Card title="Layout" icon="table-columns" href="/developers/extend/apps/layout">
    Views, navigation items, and record page layouts.
  </Card>
  <Card title="Skills & Agents" icon="robot" href="/developers/extend/apps/skills-and-agents">
    AI skills and agents with custom prompts.
  </Card>
  <Card title="CLI & Testing" icon="terminal" href="/developers/extend/apps/cli-and-testing">
    CLI commands, testing, assets, remotes, and CI.
  </Card>
  <Card title="Publishing" icon="rocket" href="/developers/extend/apps/publishing">
    Deploy to a server or publish to the marketplace.
  </Card>
</CardGroup>