mirror of
https://github.com/twentyhq/twenty
synced 2026-04-21 13:37:22 +00:00
69868a0ab6
## Summary - Remove the \"Apps are currently in alpha\" warning from 8 pages under `developers/extend/apps/` (getting-started, architecture/building, data-model, layout, logic-functions, front-components, cli-and-testing, publishing). - Keep the warning on the Skills & Agents page only, and reword it to scope it to that feature: \"Skills and agents are currently in alpha. The feature works but is still evolving.\" ## Test plan - [ ] Preview docs build and confirm the warning banner no longer appears on the 8 pages above. - [ ] Confirm the warning still renders on the Skills & Agents page with the updated wording. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
104 lines
6.4 KiB
Text
104 lines
6.4 KiB
Text
---
|
|
title: Architecture
|
|
description: How Twenty apps work — sandboxing, lifecycle, and the building blocks.
|
|
icon: "sitemap"
|
|
---
|
|
|
|
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>
|