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 / web-client

Web client application

The web client application is the browser entry point for the product. It starts React, selects a public or workspace experience, and connects product areas to server data through typed APIs. Shared state keeps identity, workspace structure, records, conversations, automation, and setup progress aligned with the routes that show them.

React bootstrap

The React bootstrap turns the browser document into a product surface. Shared providers give public and signed-in routes one place for language, theme, errors, feedback, data access, and workspace services.

Startup boundary

The startup boundary restores useful browser state, creates the React root, and loads runtime configuration before it selects a product boundary. A root error boundary protects the page when a route or shared service fails. index.tsx App.tsx

The browser waits for client configuration before it mounts the workspace. During that wait it shows either an onboarding loader or a user and metadata loader. Optional browser-state restore can fail without blocking the React root.

This diagram shows how the browser becomes a configured product surface.

flowchart TD
  Browser[Browser document] --> React[React root]
  React --> Shared[Shared providers]
  Shared --> Config[Client configuration]
  Config --> Boundary{Product boundary}
  Boundary --> Public[Public routes]
  Boundary --> Workspace[Workspace providers and routes]

References: packages/…/index.tsx• L19-29 packages/…/App.tsx• L20-49 packages/…/DomainShell.tsx• L14-40

Workspace providers

The workspace provider boundary prepares the services that signed-in work needs. It joins identity, workspace metadata, query clients, dialogs, page titles, tracking, applications, AI chat, inbox effects, and live events before it renders the active route. WorkspaceAppProviders.tsx

The same boundary exposes shared actions such as record changes, commands, file previews, support, and form work. Pages use these services without owning their global lifecycle. AI chat is also mounted once at the workspace level, while each visible chat surface receives its own instance and thread context.

References: packages/…/WorkspaceAppProviders.tsx• L47-112 packages/…/AiChatProvider.tsx• L8-21 packages/…/AiChatInstance.tsx• L10-39

Routing model

The routing model separates public account work from the active workspace. Workspace routes connect records, layouts, AI, agents, workflows, inbox conversations, onboarding, and settings to one navigation model.

Domain route trees

The domain shell uses runtime configuration and the current host to choose a route tree. Single-workspace mode opens the workspace tree directly. Multi-workspace mode uses public routes on the default domain and workspace routes on a workspace domain. DomainShell.tsx

Large workspace areas load when a user visits them. This keeps the first view focused while preserving route contracts for records, AI, agents, workflows, getting started, mobile home, and settings. Settings routes are built as a protected subtree so access rules and feature flags decide which administrative pages can open. createWorkspaceRouteObjects.tsx SettingsRoutes.tsx

flowchart TD
  Shell[Domain shell] --> Config{Configuration loaded?}
  Config -- No --> Loading[Configuration or onboarding loader]
  Config -- Yes --> Mode{Single workspace?}
  Mode -- Yes --> Workspace[Workspace route tree]
  Mode -- No --> Host{Workspace host?}
  Host -- No --> Public[Public route tree]
  Host -- Yes --> Workspace

References: packages/…/DomainShell.tsx• L14-40 packages/…/createWorkspaceRouteObjects.tsx• L94-235 packages/…/SettingsRoutes.tsx• L806-1419

Workspace surfaces

Workspace routes can serve a main page, a routed side panel, or both. The main location remains visible while a side panel supports a related task. Lazy route boundaries let a user move between these surfaces without loading every product area at startup. createWorkspaceRouteObjects.tsx

Location changes also manage short-lived state. They close unrelated panels, reset record focus, update layout context, and clear full-screen console state. Legacy paths redirect to current paths while preserving useful URL state. PageChangeEffect.tsx

Conversation navigation now has two related forms. The inbox is the main shared route for thread lists and reading. Older AI chat URLs remain supported through a compatibility page that opens a new thread or redirects to the inbox when the matching inbox destination exists. A selected thread can use the full page, inbox, or side-panel surface without changing its record identity. InboxPage.tsx LegacyAiChatPage.tsx AiChatThreadPageContent.tsx

References: packages/…/createWorkspaceRouteObjects.tsx• L101-235 packages/…/PageChangeEffect.tsx• L117-181 packages/…/InboxPage.tsx• L110-228 packages/…/LegacyAiChatPage.tsx• L14-41 packages/…/AiChatThreadPageContent.tsx• L16-43

