Introducing a new way to review your PRs.

Read the announcement

twentyhq / twenty

The open alternative to Salesforce, designed for AI.

View on GitHub

22 documents · Updated Nov 20, 2026

docs / shared-platform

Shared libraries and design system

The shared platform gives product features one common language for data, rules, application extensions, AI behavior, and user interfaces. packages/twenty-shared carries contracts and small rules across runtimes. packages/twenty-ui gives product and application surfaces the same visual and interaction patterns. See shared domain contracts and UI component system for the child pages.

Platform role

The platform sits between product features and the systems that use them. Shared contracts keep stored data, permissions, applications, AI tools, workflows, exports, and rich content aligned. Shared UI rules keep those features clear and consistent for users.

Each shared rule has one public source. A contract can reach the server, web client, SDK, workflow runtime, front-component builder, or application runtime. A design rule can reach a product page or an embedded application surface.

This diagram shows how shared contracts and UI rules shape the surfaces that users see.

flowchart LR
    Features[Product features] --> Contracts[Shared domain contracts]
    Features --> UI[UI component system]
    Contracts --> Consumers[Server, client, SDK, workflows, apps, and front components]
    UI --> Consumers
    Consumers --> Experience[Consistent product experience]

Shared domain contracts

The shared domain library gives different runtimes the same types, schemas, values, and small rules. Its public subpaths cover applications, AI, metadata, workflows, validation, date expressions, caching, content, and other cross-system concerns. The package and its build expose these groups as stable consumer boundaries (packages/…/package.json• L67-227, packages/…/vite.config.ts• L6-17). See shared domain contracts for the contract groups and their business meaning.

Public contract surface

The public contract surface turns source modules into package entry points that consumers can use by purpose. Barrel generation scans supported source modules and updates their exports, package paths, type paths, and build outputs together (packages/…/generateBarrels.ts• L490-502). The build then produces the main package and each public subpath in development, module, and CommonJS forms (packages/…/vite.config.ts• L27-75).

This keeps a new shared rule available to all intended runtimes without making private files part of the product contract. Generated barrels are outputs of this process and are not hand-maintained (packages/…/generateBarrels.ts• L42-60).

References: packages/…/package.json• L67-227 packages/…/generateBarrels.ts• L490-502 packages/…/vite.config.ts• L6-17

Application extension contracts

Application contracts describe what an application can declare and how it can connect to the platform. They cover logic functions, record events, scheduled triggers, connections, agents, permissions, messaging, views, page layouts, navigation, front components, source files, and other application resources through one manifest model (packages/…/manifestType.ts• L37-70, packages/…/index.ts• L176-228).

Application billing prices use a shared amount rule. The amount must be a positive whole number of cents within the platform limit, so authoring and runtime consumers apply the same safe billing boundary (packages/…/isApplicationBillingPriceAmount.ts• L3-9, packages/…/MaxApplicationBillingPriceAmountCents.ts• L1-3).

Connection providers support OAuth, OAuth discovery, custom credentials, and API keys. Stable first-party identifiers and deterministic resource identifiers let installed applications and system side effects keep the same identity across syncs (packages/…/TwentyPublicAppUniversalIdentifiers.ts• L1-12, packages/…/get-system-side-effect-role-target-universal-identifier.util.ts• L3-15). Navigation manifests link items to views, records, layouts, native pages, and parent items. Older folder identifiers are normalized into the current parent identifier so published applications can move to the current shape (packages/…/navigationMenuItemManifestType.ts• L5-20, packages/…/normalizeNavigationMenuItemManifest.ts• L4-24).

Roles express broad record grants, field limits, and row-level rules. The shared utilities can recognize older role declarations while installed applications move to the current records-permissions model (packages/…/roleManifestType.ts• L63-152, packages/…/getDeclaredLegacyRoleRecordsPermissionsKeys.ts• L7-20). Application source manifests accept only safe, restorable source paths and unique checksums (packages/…/isRestorableApplicationSourcePath.ts• L3-16, packages/…/isSourceFileManifestList.ts• L6-27).

