> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Navigation telemetry: org-admin usage analytics

> PHI-safe org-admin analytics over navigation events: top routes, active users, per-core volume, and cross-core co-navigation pairs.

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](/pf/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.

## Related

<Columns cols={2}>
  <Card title="Workspace admin" icon="table-columns" href="/pf/workspace-admin">
    Build custom workspaces or accept AI recommendations based on this telemetry.
  </Card>

  <Card title="Settings hub" icon="gear" href="/pf/settings">
    Where the telemetry page is linked from.
  </Card>
</Columns>

<Note>
  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.
</Note>

<Accordion title="Documentation sources">
  * src/platform/navigation/telemetry/NavTelemetryPage.tsx
  * src/platform/navigation/telemetry/useNavTelemetry.ts
  * supabase/functions/suggest-workspaces/index.ts
</Accordion>