The workspace navigation groups the main menu, inbox or AI history, and settings as drawer tabs. The active tab comes from the current route when the route decides the mode. Otherwise it uses the stored tab so a member can return to conversation history without losing the main navigation context. useActiveNavigationDrawerTab.ts

Feature flags, permissions, workspace status, and screen size shape the tabs that appear. Desktop uses the drawer. Mobile uses the home surface and bottom navigation instead of the main drawer. useNavigationDrawerTabs.ts AppNavigationDrawer.tsx

References: packages/…/useActiveNavigationDrawerTab.ts• L12-32 packages/…/useNavigationDrawerTabs.ts• L30-66 packages/…/AppNavigationDrawer.tsx• L18-47 packages/…/MainNavigationDrawerTabSwitcher.tsx• L54-177

Generated API boundary

The web client uses GraphQL as its main data boundary. Generated operation types, schema types, and typed document nodes keep each product area aligned with the server schema. Selected runtime and content resources use other API paths.

Schema surfaces

The client has separate generated GraphQL surfaces for core product data, workspace metadata, and privileged administration. Each surface matches a different server responsibility.

API surfaceProduct responsibility
CoreRecords, activities, calendar, messages, views, AI chat data, and core product work
MetadataWorkspace structure, identity, settings, applications, agents, communication, and setup state
AdminPrivileged administration, monitoring, AI administration, and workspace operations

Operations stay near the product area that uses them. Code generation turns them into TypeScript contracts, so a server schema change becomes visible at the client boundary. The generated surfaces also carry newer inbox, application, and AI administration contracts used by the workspace and settings experiences. graphql.ts generated-metadata/graphql.ts generated-admin/graphql.ts

References: packages/…/graphql.ts• L1-100 packages/…/schema.ts• L1-80 packages/…/graphql.ts• L1-60 packages/…/schema.ts• L1-30 packages/…/graphql.ts• L1-60 packages/…/schema.ts• L1-30

Data and cache contract

Apollo holds fetched server data and shares it across pages, panels, pickers, activities, and widgets. Record queries use workspace metadata and current read access to request fields that the member can see. This lets custom objects and relations use the same product surfaces.

Metadata changes can make record results stale. Live metadata events discard affected results so later views use the new field shape. Optimistic updates keep lists and grouped views responsive while the server confirms a change. Shared API clients send the browser session and workspace context. Temporary failures can be retried. An authentication failure clears old identity and routes the member to sign-in with a valid return path.

References: packages/…/ApolloFactory.ts• L84-137 packages/…/ApolloFactory.ts• L198-306 packages/…/mapObjectMetadataToGraphQLQuery.ts• L20-55 packages/…/useFindManyRecords.ts• L36-107 packages/…/RecordCacheStaleQueriesSSEEffect.tsx• L10-51

Module organization

The client groups product behavior by domain module. Routes choose the visible experience, while modules own state and behavior that can serve more than one page.

Product domains

The app domain owns providers, route choice, layouts, and cross-route effects. Identity and workspace domains own access and membership. Metadata domains describe the workspace. Record, view, activity, dashboard, workflow, AI, inbox, application, and agent domains provide the main product capabilities.

Navigation, side panels, commands, query data, live events, jobs, localization, and error handling support those domains. This separation lets a record page use shared metadata and navigation without owning workspace startup or global route behavior.

The navigation module now treats the drawer as a set of tabs rather than separate modes. This gives the main menu, inbox or AI history, and settings a shared shell while keeping route selection in the app and domain modules. AppNavigationDrawer.tsx NavigationDrawerTabbedContent.tsx

References: packages/…/folderStructure.json• L1-62 packages/…/WorkspaceAppProviders.tsx• L47-112 packages/…/AppNavigationDrawer.tsx• L18-47 packages/…/NavigationDrawerTabbedContent.tsx• L18-41

Communication experiences

Activities connect records to email, calendar, files, notes, tasks, and message threads. A thread can use a built-in channel or an application channel. The client resolves the channel, sends the message, and refreshes the record timeline after the server accepts it.