References: packages/…/manifestType.ts• L37-70 packages/…/TwentyPublicAppUniversalIdentifiers.ts• L1-12 packages/…/navigationMenuItemManifestType.ts• L5-20 packages/…/roleManifestType.ts• L63-152 packages/…/normalizeNavigationMenuItemManifest.ts• L4-24 packages/…/isSourceFileManifestList.ts• L6-27 packages/…/isApplicationBillingPriceAmount.test.ts• L4-23

AI conversation contracts

AI contracts give chat, agents, tool calls, model choice, permissions, and usage one shared vocabulary. Chat threads use shared preset filters and inbox status so server queries and client views place the same thread in the same state (packages/…/agent-chat-thread-preset-filter.const.ts• L1-13, packages/…/compute-agent-chat-thread-preset-filter-gql-filter.util.ts• L8-96, packages/…/get-agent-chat-thread-inbox-status.util.ts• L17-101).

The inbox model separates whether a member follows a thread from whether the thread is unread, mentioned, snoozed, or done. New activity can reopen a filed thread, while an unresolved mention remains visible until a later mention resolution (packages/…/AgentChatThreadInboxStatus.ts• L1-14, packages/…/get-agent-chat-thread-inbox-status.util.ts• L9-17). Tool names now have a shared snake-case boundary, while tool categories and destructive-tool checks keep AI actions grouped and safe (packages/…/is-snake-case-tool-name.util.ts• L1-4, packages/…/tool-category.const.ts• L1-15, packages/…/is-destructive-mcp-server-tool.util.ts• L1-11).

Stored agent messages and client messages still use matching shapes. The shared mapping preserves message parts, thread state, sender data, turn data, and stream timing for the UI (packages/…/index.ts• L60-75, packages/…/index.ts• L131-176).

References: packages/…/index.ts• L10-15 packages/…/agent-chat-thread-preset-filter.const.ts• L1-13 packages/…/AgentChatThreadInboxStatus.ts• L1-14 packages/…/compute-agent-chat-thread-preset-filter-gql-filter.util.ts• L8-96 packages/…/get-agent-chat-thread-inbox-status.util.ts• L17-101 packages/…/is-snake-case-tool-name.util.ts• L1-4

Metadata and permission contracts

Metadata contracts give objects, fields, relations, indexes, views, layouts, and permissions stable names and shapes. A universal identifier is the durable name for a resource across runtimes. Standard objects now cover core records together with chat, messaging, campaigns, workflows, and page-layout records (packages/…/standard-object.constant.ts• L6-8, packages/…/standard-object.constant.ts• L1390-1542). Existing identifiers are stored data and must not change casually (packages/…/standard-object.constant.ts• L6-7).

Standard fields and page layouts extend that identity into record pages and dashboards. Their stable fields, tabs, and widgets keep metadata and visible record surfaces aligned (packages/…/standard-object-fields.constant.ts• L7-10, packages/…/standard-page-layout-universal-identifiers.constant.ts• L4-7). Reserved metadata names protect platform-owned resources from collision with user-defined names (packages/…/reserved-metadata-name-keywords.constant.ts• L1-8).

Metadata synchronization uses one action shape for create, update, and delete changes. Each action names the metadata kind and carries the identifier or change data needed to apply it (packages/…/SyncAction.ts• L3-32). Field options also share one meaning for active and inactive choices. An inactive choice can remain on existing records while no longer being available for new selection (packages/…/FieldMetadataOptions.ts• L5-14, packages/…/isFieldMetadataOptionActive.ts• L1-3).

Permission helpers answer access questions per operation. They distinguish access to all records from access granted by at least one row-level rule, then map read, create, update, soft-delete, and destroy to the matching permission (packages/…/canAccessThroughAllRecordsOrRlsPermission.ts• L7-23, packages/…/canAccessThroughAllRecordsPermission.ts• L6-39, packages/…/canAccessThroughRlsPermission.ts• L6-20).

References: packages/…/standard-object.constant.ts• L6-8 packages/…/standard-object-fields.constant.ts• L7-10 packages/…/standard-page-layout-universal-identifiers.constant.ts• L4-7 packages/…/reserved-metadata-name-keywords.constant.ts• L1-8 packages/…/SyncAction.ts• L3-32 packages/…/canAccessThroughRlsPermission.ts• L6-20

