The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
---
title: Concepts
description: How Twenty apps work — entity model, sandboxing, and the install lifecycle.
---
import { PageBanner } from "/snippets/page-banner.mdx"
import { CardTitle } from "/snippets/card-title.mdx"
## How apps work
An app is a collection of **entities** declared using `defineEntity()` functions from the `twenty-sdk` package. The CLI detects these declarations via AST analysis at build time and produces a **manifest** — a complete description of what your app adds to a workspace. These functions validate your configuration at build time and provide IDE autocompletion and type safety.
```
your-app/
├── src/
│ ├── application-config.ts ← defineApplication (required, one per app)
│ ├── roles/ ← defineRole
│ ├── objects/ ← defineObject
│ ├── fields/ ← defineField
│ ├── validation-rules/ ← defineValidationRule
│ ├── logic-functions/ ← defineLogicFunction
│ ├── front-components/ ← defineFrontComponent
│ ├── skills/ ← defineSkill
│ ├── agents/ ← defineAgent
│ ├── mcp-servers/ ← defineMcpServer
│ ├── views/ ← defineView
│ ├── navigation-menu-items/ ← defineNavigationMenuItem
│ ├── settings-menu-items/ ← defineSettingsMenuItem
│ └── 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, default role, variables | [Application Config](/developers/extend/apps/config/application) |
| **Role** | Permission sets on objects and fields | [Roles & Permissions](/developers/extend/apps/config/roles) |
| **Object** | Custom record types with fields | [Objects](/developers/extend/apps/data/objects) |
| **Field** | Add fields to objects from other apps | [Extending Objects](/developers/extend/apps/data/extending-objects) |
| **Relation** | Bidirectional links between objects | [Relations](/developers/extend/apps/data/relations) |
| **Validation Rule** | Conditions a record must meet before it can be saved | [Validation Rules](/developers/extend/apps/data/validation-rules) |
| **Logic Function** | Server-side TypeScript with triggers | [Logic Functions](/developers/extend/apps/logic/logic-functions) |
| **Skill** | Reusable AI agent instructions | [Skills & Agents](/developers/extend/apps/logic/skills-and-agents) |
| **Agent** | AI assistants with custom prompts | [Skills & Agents](/developers/extend/apps/logic/skills-and-agents) |
| **Workflow** | Ready-made workflows with a trigger and steps | [Workflows](/developers/extend/apps/logic/workflows) |
| **Connection Provider** | OAuth or custom sign-in for third-party accounts | [Connections](/developers/extend/apps/logic/connections) |
| **Messaging Provider** | Sends replies from an app's message channels through a connection | [Messaging Channels](/developers/extend/apps/logic/messaging-channels#sending-replies) |
| **MCP Server** | External MCP server the workspace's AI can call | [Skills & Agents](/developers/extend/apps/logic/skills-and-agents) |
| **View** | Pre-configured record list views | [Views](/developers/extend/apps/layout/views) |
| **Navigation Menu Item** | Custom sidebar entries | [Navigation Menu Items](/developers/extend/apps/layout/navigation-menu-items) |
| **Page Layout** | Tabs and widgets on a record's detail page | [Page Layouts](/developers/extend/apps/layout/page-layouts) |
| **Front Component** | Sandboxed React UI inside Twenty | [Front Components](/developers/extend/apps/layout/front-components) |
| **Shared Dependencies** | Dependencies shared by the app's front components, declared in package.json | [Shared Dependencies](/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components) |
| **Command Menu Item** | Quick actions and Cmd+K entries | [Command Menu Items](/developers/extend/apps/layout/command-menu-items) |
| **Settings Menu Item** | Entries in the app's settings menu, each rendering a front component | [Settings Menu Items](/developers/extend/apps/layout/front-components#settings-menu-items) |
## Sandboxing
- **Logic functions** run in isolated Node.js processes on the server. They only access data through the typed API client, which acts either as the person who triggered the run or as the app itself. See [Whose access a call uses](/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).
- **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. Two runtime tokens are injected, both derived from the role declared with `defineApplicationRole()`; the default one is narrowed further to what the triggering person can do whenever someone is behind the run.
## App lifecycle
```
┌─────────────────────────────────────────────────────────┐
│ Development │
│ twenty app init → twenty app dev (live sync) │
├─────────────────────────────────────────────────────────┤
│ Build & Deploy │
│ twenty app build → twenty app publish │
├─────────────────────────────────────────────────────────┤
│ Install flow │
│ upload → [pre-install] → metadata migration → │
│ generate SDK → [post-install] → … → [uninstall] │
├─────────────────────────────────────────────────────────┤
│ Publish │
│ npm publish → appears in Twenty marketplace │
└─────────────────────────────────────────────────────────┘
```
- **`twenty app dev`** — watches your source files and live-syncs changes to a connected Twenty server. After a successful sync, it regenerates the typed API client when the schema or installed generator package changed, or generated client files are missing or changed. To refresh types after changing the workspace in the UI, run `twenty app generate-client`.
- **`twenty app build`** — compiles TypeScript, bundles logic functions and front components with esbuild, and produces a manifest.
- **Pre/post-install and uninstall hooks** — optional functions that run during installation or right before removal. See [Install Hooks](/developers/extend/apps/config/install-hooks) for details.
## Next steps
<CardGroup cols={2} className="documentation-card-group">
<Card href="/developers/extend/apps/config/overview" img="/images/documentation/section-overview-icons-v1/apps-config.svg">
<CardTitle>Config</CardTitle>
Application identity, default role, and install and uninstall hooks.
</Card>
<Card href="/developers/extend/apps/data/overview" img="/images/documentation/section-overview-icons-v1/apps-data.svg">
<CardTitle>Data</CardTitle>
Objects, fields, and bidirectional relations.
</Card>
<Card href="/developers/extend/apps/logic/overview" img="/images/documentation/section-overview-icons-v1/apps-logic.svg">
<CardTitle>Logic</CardTitle>
Logic functions, skills, agents, connections, and messaging channels.
</Card>
<Card href="/developers/extend/apps/layout/overview" img="/images/user-guide/halftone/layout-window-v1.svg">
<CardTitle>Layout</CardTitle>
Views, navigation, page layouts, front components.
</Card>
<Card href="/developers/extend/apps/operations/overview" img="/images/documentation/section-overview-icons-v1/apps-operations.svg">
<CardTitle>Operations</CardTitle>
CLI, testing, remotes, CI, and publishing your app.
</Card>
</CardGroup>
<PageBanner illustration="dev-apps" />