The inbox adds a workspace view for the same conversation model. It supports source-based thread lists, split or full-page reading, direct messages, selection, keyboard movement, and pagination. Shared chat presentation keeps files, reactions, voice notes, receipts, restricted content, and live updates consistent across record threads, inbox conversations, and AI conversations. InboxPage.tsx ChatMessageVoiceNote.tsx

Email composition keeps its draft and recipient state scoped to the active composer. This lets a member move between surfaces without mixing recipients or restoring a draft into the wrong message. useComposerDraft.ts EmailRecipientsProvider.tsx

References: packages/…/useEmailThread.ts• L24-231 packages/…/InboxPage.tsx• L133-228 packages/…/ChatMessageVoiceNote.tsx• L1-180 packages/…/useComposerDraft.ts• L1-120 packages/…/EmailRecipientsProvider.tsx• L1-120

AI experiences

AI chat connects workspace members to assistants, direct recipients, channels, records, browser context, and optional files. The inbox and full-page routes share the same thread model. Each mounted chat surface has an instance identity, a current thread, and a callback for changing that thread.

The runtime fetches messages and opens a stream for each thread that is open in a registered instance. A new thread starts with scoped state and becomes a real thread when the first selection succeeds. A message send can show an optimistic message, accept a streamed reply, and restore the draft or files after a failure. AI can also ask for approval before it changes records. AiChatProvider.tsx AiChatRuntimeEffects.tsx AiChatInstance.tsx AiChatRecordApprovalDeck.tsx

Agents and workflows are workspace product areas. Their list and detail surfaces use the same route, command, permission, and live-update contracts as other workspace pages. Agent pages show run status and insights. Workflow details support version choice, editing or read-only views, run lists, and run insights.

References: packages/…/AiChatProvider.tsx• L8-21 packages/…/AiChatRuntimeEffects.tsx• L9-29 packages/…/AiChatInstance.tsx• L17-39 packages/…/useAiChatPageThreadId.ts• L7-12 packages/…/AiChatRecordApprovalDeck.tsx• L23-177 packages/…/AgentCoreIndexPage.tsx• L39-140 packages/…/WorkflowCoreShowPage.tsx• L50-225

Embedded application boundary

Installed applications can add UI and content to product surfaces. The client loads application content through the metadata API and runs it with scoped access data, execution context, server URLs, and approved media access.

The application boundary checks access before it loads content. Managed frames restrict media permission to approved origins and requested capabilities. Settings lets a member inspect application connections, connect with an API key, reconnect or remove a connection, and install applications after permission checks. Application health checks are part of this connection lifecycle rather than a separate product surface.

References: packages/…/FrontComponentRenderer.tsx• L60-105 packages/…/ManagedIframe.tsx• L6-56 packages/…/SettingsApplicationConnectWithApiKey.tsx• L24-145 packages/…/SettingsApplicationConnectionDetail.tsx• L80-181 packages/…/SettingsApplicationConnectionsSection.tsx• L22-129 packages/…/applicationHealthCheckResultFragment.ts• L1-80

Product state

Product state follows its lifetime and scope. Jotai atoms hold browser state across components. Apollo holds fetched server data. The metadata store holds the workspace description that metadata-driven routes need. Route and component state holds one visit or surface.

State scopes

State follows the product scope that owns it. Workspace state can affect route selection and service setup. Component state stays with one page or panel. Shared state is used when another module must observe the same product fact.

State groupScope and purpose
Client configurationSelects runtime server and domain behavior before route selection
Identity and workspaceTracks user, workspace, member, session, access, billing, applications, and AI policy
Metadata storeHolds objects, fields, views, layouts, navigation, applications, agents, and permissions
Apollo cacheShares fetched GraphQL results across product modules
Route and component stateKeeps selections, panels, dialogs, drafts, and editor modes aligned with the active surface
Live event and job stateApplies server changes and background-work progress in the browser
Experience preferencesKeeps language, theme, time zone, number format, and display choices aligned with the member

The current workspace state is durable browser state because route choice and workspace services need it during a new load. It also carries product policy such as feature flags, access settings, installed applications, model choices, and AI data rules. currentWorkspaceState.ts