Validation and filter contracts

Validation rules let a record condition compare current values, prior values, and a shared write-time value. The rule evaluator returns passed, failed, or errored so a bad expression does not look like a valid record (packages/…/createValidationRuleEvaluator.ts• L9-66). Database events supply the current record and, when the action supports it, the prior record (packages/…/getValidationRuleRecordsFromDatabaseEvent.ts• L4-43).

Expression dates provide one shared model for date-only values and zoned date-time values. Date functions use shared units and parts for differences, additions, truncation, relative ranges, and validation messages (packages/…/ExpressionDate.ts• L1-5, packages/…/ExpressionDateParts.ts• L1-10, packages/…/ExpressionDateUnits.ts• L1-4, packages/…/ValidationRuleFunctions.ts• L11-55).

Record filters convert user-facing field conditions into one shared GraphQL filter shape. This covers scalar fields, composite fields, relations, relative dates, and array-valued inputs (packages/…/RecordGqlOperationFilter.ts• L1-14, packages/…/RecordGqlOperationFilter.ts• L192-240, packages/…/turnRecordFilterIntoGqlOperationFilter.ts• L149-209). Filter text keeps quoted commas inside array values instead of treating them as separators (packages/…/split-filter-array-items.ts• L8-33).

References: packages/…/createValidationRuleEvaluator.ts• L18-66 packages/…/ExpressionDate.ts• L1-5 packages/…/ValidationRuleFunctions.ts• L11-55 packages/…/turnRecordFilterIntoGqlOperationFilter.ts• L149-209 packages/…/split-filter-array-items.ts• L8-33 packages/…/resolveRelativeDateTimeFilter.ts• L9-61

Workflow contracts

Workflow contracts give the editor, runner, and run view the same language for triggers, actions, waits, variables, records, filters, and results. The public boundary includes action schemas, run state, output schemas, layout data, and validation tools (packages/…/index.ts• L31-37, packages/…/index.ts• L120-140, packages/…/index.ts• L190-218).

The action contract is a discriminated set of supported actions. Email bodies use a serialized email document and can include files or workflow variable references (packages/…/send-email-action-settings-schema.ts• L7-38). Workflow validation checks trigger and step shapes before execution and rejects invalid email documents or record updates without fields (packages/…/validate-workflow-step-params.util.ts• L31-98). A workflow run keeps its state, status, step logs, and lifecycle dates in one shape (packages/…/workflow-run-schema.ts• L6-18).

Feature flags connect optional workflow actions to the product features that enable them. MCP tool defaults come from the tool schema so the editor can show required inputs before a run (packages/…/FeatureFlagKey.ts• L1-25, packages/…/getDefaultMcpToolInputFromJsonSchema.ts• L7-53).

References: packages/…/index.ts• L31-37 packages/…/send-email-action-settings-schema.ts• L7-38 packages/…/workflow-run-schema.ts• L6-18 packages/…/getDefaultMcpToolInputFromJsonSchema.ts• L7-53 packages/…/validate-workflow-step-params.util.ts• L31-98

Page layout and embedded UI contracts

Page-layout utilities keep configurable surfaces usable across product and application pages. They decide whether a front component can appear in a widget picker and keep viewport-filling widgets at the end of a vertical list (packages/…/isFrontComponentAvailableInWidgetPicker.ts• L5-29, packages/…/reindexWidgetsToVerticalListPositions.ts• L11-29, packages/…/sortWidgetsWithViewportFillingLast.ts• L16-34).

Front-component build contracts let embedded application UI use host-provided browser dependencies. The shared boundary checks type references and records build inputs so the host and component agree on imports (packages/…/collect-front-component-type-references.ts• L5-88, packages/…/shared-dependencies-build-manifest.type.ts• L3-9). It also checks a component with a small preview program and can bundle CSS into a browser style element, so type errors and styles reach the embedded surface before it runs (packages/…/get-front-component-type-diagnostics.ts• L6-18, packages/…/css-injection-plugin.ts• L26-81).

