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
Navigation tabs
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 surface | Product responsibility |
|---|---|
| Core | Records, activities, calendar, messages, views, AI chat data, and core product work |
| Metadata | Workspace structure, identity, settings, applications, agents, communication, and setup state |
| Admin | Privileged 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 group | Scope and purpose |
|---|---|
| Client configuration | Selects runtime server and domain behavior before route selection |
| Identity and workspace | Tracks user, workspace, member, session, access, billing, applications, and AI policy |
| Metadata store | Holds objects, fields, views, layouts, navigation, applications, agents, and permissions |
| Apollo cache | Shares fetched GraphQL results across product modules |
| Route and component state | Keeps selections, panels, dialogs, drafts, and editor modes aligned with the active surface |
| Live event and job state | Applies server changes and background-work progress in the browser |
| Experience preferences | Keeps 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:
- Workspace providers start the event client.
- Active pages and jobs declare the updates they need.
- The client adds or removes subscriptions as surfaces mount or unmount.
- The server sends record, metadata, application, agent, workflow, message, or job events.
- Browser handlers update the matching state.
- 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:
- Client application shell and navigation explains configuration, providers, navigation, layout, commands, localization, settings, and error handling.
- Client record and productivity experiences explains records, activities, dashboards, files, imports, editors, maps, and page layouts.
- Administrative log console explains the administrative log experience and its role in inspecting system activity.
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
| Trigger | Consequence | Guard |
|---|---|---|
| Client configuration is missing | The workspace cannot mount a valid route tree | Hold workspace mounting until configuration is loaded |
| A stale session response completes after a newer session starts | The client can clear valid identity and send the member to sign-in | Check the response against the active session before changing identity |
| Metadata changes without cache invalidation | Record pages can use an old field shape | Discard affected results when live metadata events arrive |
| A thread route loses its source, selected ID, or new-thread state | The inbox can show the wrong pane or lose a draft | Keep route state and chat atoms scoped to the active surface |
| A legacy AI URL is treated as a normal record URL | The member can miss the inbox destination or open the wrong thread surface | Resolve valid thread IDs and apply the compatibility redirect before rendering |
| No AI model meets the workspace data policy | A request could violate workspace privacy rules | Pause AI and show the policy warning when no model is allowed |
| An application connection lacks the required permission or credentials | Install or connect actions fail or expose an unusable connection | Check permission, provider scope, health, and authorization state before showing the action |
| A live event is applied to the wrong surface | A page can show data from another record or request | Scope subscriptions and short-lived state by workspace, record, thread, or job |
Key files
| File | Why to read it |
|---|---|
| packages/…/index.tsx | Browser startup boundary |
| packages/…/App.tsx | Shared public and workspace provider boundary |
| packages/…/DomainShell.tsx | Host and workspace route choice |
| packages/…/WorkspaceAppProviders.tsx | Signed-in services, chat runtime, and live events |
| packages/…/createWorkspaceRouteObjects.tsx | Workspace route map and lazy product areas |
| packages/…/SettingsRoutes.tsx | Protected settings route map and legacy redirects |
| packages/…/graphql.ts | Generated core API operations and result types |
| packages/…/graphql.ts | Generated workspace and metadata API contracts |
| packages/…/graphql.ts | Generated privileged administration API contracts |
| packages/…/InboxPage.tsx | Shared conversation list and reading surface |
| packages/…/LegacyAiChatPage.tsx | Compatibility route for older AI chat URLs |
| packages/…/AiChatThreadPageContent.tsx | AI chat as a record experience |
| packages/…/AiChatInstance.tsx | Per-surface chat identity and thread lifecycle |
| packages/…/RecordShowPageShell.tsx | Common full-page and side-panel record surface |
| packages/…/currentWorkspaceState.ts | Durable workspace product state |
| packages/…/metadataStoreState.ts | Workspace metadata state |
| packages/…/SSEQuerySubscribeEffect.tsx | Live server-to-client state flow |