Client application shell and navigation
The client application shell is the shared workspace frame for the Twenty web app. It turns server configuration and workspace metadata into routes, navigation, layouts, commands, localization, settings, and error recovery. For the wider client model, see Web client application; for product pages inside the shell, see Client record and productivity experiences; for log views, see Log console.
Runtime boundary
The browser restores local metadata, mounts shared providers, and then selects the root or workspace experience. Workspace providers also own shared record forms and side-panel flows, so a page can open a focused edit surface without leaving the current workspace.
This diagram shows the startup boundary and the route choice that follows it.
flowchart TD
A[Browser entry point] --> B[Restore metadata cache]
B --> C[Shared application providers]
C --> D[Load client configuration]
D --> E{Domain and workspace state}
E -->|Default domain| F[Root routes]
E -->|Workspace domain| G[Workspace routes]
F --> H[Auth and onboarding]
G --> I[Workspace shell]
Configuration describes how the instance can run. Metadata describes what the current workspace exposes, such as objects, views, layouts, navigation items, applications, and commands. The shell waits for the state needed by each route before it renders that route.
The startup boundary also restores validated URL state for return paths, billing checkout, and partner attribution. The active locale supplies text direction to shared controls. A routed flow scope keeps temporary form and UI state local to an editor or route flow on one surface.
References: packages/…/index.tsx• L1-31 packages/…/App.tsx• L20-51 packages/…/LocaleDirectionProvider.tsx• L13-21 packages/…/DomainShell.tsx• L14-40 packages/…/WorkspaceAppProviders.tsx• L46-111 packages/…/useInitializeQueryParamState.ts• L13-74 packages/…/RoutedFlowStateScopeContext.ts• L1-6
Client configuration
Client configuration is the instance-wide contract that lets the browser adapt to its server. The client loads it from the configured server base URL and shares it with authentication, domains, billing, onboarding, integrations, analytics, support, and feature access.
The configuration load controls the first major branch in the shell:
- While it is pending, the browser shows a loader.
- If it fails, normal routing stops and the shell shows a full-screen back-end error with a reload action.
- When it is ready, feature and service state can shape routes and settings visibility.
The contract covers connection and identity, workspace behavior, and optional services. Public feature flags also have translated descriptions in admin settings. This keeps admin controls and client behavior tied to the same server state.
References: packages/…/getClientConfig.ts• L1-16 packages/…/ClientConfig.ts• L15-53 packages/…/useClientConfig.ts• L152-257 packages/…/ClientConfigProvider.tsx• L6-23 packages/…/SettingsAdminFeatureFlagMetadata.ts• L4-91
Apollo data access
Apollo is the client data layer for GraphQL, metadata GraphQL, REST-backed operations, file uploads, and streaming responses. Shared providers create the metadata client, while workspace routes add clients for core workspace data and the admin panel.
Requests carry the current locale, app version, and session generation. GraphQL and REST operations share cookie-based session handling, retry rules, and authentication response handling. A delayed request from an older session cannot clear a newer session.
The client keeps visible records and lists aligned during writes through optimistic cache changes. The cache and Jotai application state have different roles:
| State system | Main purpose |
|---|---|
| Apollo cache | Hold query results and support responsive reads and updates. |
| Jotai application state | Hold session, workspace, configuration, UI, and shell state. |
| Routed-flow state | Keep temporary editor and surface state local to its route flow. |
Persistent entity state can remain shared across surfaces. Drafts and component state stay inside their routed flow. Cursor encoding keeps a record identifier with its optional position so record navigation can carry stable page context.
References: packages/…/useApolloFactory.ts• L26-137 packages/…/apollo.factory.ts• L83-137 packages/…/apollo.factory.ts• L197-288 packages/…/triggerCreateRecordsOptimisticEffect.ts• L37-205 packages/…/triggerUpdateRelationsOptimisticEffect.ts• L53-105 packages/…/encodeCursor.ts• L6-19 packages/…/ApolloCoreProvider.tsx• L5-17 packages/…/useApolloAdminClient.ts• L7-19
Metadata store
The metadata store gives the shell a local, workspace-aware description of the product surface. It persists metadata in the browser and tracks which collections are ready or stale.
On a provisioned workspace, the client loads the minimum object and view metadata first. Collection hashes then identify server changes, so later loads can fetch only stale groups. Live metadata events keep the local description current. Object definitions arrive with their fields and indexes. Views arrive with their filters and sorts. Page layouts arrive with their tabs and widgets.
Navigation, the default home path, layouts, command items, front components, applications, and object routes depend on this state. A minimum metadata gate prevents a workspace route from rendering before its required state is ready.
References: packages/…/metadataStoreStorage.ts• L1-8 packages/…/metadataStoreState.ts• L4-65 packages/…/useLoadMinimalMetadata.ts• L16-101 packages/…/useLoadStaleMetadataEntities.ts• L25-176 packages/…/MetadataStoreSSEEffect.tsx• L11-68 packages/…/MinimalMetadataGate.tsx• L8-19
Route selection
The shell selects a root route tree or a workspace route tree from the current domain and workspace state. Root routes serve sign-in and account transition paths. Workspace routes serve the main app, onboarding, settings, native workflow and agent pages, and not-found behavior.
Workspace routes carry a surface contract. The contract states whether a location belongs on the main surface, the side panel, or both. The shell filters route definitions for the active surface and gives side-panel flows their own route context. An unavailable side-panel location stays inside the panel instead of replacing the main page.
Route selection also enforces account state. Missing workspaces return to sign-in. Incomplete onboarding moves to setup. A suspended workspace keeps only allowed billing or profile settings available. Completed onboarding returns to a safe saved path or the default home.
The default home path uses the current user, permissions, device type, navigation metadata, available views, and the initial-object-view feature flag. Desktop normally opens the first usable object-backed navigation item. Mobile uses mobile home. A user with no readable object falls back to profile settings.
When the location changes, the shell updates the active page layout and clears state that belongs to the old flow. It also manages side-panel content, record selection, focus, safe sign-in return paths, and log-console full-screen state.
This diagram shows how one route definition becomes a surface-specific route and then a rendered flow.
flowchart LR
A[Workspace route definitions] --> B{Surface contract}
B -->|Main| C[Main route tree]
B -->|Side panel| D[Side-panel route tree]
C --> E[Main workspace surface]
D --> F[Routed flow scope]
F --> G[Side-panel surface]
References: packages/…/SettingsRoutes.tsx• L45-105 packages/…/createWorkspaceRouteObjects.tsx• L87-235 packages/…/getWorkspaceRouteObjectsForSurface.ts• L7-53 packages/…/isWorkspaceLocationAvailableOnSurface.ts• L7-38 packages/…/WorkspaceRoutes.tsx• L9-40 packages/…/WorkspaceRouteUnavailable.tsx• L16-27 packages/…/PageChangeEffect.tsx• L53-182 packages/…/useDefaultHomePagePath.ts• L22-139 packages/…/getFirstNavigationMenuItemLink.ts• L22-71 packages/…/useDefaultHomePagePath.test.ts• L224-420
Layout structure
The default workspace layout is the stable frame around most product pages. It combines the navigation drawer, main page area, mobile navigation, side panels, file preview, keyboard help, layout controls, and page-level error isolation.
The main content can show a side panel on desktop or a mobile command surface on small screens. Each side-panel page has its own identity, so drafts and requests stay with the open flow. Scroll state is separate for each surface and path.
Tabs adapt to the available width. Desktop shows the tabs that fit and moves the rest into a More menu. Mobile keeps the tabs in a horizontal scroll area. A URL hash controls a tab only when the current surface owns that route; otherwise the surface uses its local or default tab.
Shared layers place headers, drawers, panels, dialogs, dropdowns, and toasts above the page that owns them. File fields use one preview decision point: the attachment-preview setting and download permission decide whether a file opens in the global preview or downloads. A gallery keeps its file order and supports previous and next navigation.
Shared field displays keep records readable without changing their meaning. They provide tags, phone links, linked text, country and currency controls, and member time formats. A compact audio-bar indicator gives AI and audio surfaces a common visual cue.
Dialog surfaces
Dialog surfaces provide focused confirmation and form interactions without changing the page route. Each dialog owns its focus, keyboard actions, dismissal rules, and identity so nested or parallel dialogs do not share state.
References: packages/…/DialogInstance.tsx• L19-145 packages/…/ConfirmationDialog.tsx• L31-145 packages/…/useDialog.tsx• L9-98
Dropdown surfaces
Dropdown surfaces present short menus near a trigger while keeping the menu inside usable bounds. They share rules for mobile limits, modal containment, outside clicks, Escape, focus, and portal layers.
References: packages/…/Dropdown.tsx• L52-260 packages/…/DropdownInternalContainer.tsx• L52-173 packages/…/SelectableList.tsx• L19-69
Field display surfaces
Field display surfaces turn stored values into readable controls. They keep file preview, download, gallery navigation, links, tags, phone values, and locale formats consistent across records, side panels, and settings.
References: packages/…/GlobalFilePreviewModal.tsx• L28-83 packages/…/FilePreviewDialog.tsx• L72-186 packages/…/useOpenFilePreview.ts• L18-46 packages/…/filePreviewGalleryFilesState.ts• L1-7 packages/…/getFilePreviewGalleryNavigation.ts• L5-41 packages/…/MultiSelectDisplay.tsx• L20-52 packages/…/PhoneDisplay.tsx• L14-50
References: packages/…/DefaultLayout.tsx• L65-91 packages/…/MainAppLayoutWithSidePanel.tsx• L45-60 packages/…/PageHeader.tsx• L97-153 packages/…/TabList.tsx• L67-245 packages/…/useTabListActiveTabId.ts• L14-41 packages/…/useScrollRestoration.ts• L8-81 packages/…/SidePanelPageInfo.tsx• L1-120 packages/…/AiModelTierIndicator.tsx• L1-11
Navigation model
Navigation turns workspace metadata and permissions into paths that a user can reach. The drawer now uses tabs as its top-level destinations: Home, Inbox or AI, and Settings. Workspace-defined navigation tabs can appear below Home and can select a focused menu view.
Desktop keeps the tab switcher and fixed actions in the drawer. The scroll area then shows favorites, workspace sections, Getting started, or the selected workspace tab. Mobile uses Home as the main surface and leaves tab switching to the mobile navigation bar. The drawer remains available for mobile settings.
The active tab comes from the route when the user is in settings or AI. In other locations, stored tab state keeps chat history visible beside normal navigation. AI or Inbox content stays mounted when permitted, so switching tabs can preserve its state. Layout customization disables tabs that would leave the editing flow and shows why they are unavailable. Unread Inbox work appears on an inactive tab.
Navigation items can target an object, view, record, page layout, native page, link, or folder. The shell removes targets whose metadata is missing or inactive and checks readable object permissions before it builds a link. An object item opens its last usable view or falls back to the first selectable view or object index.
The drawer supports workspace switching, search, folders, favorites, Getting started, and workspace sections. Switching workspaces carries the current path when the target supports it. The navigation editor keeps workspace changes as a layout draft until save. Its actions also let an editor move an item to a folder or tab and manage a section without leaving the draft flow. Personal favorites remain user-owned items.
The log-console switch is a separate navigation control. It clears selected-log and full-screen state when the console opens. The mobile bar becomes inert while a side panel or full AI chat is open and follows page scroll direction so it does not cover content.
This diagram shows how route state and workspace metadata choose the visible navigation surface.
flowchart TD
A[Route and workspace state] --> B[Active drawer tab]
B -->|Home| C[Workspace navigation]
B -->|Inbox or AI| D[Conversation surface]
B -->|Settings| E[Settings navigation]
C --> F[Metadata and permission checks]
F --> G[Reachable links]
References: packages/…/AppNavigationDrawer.tsx• L18-47 packages/…/MainNavigationDrawerContent.tsx• L9-25 packages/…/MainNavigationDrawerFixedRows.tsx• L14-43 packages/…/MainNavigationDrawerScrollableItems.tsx• L50-79 packages/…/MainNavigationDrawerTab.tsx• L90-158 packages/…/MainNavigationDrawerTabSwitcher.tsx• L54-177 packages/…/NavigationDrawerHeader.tsx• L58-101 packages/…/NavigationDrawerModeTransitionEffect.tsx• L16-68 packages/…/NavigationDrawerTabbedContent.tsx• L18-41 packages/…/useActiveNavigationDrawerTab.ts• L12-32 packages/…/useNavigationDrawerTabs.ts• L30-66 packages/…/useSwitchNavigationDrawerTab.ts• L28-133 packages/…/AppNavigationDrawer.test.tsx• L55-88 packages/…/en.po• L15382-15389 packages/…/en.po• L19318-19342 packages/…/en.po• L24896-24900 packages/…/en.po• L26509-26525
Commands and shortcuts
Commands provide a fast path to search, navigation, AI, and actions that are also available through the UI. A command can belong to a page, object, selection, view, or layout. The shell checks the current context before it displays or runs the command.
Commands use three action forms:
- Navigation: Move to a path or to an object index.
- Headless action: Run with the current view, filters, selected records, metadata, and side-panel state.
- Front component: Open a configured side-panel experience with the selected record as context.
Pinned actions stay in a footer when they fit and move into a menu when they do not. Global shortcuts open common surfaces while respecting focused editors, so text controls keep keys needed for editing. Workflow commands can open a side-panel step with the current object, selection, view, and workflow context.
This diagram shows how server-defined command metadata becomes a context-aware action.
flowchart TD
A[Command metadata] --> B[Context and availability checks]
B --> C{Command kind}
C -->|Navigation| D[Change route]
C -->|Headless action| E[Build action context]
C -->|Front component| F[Open side-panel experience]
E --> G[Run command]
References: packages/…/CommandMenuContextProviderContent.tsx• L29-90 packages/…/useCommandMenuItemClick.ts• L17-124 packages/…/buildHeadlessCommandContextApi.ts• L23-137 packages/…/CommandMenuItemRenderer.tsx• L41-224 packages/…/WidgetCommandMenuItem.ts• L1-15 packages/…/GotoHotkeysEffectsProvider.tsx• L13-47 packages/…/useWorkflowCommandMenu.test.tsx• L118-219 packages/…/useGlobalHotkeys.ts• L16-82
Localization and settings
Localization covers translated interface text, text direction, workspace metadata translations, and member display preferences. The app activates a locale before it renders its provider tree. Locale catalogs and generated locale data move together, and the active member locale travels with API requests.
Member format preferences control time zone, date format, time format, number format, and calendar start day. The client detects system defaults when a member has no choice. Settings navigation then uses login state, permissions, billing state, service availability, and feature flags to show the controls a user can use.
Settings are grouped into user, workspace, and instance controls. Billing, developer tools, applications, AI, admin tools, support, and app preferences appear only when their service and access state allows them. A denied route stays in the settings frame or side panel as an unavailable state rather than exposing a broken page.
Settings pages can also target a section with a URL hash. The shell resolves the active tab before effects run, scrolls to a targeted section while late content changes its position, and stops following once the user starts to scroll.
The English catalog also carries the labels used by the navigation editor. Recent entries cover moving an item to a folder or tab and section actions, so the catalog remains part of the navigation editor contract.
References: packages/…/useSettingsNavigationItems.tsx• L53-202 packages/…/SettingsNavigationDrawerItems.tsx• L82-129 packages/…/SettingsNavigationDrawerItem.tsx• L14-43 packages/…/SettingsSectionAnchor.tsx• L45-74 packages/…/SettingsSectionAnchorScrollEffect.tsx• L13-36 packages/…/watchSettingsSectionAnchorScroll.ts• L11-51 packages/…/useSettingsActiveTabId.ts• L8-27 packages/…/LocaleDirectionProvider.tsx• L13-21 packages/…/en.po• L15382-15389 packages/…/en.po• L19318-19342 packages/…/en.po• L24896-24900 packages/…/en.po• L26509-26525 packages/…/en.ts• L1-20 packages/…/SettingsDatePickerInput.tsx• L73-194
Account settings
Account settings connect the workspace to Google, Microsoft, and IMAP/SMTP/CalDAV services. The page offers only providers enabled by client configuration and routes each provider to the matching OAuth or protocol form.
Members can complete pending setup, open email or calendar settings, reconnect an eligible provider, disconnect an account while retaining synced data, or delete an account with its synced data. Protocol forms save only configured protocols and keep an existing password when an edit does not replace it.
Legacy account paths redirect to app preferences while preserving the query and hash. This keeps old links usable while the newer app-preference surface becomes the place for application connections and account settings.
References: packages/…/SettingsAccountsListEmptyStateCard.tsx• L22-76 packages/…/SettingsAccountsRowDropdownMenu.tsx• L38-208 packages/…/useAccountsConfigurationCompletionPath.ts• L6-25 packages/…/useImapSmtpCaldavConnectionForm.ts• L65-234 packages/…/useTriggerProviderReconnect.ts• L8-38 packages/…/SettingsLegacyAccountsRedirect.tsx• L4-16 packages/…/AppPreferencesPathByLegacyAccountsPath.ts• L1-19
App preferences
App preferences give members one place to see installed apps and the personal accounts those apps use. Connection rows show status and support reconnect or remove actions. A provider without usable credentials shows a setup warning instead of starting authorization.
Connection setup uses the provider type to choose an API-key page or OAuth. The flow keeps a validated return path, refetches the affected account lists, and returns to the app’s settings after success. Installed app status can be refreshed separately, and an app can run a health check after its variables are saved.
Health checks keep the latest result per application and show a translated status banner. An app-supplied action is used only when its path is a safe internal workspace path, so a health message cannot send the member to an external location.
References: packages/…/getApplicationsWithPreferences.ts• L15-72 packages/…/SettingsAppPreferencesConnectionsTab.tsx• L23-99 packages/…/MyApplicationHealthCheckRunner.ts• L8-14 packages/…/runMyApplicationHealthCheck.ts• L4-11 packages/…/useAccountsSettingsBreadcrumbLink.ts• L8-16 packages/…/SettingsApplicationsInstalledAppsSection.tsx• L15-55 packages/…/SettingsApplicationHealthCheckBanner.tsx• L15-49 packages/…/SettingsApplicationHealthCheckEffect.tsx• L10-24 packages/…/useRunApplicationHealthCheck.ts• L10-70 packages/…/useSaveApplicationVariablesAndRecheckHealth.ts• L4-26 packages/…/getApplicationHealthBanner.ts• L12-50
Billing settings
Billing settings present plan access, subscription state, workspace spend, resource credits, and limits as one user-facing view. They support plan changes, payment recovery, credit packages, and workspace or spender limits.
The admin billing view also records billing arrangements, which are deliberate exceptions to the normal plan. An operator can add free or committed seats, a workspace credit allowance, or other server-provided arrangement types. Each arrangement shows its reason, status, dates, operator, and detail, and active or scheduled arrangements can be ended rather than edited.
Usage limits combine server defaults with optional workspace overrides. The editor preserves the unit scale used for display, validates period and burst values, and lets an operator reset an override to the default. Billing arrangements and limit changes refetch the related admin views so the displayed subscription, usage, and history stay aligned.
References: packages/…/SettingsBillingSubscriptionInfo.tsx• L124-217 packages/…/SettingsAdminWorkspaceBillingContent.tsx• L125-415 packages/…/SettingsAdminWorkspaceBillingArrangementsSection.tsx• L56-245 packages/…/SettingsAdminWorkspaceBillingArrangementModal.tsx• L64-296 packages/…/SettingsAdminWorkspaceBillingArrangementDetailsModal.tsx• L54-147 packages/…/workspaceBillingArrangements.ts• L5-40 packages/…/createWorkspaceBillingArrangement.ts• L3-27 packages/…/endWorkspaceBillingArrangement.ts• L3-15 packages/…/formatAdminBillingArrangementDetails.ts• L33-110 packages/…/formatAdminBillingArrangementEndDate.ts• L10-20 packages/…/parseAdminBillingArrangementCreditAllowance.ts• L3-17 packages/…/parseAdminBillingArrangementSeats.ts• L1-7 packages/…/SettingsAdminWorkspaceUsageLimitModal.tsx• L54-336
Developer settings
Developer settings provide authenticated tools for API keys, webhooks, GraphQL, REST, applications, MCP clients, and the Twenty CLI. The shell keeps short-lived playground access in memory and validates webhook and external setup inputs before it sends them.
MCP servers are remote Model Context Protocol endpoints that expose tools to agents. The settings surface is visible only when the feature and API-key or webhook permission allow it. Members can add or edit a server, remove it, and sync its tool list; the form requires an HTTP or HTTPS URL and a safe tool name.
The detail route treats an invalid or missing server as not found. A tool sync reports the server result and does not replace a useful error with a success message when the server returns a sync error.
References: packages/…/SettingsDevelopersTabs.ts• L1-9 packages/…/useOpenPlayground.ts• L18-63 packages/…/SettingsDevelopersWebhookForm.tsx• L38-257 packages/…/SettingsMcpServersSection.tsx• L14-42 packages/…/SettingsMcpServerDetail.tsx• L16-51 packages/…/SettingsMcpServerNewForm.tsx• L16-47 packages/…/SettingsMcpServerEditForm.tsx• L23-81 packages/…/useCreateMcpServer.ts• L12-50 packages/…/useSyncMcpServerTools.ts• L11-48 packages/…/mcpServerFormSchema.ts• L7-36 packages/…/SettingsMcpSetupCard.tsx• L99-163
Admin settings
Admin settings provide instance-level control over workspaces, applications, AI, feature flags, usage limits, billing arrangements, configuration variables, queues, credits, and server access. These pages use a separate admin data client so instance data stays distinct from normal workspace data.
Role settings keep edits in a routed draft until save. A role save combines basic role changes with permission flags, object and field permissions, row-level rules, and role assignments. Record filters in the editor become row-level predicates and groups, while the save flow restores broad object grants when a filtered rule no longer applies.
The row-level contract is now an upsert of rules that includes record grants and predicate trees. This keeps the permissions attached to a filtered object in one save path rather than saving filters and grants as unrelated state.
Select-field settings distinguish active options and application-owned defaults from options that a user can change. This keeps app-defined choices available while still allowing workspace customization where the model permits it.
References: packages/…/useApolloAdminClient.ts• L7-19 packages/…/SettingsAdminWorkspaceBillingArrangementsSection.tsx• L75-136 packages/…/useUpsertRowLevelPermissionRulesMutation.ts• L1-15 packages/…/upsertRowLevelPermissionRulesMutation.ts• L7-31 packages/…/buildRowLevelPermissionRulesInput.ts• L19-113 packages/…/useSaveDraftRoleToDB.ts• L226-478 packages/…/useRecordLevelPermissionSyncToDraftRole.ts• L24-125 packages/…/recordLevelPermissionPredicateConversion.ts• L20-163 packages/…/SettingsDataModelFieldSelectForm.tsx• L1-200 packages/…/normalizeSelectOptions.ts• L1-100
Security settings
Security settings control sign-in rules, profile edit access, retention, and workspace embedding. Allowed origins define which sites may embed the workspace. Per-origin media permissions define whether an embedded site may request microphone or camera access.
Origins must be plain HTTP or HTTPS origins without a path or wildcard. Media entries require HTTPS and at least one capability. Changes to media access apply to open tabs after a reload.
References: packages/…/SettingsSecuritySettings.tsx• L57-281 packages/…/SettingsSecurityIframeOrigins.tsx• L36-149 packages/…/SettingsSecurityIframeMediaPermissions.tsx• L27-106 packages/…/SettingsSecurityIframeMediaPermissionForm.tsx• L39-138
Event logs
Event logs give an authorized workspace a filtered view of page views, application logs, and audit data. The page combines stored results with a live stream only when no active filters are present, and it lets the user pause or resume that stream.
Application logs require the instance log store. Other log types require the audit-log entitlement. When access is missing, the page shows the plan requirement inside the settings frame and offers the relevant billing or organization path.
References: packages/…/SettingsLogs.tsx• L92-232 packages/…/SettingsOpenLogConsoleCard.tsx• L14-51 packages/…/useSetIsLogConsoleEnabled.ts• L8-28
Error handling
Error handling uses boundaries at different shell levels so one broken page does not always remove the whole application. The root boundary covers failures in the application shell. The default layout adds full-screen and page-level boundaries for workspace content. The configuration provider handles failure before normal routing can start.
The shell reports unexpected exceptions and selected GraphQL failures to error reporting. It treats authentication failures as session events and known business errors as handled results. Query failures can show a translated or server-derived toast at the page that owns the query. A stale lazy-loaded bundle can trigger one guarded reload so a new bundle can be fetched without a reload loop.
Application settings and MCP pages use the same error-to-toast path for failed mutations. Health-check failures keep the last result only when the caller asks to preserve it, and stale health-check responses cannot replace a newer run.
References: packages/…/AppErrorBoundary.tsx• L50-130 packages/…/AppRootErrorFallback.tsx• L102-138 packages/…/AppPageErrorFallback.tsx• L8-21 packages/…/AppFullScreenErrorFallback.tsx• L17-30 packages/…/ClientConfigProvider.tsx• L6-23 packages/…/ToastOnQueryErrorEffect.tsx• L7-27 packages/…/useApolloFactory.ts• L50-103 packages/…/useRunApplicationHealthCheck.ts• L22-59 packages/…/useSyncMcpServerTools.ts• L18-46
Change checklist
When these files or sections are changed, remember to consider these:
- Changes to client configuration must stay aligned with its type, state mapping, startup gate, and feature or permission checks.
- Changes to metadata names or hashes must stay aligned with persistent storage, minimum loading, stale loading, and live updates.
- Changes to route paths or surface contracts must stay aligned with route trees, home selection, navigation links, settings redirects, and side-panel checks.
- Changes to session behavior must cover GraphQL and REST requests. An old request must not clear a newer session.
- Changes to navigation tabs must preserve route-derived active state, workspace menu tabs, unread state, layout-draft locks, mounted conversation content, and mobile behavior.
- Changes to command metadata must stay aligned with availability, pinning, shortcuts, engine keys, front components, and action context.
- Changes to file preview or tabs must preserve permission checks, gallery order, route-owned hashes, measured overflow, and mobile scrolling.
- Changes to account or app connections must preserve provider credentials, channel presence, sync controls, valid return paths, refetch scope, and partial-failure feedback.
- Changes to billing arrangements or usage limits must preserve server identifiers, status and end-date meaning, unit scaling, default-versus-override mapping, and related query refetches.
- Changes to role permissions must preserve routed drafts, feature gates, object grants, predicate groups, row-level rule IDs, and the combined save flow.
- Changes to select-field options must preserve the distinction between active, default, and application-owned options.
- Changes to locale catalogs must keep source catalogs and generated locale data aligned. Keep text direction and server request locale aligned with the active locale.
- Changes to settings section hashes must preserve synchronous tab selection, late-content scroll correction, reduced-motion behavior, and the stop condition after user scroll intent.
- Changes to application health checks must preserve per-application run identity and safe internal action paths.
- Changes to MCP server forms must preserve URL validation, tool-name rules, feature and permission gates, cache refresh, and sync error reporting.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Configuration is marked ready before its values reach shared state | The router can select a route without required instance settings. | Keep the configuration request and state mapping as one startup contract. |
| Metadata hashes or entity names do not match | The shell can show stale navigation or choose the wrong home path. | Keep collection names, grouped loads, key mapping, and hash updates consistent. |
| A route surface handle is missing or incorrect | A side-panel location can disappear or render in the wrong surface. | Keep route handles, surface filtering, and location checks consistent. |
| A navigation target points to missing or unreadable metadata | The sidebar can show a dead item or choose an unusable home path. | Validate active targets and readable object permissions before linking. |
| A navigation tab is selected from stale route or stored state | The drawer can show the wrong content or leave a settings route. | Let settings and AI routes take precedence and reset the navigation menu tab when switching surfaces. |
| A settings permission or feature flag is changed without its route rule | A user can see a link to a page that rejects the same user. | Keep settings navigation and route protection driven by the same access state. |
| A legacy or OAuth redirect drops its return path | A connection flow can reopen the wrong settings page. | Validate and preserve the return path through each redirect. |
| A workspace billing arrangement is ended without refetching its related view | Admin billing can show an ended arrangement as active or show stale credits. | Refetch arrangements and workspace billing data when the arrangement changes credits. |
| A usage-limit value is sent without its display scale | The stored limit differs from the value the operator saw. | Apply one shared scale for input parsing and display. |
| A provider starts authorization without usable credentials | Connection setup fails before the provider can authorize it. | Gate authorization on provider type and credential state. |
| A health-check response arrives after a newer run | An old result can replace the current app status. | Compare the response run ID with the stored run ID before applying it. |
| A health banner accepts an external action path | An app message can redirect a member outside the workspace. | Show an action only for a safe internal path. |
| A row-level predicate is saved without its related object grant | A role can show a filter but fail to grant access to the filtered records. | Rewrite object grants and row-level rules together. |
| A hidden navigation surface remains focusable | Keyboard users can reach controls that the current surface hides. | Apply inert state and remove hidden content from the tab order. |
| A tab hash is applied on a surface that does not own the route | A side-panel tab can change the main page selection. | Apply hash navigation only when the active surface owns the route. |
| A settings section moves while anchor loading is active | The requested section can stop below the viewport. | Follow resize changes until user scroll intent, then stop. |
| A file gallery uses stale or reordered files | Previous and next actions can open the wrong attachment. | Keep the gallery list and active file in shared preview state. |
| A live log stream is merged while filters are active | Real-time and historical results can mix incorrectly. | Enable the live stream only when no active filters exist. |
| A stale chunk reload has no cooldown | A failed deployment can cause repeated page reloads. | Store and check the stale-chunk reload timestamp. |
Key files
| File | Why to read it |
|---|---|
| packages/…/index.tsx | Shows the browser entry sequence and metadata cache restoration. |
| packages/…/App.tsx | Shows the provider boundary shared by all client routes. |
| packages/…/DomainShell.tsx | Shows how configuration and domain state select root or workspace routing. |
| packages/…/WorkspaceAppProviders.tsx | Shows the workspace provider tree and shared client state. |
| packages/…/DefaultLayout.tsx | Shows the workspace frame and page-level error boundaries. |
| packages/…/SettingsRoutes.tsx | Shows settings route groups, access gates, and redirects. |
| packages/…/PageChangeEffect.tsx | Shows the shell state changes that follow navigation. |
| packages/…/useClientConfig.ts | Shows how server configuration becomes client-wide behavior. |
| packages/…/apollo.factory.ts | Shows the shared data, auth, retry, session, and error contract. |
| packages/…/useLoadMinimalMetadata.ts | Shows the minimum metadata needed to start the workspace. |
| packages/…/useLoadStaleMetadataEntities.ts | Shows how stale metadata is grouped and applied. |
| packages/…/AppNavigationDrawer.tsx | Shows the desktop drawer, mobile split, and settings content boundary. |
| packages/…/MainNavigationDrawerTabSwitcher.tsx | Shows drawer tabs, workspace navigation tabs, unread state, and layout locks. |
| packages/…/NavigationDrawerTabbedContent.tsx | Shows how navigation and AI or Inbox content share the drawer. |
| packages/…/useActiveNavigationDrawerTab.ts | Shows how route and stored state choose the active tab. |
| packages/…/useDefaultHomePagePath.ts | Shows how permissions and metadata select the default destination. |
| packages/…/useCommandMenuItemClick.ts | Shows how context-aware commands choose their action. |
| packages/…/TabList.tsx | Shows route-aware tabs, overflow, and mobile scrolling. |
| packages/…/useOpenFilePreview.ts | Shows the decision between file preview and download. |
| packages/…/useSettingsNavigationItems.tsx | Shows how settings entries follow access and service state. |
| packages/…/SettingsAppPreferencesConnectionsTab.tsx | Shows app connection states and return paths. |
| packages/…/useRunApplicationHealthCheck.ts | Shows application health-check state and stale-result protection. |
| packages/…/SettingsMcpServerEditForm.tsx | Shows MCP server editing and tool management. |
| packages/…/SettingsAccountsRowDropdownMenu.tsx | Shows connected-account setup, reconnect, disconnect, and delete actions. |
| packages/…/SettingsAdminWorkspaceBillingContent.tsx | Shows the admin billing view and its related sections. |
| packages/…/SettingsAdminWorkspaceBillingArrangementsSection.tsx | Shows billing arrangement history and end flow. |
| packages/…/SettingsAdminWorkspaceUsageLimitModal.tsx | Shows workspace limit overrides and reset behavior. |
| packages/…/useSaveDraftRoleToDB.ts | Shows the combined role and permission save flow. |
| packages/…/buildRowLevelPermissionRulesInput.ts | Shows how filter state becomes row-level rule input. |
| packages/…/SettingsSectionAnchorScrollEffect.tsx | Shows hash-based settings section scrolling. |
| packages/…/AppErrorBoundary.tsx | Shows the shell-level error boundary and reporting path. |