References: packages/…/isFrontComponentAvailableInWidgetPicker.ts• L5-29 packages/…/reindexWidgetsToVerticalListPositions.ts• L11-29 packages/…/sortWidgetsWithViewportFillingLast.ts• L16-34 packages/…/collect-front-component-type-references.ts• L5-88 packages/…/get-front-component-type-diagnostics.ts• L6-18 packages/…/css-injection-plugin.ts• L26-81

Boundary utilities

Shared utilities apply product rules at system boundaries. They cover filters, dates, currency, URLs, rich content, navigation, page layouts, feature flags, permissions, validation, caching, and email documents so each runtime does not invent a different result (packages/…/index.ts• L28-44, packages/…/index.ts• L95-148).

Email body input accepts a document, HTML, or text and produces a versioned email document for workflow and messaging consumers. Plain text keeps line breaks as document breaks, while an empty body has a valid empty document shape (packages/…/email-body-input-schema.ts• L5-10, packages/…/convert-email-body-input-to-email-document.ts• L15-39, packages/…/empty-email-document.ts• L5-9). Older string-body conversion now belongs to the server upgrade path (packages/…/convert-string-body-to-email-document.util.ts• L29-70).

Least-recently-used cache utilities provide bounded reuse for pure lookups. Reads refresh recency, writes evict old entries, and the shared eviction rule can apply a limit to the whole map or a selected group (packages/…/memoizeLeastRecentlyUsed.ts• L5-26, packages/…/readLruEntry.ts• L3-19, packages/…/writeLruEntry.ts• L3-18, packages/…/evictLeastRecentlyUsed.ts• L5-24).

The feature-flag vocabulary gives optional product behavior one shared set of names. Field option checks and filter parsing follow the same rule in every consumer, including the server, client, and application layers (packages/…/FeatureFlagKey.ts• L1-25, packages/…/isFieldMetadataOptionActive.ts• L1-3, packages/…/index.ts• L137-148).

References: packages/…/index.ts• L28-44 packages/…/index.ts• L95-148 packages/…/convert-email-body-input-to-email-document.ts• L15-39 packages/…/memoizeLeastRecentlyUsed.ts• L5-26 packages/…/evictLeastRecentlyUsed.ts• L5-24 packages/…/FeatureFlagKey.ts• L1-25

UI component system

The UI component system is the shared React library for product screens and application surfaces. It provides primitives and product components for input, display, feedback, layout, navigation, surfaces, typography, icons, themes, accessibility, and testing (packages/…/package.json• L1-5, packages/…/package.json• L104-232). See UI component system for the component families and interaction rules.

The public entry point groups these families behind supported exports. Engineers can use a low-level primitive for a focused need or a higher-level component for a common product pattern (packages/…/package.json• L104-232).

Input and display components

Input components give forms common value, state, focus, size, label, and keyboard behavior. Display components show status, labels, icons, text, and compact record data. These components make common product states recognizable across screens.

Compact display elements such as chips share size, shape, color, variant, truncation, focus, disabled, hover, and active behavior. This keeps labels and status markers readable when they are static or clickable (packages/…/Chip.module.scss• L1-97).

Feedback primitives also represent loading without exposing a false content state. The skeleton supports block and inline layouts, custom shape and color, static or animated display, dark mode, right-to-left layout, and reduced motion (packages/…/Skeleton.stories.tsx• L24-79, packages/…/Skeleton.stories.tsx• L83-101, packages/…/Skeleton.stories.tsx• L169-210).

References: packages/…/package.json• L78-93 packages/…/Chip.module.scss• L1-97 packages/…/Skeleton.stories.tsx• L9-18

Navigation components give menus, tabs, list items, pagers, popovers, dialogs, and tooltips a shared interaction model. Dropdowns also share grouped content, search, scrolling, selection, and focus-visible behavior (packages/…/package.json• L118-212, packages/…/Dropdown.module.scss• L1-13, packages/…/Dropdown.module.scss• L53-77). Feedback components explain loading, empty, error, progress, warning, and success states so users can understand what the system is doing.

The component system treats focus, motion, dark mode, and right-to-left layout as shared states rather than screen-specific exceptions. Stories exercise these states as part of the component contract (packages/…/Skeleton.stories.tsx• L169-210).

