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 and feedback components
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
| Trigger | Consequence | Guard |
|---|---|---|
| A public shared module is added without a generated barrel or package export | A consumer cannot import the contract or receives a stale type surface | Keep 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 handling | Existing applications stop syncing, connecting, sending messages, enforcing access, or accepting valid prices | Keep 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 links | Row-level access changes during sync or migration | Normalize, flatten, and nest rules through the shared permission utilities |
| A standard universal identifier changes | Stored metadata no longer resolves to the same object, field, view, or layout | Treat 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 unit | A record query returns the wrong rows or a validation rule gives the wrong result | Use the shared filter parser, date units, date parts, and evaluator |
| A workflow email body is stored as HTML or plain text instead of a document | The step fails validation or an old run cannot be read in the expected form | Convert 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 sync | The embedded component fails to render or loses its styles | Run 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 surface | Product and embedded screens show different behavior or lose an accessibility behavior | Keep package exports, component stories, themes, keyboard states, mobile rules, and direction support aligned |
Key files
| File | Why to read it |
|---|---|
| packages/…/package.json | Shows the public contract groups and subpath boundaries. |
| packages/…/generateBarrels.ts | Shows how shared barrels and package exports stay aligned with modules. |
| packages/…/vite.config.ts | Shows how the public shared modules become runtime and development builds. |
| packages/…/manifestType.ts | Shows the application resource contract as one platform manifest. |
| packages/…/navigationMenuItemManifestType.ts | Shows how application navigation connects items to platform surfaces. |
| packages/…/roleManifestType.ts | Shows broad, field, and row-level role permissions. |
| packages/…/isApplicationBillingPriceAmount.ts | Shows the shared boundary for valid application billing amounts. |
| packages/…/isApplicationBillingPriceAmount.test.ts | Shows the accepted and rejected billing amount cases. |
| packages/…/normalizeNavigationMenuItemManifest.ts | Shows how older navigation declarations become the current parent model. |
| packages/…/index.ts | Shows the public vocabulary for AI tools, messages, models, and run state. |
| packages/…/standard-object.constant.ts | Shows how standard fields, indexes, and views form record metadata. |
| packages/…/standard-page-layout-universal-identifiers.constant.ts | Shows how standard records connect to stable page layouts. |
| packages/…/ExpressionDate.ts | Shows the shared value model for date-only and date-time expressions. |
| packages/…/split-filter-array-items.ts | Shows how filter arrays preserve quoted values. |
| packages/…/memoizeLeastRecentlyUsed.ts | Shows the shared bounded cache behavior. |
| packages/…/convert-email-body-input-to-email-document.ts | Shows how email input becomes a versioned document. |
| packages/…/workflow-run-schema.ts | Shows the shared workflow run state boundary. |
| packages/…/validate-workflow-step-params.util.ts | Shows the checks applied before workflow steps run. |
| packages/…/css-injection-plugin.ts | Shows how embedded component styles reach the browser. |
| packages/…/package.json | Shows the supported UI package and subpath boundaries. |
| packages/…/Dropdown.module.scss | Shows shared menu layout, focus, selection, and scrolling states. |
| packages/…/Shortcut.tsx | Shows shared keyboard hint presentation and accessibility behavior. |
| packages/…/Skeleton.stories.tsx | Shows component states for loading, motion, theme, direction, and composition. |
| packages/…/index.ts | Shows the application authoring boundary. |
| packages/…/index.ts | Shows the runtime-facing application boundary. |