References: packages/…/metadataStoreState.ts• L4-66 packages/…/currentWorkspaceState.ts• L8-74 packages/…/UserMetadataProviderInitialEffect.tsx• L69-174 packages/…/agentChatThreadListFamilyState.ts• L1-10 packages/…/agentChatThreadReadPositionsFamilyState.ts• L1-10

Record and conversation identity

Record identity is the link between a URL, a visible surface, and the data shown inside it. Record pages, side panels, inbox threads, and AI threads use the same identity contract so a member can move a conversation between surfaces without changing what it represents. AiChatThreadPageContent.tsx

The route supplies a valid thread identifier when one exists. A new-thread identifier is held separately until a thread is created or selected. The client then loads the thread only when it is not already known and keeps message fetches and streams tied to the open chat instance. getAiChatPageThreadId.ts AiChatPageThreadLoadEffect.tsx

Record indexes follow the same rule for views. Filters, grouping, visible records, and selection stay together so table, list, board, and calendar surfaces show the same result set in different forms. RecordIndexContainer.tsx RecordGroupTabs.tsx

References: packages/…/AiChatThreadPageContent.tsx• L16-43 packages/…/getAiChatPageThreadId.ts• L7-30 packages/…/AiChatPageThreadLoadEffect.tsx• L14-44 packages/…/RecordIndexContainer.tsx• L34-82 packages/…/RecordGroupTabs.tsx• L56-184

Workspace progress

Getting started is a workspace progress experience. It reads enabled steps and completed actions from the metadata API, selects the next useful step, and lets the member complete, skip, snooze, or return to a step. A failed action keeps the page able to retry instead of losing progress. GettingStartedPageContent.tsx

On mobile, this progress experience shares the home surface with navigation and the inbox entry point. Desktop users go to the normal default home page instead of rendering the mobile home surface. MobileHomePage.tsx

References: packages/…/GettingStartedPageContent.tsx• L96-177 packages/…/useGettingStartedProgress.ts• L6-23 packages/…/MobileHomePage.tsx• L32-55

Live workspace state

The workspace client keeps an event channel for changes that must reach an open browser. Active pages and tracked jobs declare the updates they need. Browser handlers map server events to Apollo, the metadata store, or feature state.

When a live change reaches the browser, the client follows a structured sequence:

  1. Workspace providers start the event client.
  2. Active pages and jobs declare the updates they need.
  3. The client adds or removes subscriptions as surfaces mount or unmount.
  4. The server sends record, metadata, application, agent, workflow, message, or job events.
  5. Browser handlers update the matching state.
  6. The affected page renders new data or settles the background action.

This diagram shows how a server change reaches a workspace page.

flowchart LR
  Page[Active page or job] --> Subscribe[Event subscription]
  Subscribe --> Stream[Server event stream]
  Stream --> Mapping[Browser event mapping]
  Mapping --> Apollo[Apollo cache]
  Mapping --> Metadata[Metadata store]
  Mapping --> Feature[Feature state]
  Apollo --> Render[Rendered page]
  Metadata --> Render
  Feature --> Render

References: packages/…/WorkspaceAppProviders.tsx• L56-105 packages/…/SSEQuerySubscribeEffect.tsx• L71-277 packages/…/MetadataStoreSSEEffect.tsx• L22-75 packages/…/useListenToCoreWorkflowRunEvents.ts• L1-120

AI policy state

Workspace privacy settings control which AI providers may process workspace requests. The client compares the policy with available model data and warns when no model meets the rule.

The policy is part of product state. A policy change updates workspace state and the set of models that chat can use. When that set is empty, the client pauses AI instead of sending a request that violates the workspace rule. Settings also separates AI behavior for direct messages and the global inbox. SettingsAiBehaviorSection.tsx

References: packages/…/SettingsPrivacyAiDataProcessing.tsx• L41-140 packages/…/getWorkspaceAiDataPolicy.ts• L5-21 packages/…/findAiModelTierForDataPolicy.ts• L5-24 packages/…/SettingsAiBehaviorSection.tsx• L38-123 packages/…/currentWorkspaceState.ts• L43-52

Child experiences

This page gives the system view. Read the child pages for the visible product areas that carry most of the workspace behavior:

Application shell

The application shell is the shared workspace frame around product pages. It owns navigation, layout, commands, localization, settings entry points, and common error behavior. See Client application shell and navigation for that flow.