References: packages/…/package.json• L118-212 packages/…/Dropdown.module.scss• L1-13 packages/…/Dropdown.module.scss• L53-77 packages/…/Skeleton.stories.tsx• L185-210

Themes and icons

Themes provide shared values for color, type, spacing, borders, shadows, motion, and shape. Light and dark themes expose the same value set, so components can change appearance without changing their contract. Icons provide a stable visual vocabulary through named components and public icon lookup (packages/…/package.json• L104-232).

References: packages/…/package.json• L104-232 packages/…/Skeleton.stories.tsx• L185-194

Public UI boundaries

The top-level UI package is the supported boundary for product and application consumers. It provides package exports for components, primitives, icons, themes, styles, utilities, and testing support (packages/…/package.json• L104-232). Focused imports keep consumers tied to a component family instead of to internal source paths.

Component stories and generated documentation describe supported names, states, and props. A component change is therefore a change to the shared product language. Its public export, state contract, theme support, and accessibility behavior must continue to describe the same user experience (packages/…/Skeleton.stories.tsx• L9-18, packages/…/Skeleton.stories.tsx• L50-80). Shortcut presentation adds a shared accessible label and can hide desktop-only hints on mobile (packages/…/Shortcut.tsx• L23-46).

References: packages/…/package.json• L104-232 packages/…/Skeleton.stories.tsx• L9-18 packages/…/Skeleton.stories.tsx• L50-80 packages/…/Shortcut.tsx• L23-46

Consumer boundaries

The server, web client, SDK, workflow runtime, component renderer, and applications consume shared packages through public exports. Each consumer selects the contract groups it needs while relying on the same names and shapes.

Application authoring boundary

The SDK turns shared application contracts into an authoring boundary. Application authors declare resources, roles, layouts, logic, connections, messaging, billing, and workflows through the same model used by the platform. Validation checks the declaration before it becomes a build result (packages/…/index.ts• L1-32, packages/…/index.ts• L60-85).

References: packages/…/index.ts• L1-32 packages/…/index.ts• L60-85

Application runtime boundary

The SDK runtime boundary gives deployed logic functions access to platform capabilities through shared request and response shapes. It carries connections, messaging, inbox work, agents, jobs, timeline activity, and key-value data without creating a second product contract (packages/…/index.ts• L1-11, packages/…/index.ts• L171-217).

References: packages/…/index.ts• L1-11 packages/…/index.ts• L171-217

Front-component runtime boundary

The front-component boundary lets application UI run with host-provided shared dependencies. The shared build contract checks dependency type references, records build inputs, creates a common entry point, and maps component imports to that host entry point (packages/…/collect-front-component-type-references.ts• L5-88, packages/…/index.ts• L10-36).

References: packages/…/collect-front-component-type-references.ts• L5-88 packages/…/index.ts• L10-36

Contract propagation

When a shared value changes, every consumer boundary must still understand it. The normal path is:

flowchart TD
    Source[Shared contract or design rule] --> Export[Public package export]
    Export --> Server[Server and workflow runtime]
    Export --> Client[Web client and UI renderer]
    Export --> SDK[SDK and applications]
    Export --> Front[Embedded front components]
    Server --> Result[Stored or visible product behavior]
    Client --> Result
    SDK --> Result
    Front --> Result

References: packages/…/index.ts• L1-32 packages/…/index.ts• L1-11 packages/…/index.ts• L10-36 packages/…/package.json• L67-227

Change checklist

When these files or sections are changed, remember to consider these:

  • Application manifests, navigation, source-file lists, connection providers, messaging payloads, billing amounts, or role permissions: check SDK declarations, runtime payloads, sync state, compatibility with older manifests, application settings, and billing limits together.
  • Deterministic identifiers, standard metadata, page layouts, or reserved names: check stored identifiers, server builders, generated views, and visible record surfaces together.
  • Role permission nesting, flattening, normalization, or restriction comparison: check object grants, field restrictions, row-level predicates, and stable identifiers together.
  • Filter parsing, validation expressions, or date helpers: check quoted values, array splitting, expression units and parts, UTC boundaries, and all filter and validation entry points together.
  • Workflow email bodies or email document input: check schema versioning, variable handling, legacy upgrade conversion, and send-step validation together.
  • Front-component type checks, CSS handling, or shared dependency builds: check preview diagnostics, host imports, source tracking, style injection, and embedded runtime behavior together.
  • UI exports, dropdown states, shortcut presentation, or component stories: check public import paths, keyboard and focus behavior, mobile visibility, light and dark states, motion preferences, right-to-left behavior, and accessibility behavior together.

