Skip to main content
The Navigation telemetry page gives org admins an aggregated view of how members move around the platform. Use it to understand which workspaces and routes are actually used, spot under-adopted areas, and decide which workspaces to add, override, or recommend to users.

​
Overview

The page reads from nav_events, a PHI-safe event stream that records only route templates (such as /clinical/patients/:id) and event types (such as route_visit, workspace_select). It never stores patient or record IDs, query parameters, or any field-level values, so the entire surface — including the aggregation RPC — is safe to expose to org admins. For each selected window (7, 30, or 90 days) the page shows:
  • Metric cards — total events, active users, top workspaces selected, top routes.
  • Core usage bar chart — relative event volume per core (clinical, practice, hr, and so on).
  • Co-navigation summary — pairs of route templates that the same user visited within the window. This is the signal that powers AI workspace recommendations.
  • Events time series — daily events for the window, useful for spotting trends after a workspace change or release.

​
Who it’s for

Required permission: system.organizations.admin. The page is org-scoped — you only ever see your own organization’s aggregates. The underlying nav_events_summary RPC is SECURITY DEFINER and filters by organization_id server-side, so cross-org leakage is not possible.

​
Before you start

  • You must hold system.organizations.admin for the active organization.
  • nav_events collection must be enabled (default).
  • Expect empty or thin charts for newly onboarded orgs — the page handles low-data states explicitly. Aggregates fill in as members navigate.

​
Open the page

  1. Go to Settings (/settings).
  2. Under Navigation & workspaces, select Navigation telemetry.
  3. Choose 7 / 30 / 90 days from the range selector. The whole page re-queries.

​
Read the charts

Top routes answers “where do people actually go?” — useful for confirming that the routes you expect to be hot really are. Top workspaces selected counts workspace_select events, not route visits. A workspace that’s high in route volume but low in selections is being reached by direct links or bookmarks; consider promoting it in the sidebar. Core usage is event volume per top-level core. If a core has near-zero events, members likely aren’t reaching it from any workspace — a candidate for a new custom workspace or a seed override. Co-navigation pairs show route templates co-visited by the same user inside the window. Tight pairs across cores (for example a clinical chart route plus a practice billing route) are evidence that members are stitching together a workflow the built-in workspaces don’t cover. These pairs feed the Suggest workspaces AI flow on the Workspace admin page.

​
Key concepts

Route template — The pattern (/clinical/patients/:id) rather than the resolved URL (/clinical/patients/123). Storing the template, not the URL, is what keeps nav_events PHI-safe. nav_events_summary RPC — The single Postgres function behind this page and behind AI workspace recommendations. It runs all aggregation server-side; no raw rows are pulled to the client. Active users — Distinct users who emitted at least one nav event in the window. Useful as a denominator when comparing route volume across windows.

Workspace admin

Build custom workspaces or accept AI recommendations based on this telemetry.

Settings hub

Where the telemetry page is linked from.
This page documents shipped product behavior. It is not medical, legal, or billing advice. Verify against your organization’s policies and applicable regulations before using it for clinical, compliance, or billing decisions. Protected health information (PHI) shown in the product is governed by your tenant’s access controls and is never exposed in this documentation.
  • src/platform/navigation/telemetry/NavTelemetryPage.tsx
  • src/platform/navigation/telemetry/useNavTelemetry.ts
  • supabase/functions/suggest-workspaces/index.ts