References: packages/…/DefaultLayout.tsx• L65-91 packages/…/AppNavigationDrawer.tsx• L18-47 packages/…/useSettingsNavigationItems.tsx• L53-202

Record experiences

Record experiences turn workspace metadata and server data into lists, boards, calendars, record pages, activities, and page layouts. They share record state and cache rules so a record opened from one surface remains understandable in another. See Client record and productivity experiences for the product flow.

References: packages/…/RecordTableContent.tsx• L45-167 packages/…/generateRecordCacheFragment.ts• L12-64 packages/…/WidgetContentRenderer.tsx• L1-160

Administrative log console

The administrative log console gives an authorized user one place to inspect system activity. It can show record changes, security events, application logs, webhooks, page views, and usage events. Filters and detail views change with the selected source. See Administrative log console for the console flow.

References: packages/…/LogConsoleSources.tsx• L67-345 packages/…/LogConsole.tsx• L257-300 packages/…/LogConsoleTable.tsx• L89-256

Change checklist

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

  • Generated core, metadata, and admin GraphQL types must stay aligned with the operations used by the workspace, settings, inbox, conversation pages, and admin surfaces.
  • Route changes for inbox or legacy AI URLs must preserve full-page, split-view, side-panel, new-thread, and redirect URL state.
  • Navigation tab changes must keep route mode, feature flags, permissions, unread counts, and mobile behavior aligned.
  • Changes to record or thread identity must preserve the shared behavior used by normal records, inbox threads, and AI chat instances.
  • Changes to application connections must keep provider scope, permission checks, health status, return paths, and connection actions aligned.
  • Changes to AI policy or behavior settings must keep model access and direct-message or inbox participation rules consistent.
  • Live event changes must update the correct Apollo, metadata, or feature state without applying a late event to another workspace surface.

Important failure modes

TriggerConsequenceGuard
Client configuration is missingThe workspace cannot mount a valid route treeHold workspace mounting until configuration is loaded
A stale session response completes after a newer session startsThe client can clear valid identity and send the member to sign-inCheck the response against the active session before changing identity
Metadata changes without cache invalidationRecord pages can use an old field shapeDiscard affected results when live metadata events arrive
A thread route loses its source, selected ID, or new-thread stateThe inbox can show the wrong pane or lose a draftKeep route state and chat atoms scoped to the active surface
A legacy AI URL is treated as a normal record URLThe member can miss the inbox destination or open the wrong thread surfaceResolve valid thread IDs and apply the compatibility redirect before rendering
No AI model meets the workspace data policyA request could violate workspace privacy rulesPause AI and show the policy warning when no model is allowed
An application connection lacks the required permission or credentialsInstall or connect actions fail or expose an unusable connectionCheck permission, provider scope, health, and authorization state before showing the action
A live event is applied to the wrong surfaceA page can show data from another record or requestScope subscriptions and short-lived state by workspace, record, thread, or job

Key files

FileWhy to read it
packages/…/index.tsxBrowser startup boundary
packages/…/App.tsxShared public and workspace provider boundary
packages/…/DomainShell.tsxHost and workspace route choice
packages/…/WorkspaceAppProviders.tsxSigned-in services, chat runtime, and live events
packages/…/createWorkspaceRouteObjects.tsxWorkspace route map and lazy product areas
packages/…/SettingsRoutes.tsxProtected settings route map and legacy redirects
packages/…/graphql.tsGenerated core API operations and result types
packages/…/graphql.tsGenerated workspace and metadata API contracts
packages/…/graphql.tsGenerated privileged administration API contracts
packages/…/InboxPage.tsxShared conversation list and reading surface
packages/…/LegacyAiChatPage.tsxCompatibility route for older AI chat URLs
packages/…/AiChatThreadPageContent.tsxAI chat as a record experience
packages/…/AiChatInstance.tsxPer-surface chat identity and thread lifecycle
packages/…/RecordShowPageShell.tsxCommon full-page and side-panel record surface
packages/…/currentWorkspaceState.tsDurable workspace product state
packages/…/metadataStoreState.tsWorkspace metadata state
packages/…/SSEQuerySubscribeEffect.tsxLive server-to-client state flow