Important failure modes

TriggerConsequenceGuard
A public shared module is added without a generated barrel or package exportA consumer cannot import the contract or receives a stale type surfaceKeep source barrels, package exports, type paths, and build entries in sync
A stored application trigger, provider, message, navigation item, role type, or billing amount changes without compatibility handlingExisting applications stop syncing, connecting, sending messages, enforcing access, or accepting valid pricesKeep current and accepted legacy forms in the shared application contract and validate billing amounts at the shared boundary
A role changes from nested rules to flat records without preserving identifiers and parent linksRow-level access changes during sync or migrationNormalize, flatten, and nest rules through the shared permission utilities
A standard universal identifier changesStored metadata no longer resolves to the same object, field, view, or layoutTreat identifiers as durable values and update them only for an explicit change
A filter parser splits a quoted comma or a date rule uses an unsupported unitA record query returns the wrong rows or a validation rule gives the wrong resultUse the shared filter parser, date units, date parts, and evaluator
A workflow email body is stored as HTML or plain text instead of a documentThe step fails validation or an old run cannot be read in the expected formConvert input at the boundary and validate serialized email documents
A front component passes type checks but its host dependency or CSS build is out of syncThe embedded component fails to render or loses its stylesRun the shared preview diagnostics and track host imports and CSS source files
A UI export, theme state, dropdown focus rule, or shortcut rule changes in only one surfaceProduct and embedded screens show different behavior or lose an accessibility behaviorKeep package exports, component stories, themes, keyboard states, mobile rules, and direction support aligned

Key files

FileWhy to read it
packages/…/package.jsonShows the public contract groups and subpath boundaries.
packages/…/generateBarrels.tsShows how shared barrels and package exports stay aligned with modules.
packages/…/vite.config.tsShows how the public shared modules become runtime and development builds.
packages/…/manifestType.tsShows the application resource contract as one platform manifest.
packages/…/navigationMenuItemManifestType.tsShows how application navigation connects items to platform surfaces.
packages/…/roleManifestType.tsShows broad, field, and row-level role permissions.
packages/…/isApplicationBillingPriceAmount.tsShows the shared boundary for valid application billing amounts.
packages/…/isApplicationBillingPriceAmount.test.tsShows the accepted and rejected billing amount cases.
packages/…/normalizeNavigationMenuItemManifest.tsShows how older navigation declarations become the current parent model.
packages/…/index.tsShows the public vocabulary for AI tools, messages, models, and run state.
packages/…/standard-object.constant.tsShows how standard fields, indexes, and views form record metadata.
packages/…/standard-page-layout-universal-identifiers.constant.tsShows how standard records connect to stable page layouts.
packages/…/ExpressionDate.tsShows the shared value model for date-only and date-time expressions.
packages/…/split-filter-array-items.tsShows how filter arrays preserve quoted values.
packages/…/memoizeLeastRecentlyUsed.tsShows the shared bounded cache behavior.
packages/…/convert-email-body-input-to-email-document.tsShows how email input becomes a versioned document.
packages/…/workflow-run-schema.tsShows the shared workflow run state boundary.
packages/…/validate-workflow-step-params.util.tsShows the checks applied before workflow steps run.
packages/…/css-injection-plugin.tsShows how embedded component styles reach the browser.
packages/…/package.jsonShows the supported UI package and subpath boundaries.
packages/…/Dropdown.module.scssShows shared menu layout, focus, selection, and scrolling states.
packages/…/Shortcut.tsxShows shared keyboard hint presentation and accessibility behavior.
packages/…/Skeleton.stories.tsxShows component states for loading, motion, theme, direction, and composition.
packages/…/index.tsShows the application authoring boundary.
packages/…/index.tsShows the runtime-facing application boundary.