Architecture

Clara apps are TypeScript packages that extend your workspace with custom objects, logic, UI components, and AI capabilities. They run on the Clara 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

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.

Entity types

Entity	Purpose	Docs
Application	App identity, permissions, variables	Data Model
Role	Permission sets for objects and fields	Data Model
Object	Custom data tables with fields	Data Model
Field	Extend existing objects, define relations	Data Model
Logic Function	Server-side TypeScript with triggers	Logic Functions
Front Component	Sandboxed React UI in Clara’s page	Front Components
Skill	Reusable AI agent instructions	Skills & Agents
Agent	AI assistants with custom prompts	Skills & Agents
View	Pre-configured record list views	Layout
Navigation Menu Item	Custom sidebar entries	Layout
Page Layout	Custom record page tabs and widgets	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 Clara 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 Clara marketplace            │
└─────────────────────────────────────────────────────────┘

yarn twenty dev — watches your source files and live-syncs changes to a connected Clara 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 for details.

Next steps

Data Model

Define objects, fields, roles, and relations.

Logic Functions

Server-side functions with HTTP, cron, and event triggers.

Front Components

Sandboxed React components inside Clara’s UI.

Layout

Views, navigation items, and record page layouts.

Skills & Agents

AI skills and agents with custom prompts.

CLI & Testing

CLI commands, testing, assets, remotes, and CI.

Publishing

Deploy to a server or publish to the marketplace.

Overview

Apps

API

Self-Host

Contribute

How apps work

Entity types

Sandboxing

App lifecycle

Next steps

Data Model

Logic Functions

Front Components

Layout

Skills & Agents

CLI & Testing

Publishing

​How apps work

​Entity types

​Sandboxing

​App lifecycle

​Next steps

Data Model

Logic Functions

Front Components

Layout

Skills & Agents

CLI & Testing

Publishing

How apps work

Entity types

Sandboxing

App lifecycle

Next steps