Signal — KPI Targets

KPI Targets is an admin-only screen in Signal (Power Digital's internal BI web app) at route /kpi-targets. It is the control room where every client-facing job title gets its official revenue benchmarks — RPE (revenue per employee), MRR (monthly recurring revenue book size), and client retention rate — and where an admin verifies that every employee in Signal is actually matched to one of those benchmarks. It answers: "What target is each role supposed to hit, and which employees are covered by a target?" Target numbers originate in a People-team Google Sheet (the CX and SS "JD Review Process" tabs); the employee roster and job titles originate in Nova (Power Digital's HR/ops platform); Signal's own records (Supabase tables written by Signal itself) hold the working copy of roles, the title-match log, and the sync history.

The KPI Targets module exists because Signal grades employees against role-based revenue benchmarks: an Account Manager is expected to manage a certain monthly recurring revenue (MRR) book, a Strategist is expected to generate a certain revenue per employee (RPE), and client-facing roles carry a client retention benchmark. Those benchmark numbers are maintained by the People team in a Google Sheet (the "CX JD Review Process" and "SS JD Review Process" tabs), while employees and their job titles live in Nova, Power Digital's HR/ops platform. Nothing connects the two automatically — job titles are messy ("Sr. Paid Media Strategist, B2B" vs "Paid Advertising Strategist"), and an unmatched title means an employee silently has no target and drops out of performance views like Company Capacity and Role Capacity.

The KPI Targets screen solves that: it shows the canonical roster of roles and their targets (Signal's working copy, refreshed from the Google Sheet on every sync), shows how many real Nova employees matched each role, quantifies coverage ("X of Y assigned employees have KPI targets"), and lists the job titles that could not be matched so an admin can get the mapping fixed.

The KPI Targets view at /kpi-targets is gated in two places, both in src/App.tsx (verified staging @ 98df0c4):

How the flags are granted: isAdmin and isGandalf come from the is_admin / is_gandalf columns of the app_users table in Signal's own records (Supabase), read by src/context/AuthContext.tsx on sign-in and cached in sessionStorage. The app_users roles are managed in Signal's "General Access" screen (/users, itself Gandalf-gated). Two code-constant fallbacks exist in AuthContext.tsx as of Jul 2026: a SUPER_ADMIN_EMAILS list (always admin regardless of database state) and a GANDALF_ALLOWLIST (always Gandalf regardless of database state). Sign-in itself is Google OAuth restricted to Power Digital email domains.

Note: the gate is enforced in the frontend router; the backend /api/kpi-targets* endpoints themselves do not perform per-user authorization checks (as of staging @ 98df0c4).

Origin conventions: "Nova" = Power Digital's HR/ops platform (source of who works here and their job title). "Google Sheet" = the People-team KPI sheet, ID 1JdhP_o1LHq44X9jJPSGiHAe2UiMHS9HZfrJ4wc1_NrY (overridable via KPI_SHEET_ID env var), tabs "CX JD Review Process" and "SS JD Review Process". "Signal's own records" = data entered/written by Signal itself (Supabase tables signal_roles, signal_match_log, signal_sync_log). The curated title map JD_TITLE_MAP is a hardcoded constant in the app repo (server/jd-title-map.ts, 165 entries, generated from a "Signal Title / JD" Excel export dated 2026-04-17).

Behind the scenes, the sync pipeline (runKpiMatchSync in server/index.ts) orchestrates three origins: (1) the Nova employee roster (active, non-terminated employees with job titles), (2) the Google Sheet KPI tabs (free-text KPI cells parsed into structured RPE/MRR/retention numbers), and (3) the curated title map JD_TITLE_MAP (deterministically maps each Nova title to a role, or marks it "Exclude"). It writes results into Signal's own records and repopulates all in-memory caches.

All metrics on the KPI Targets view are targets (benchmarks), not actuals. Actuals (each person's real MRR/RPE/retention) are computed elsewhere in Signal by the revenue engine (server/vena-kpi-engine.ts, from Vena contract data) and compared against these targets in downstream views.

The KPI Targets screen has exactly one user action that writes data: the Re-sync Matches button (POST /api/kpi-targets/sync, handled by runKpiMatchSync in server/index.ts). One sync run, server-side:

The same sync also runs automatically ~30 seconds after every backend server restart (code constant as of Jul 2026), so the data self-heals after deploys without anyone clicking the button.

You cannot edit target numbers on this screen. Targets are only editable at their origin — the People-team Google Sheet — and the title-to-role mapping is only editable in the curated map in code (server/jd-title-map.ts). This is by design: one source of truth, no side-channel edits. Column show/hide and search are per-browser presentation preferences, not data writes.

Q: Who can see the KPI Targets page? A: Signal Admins and Gandalf-tier (super-admin) users. The route /kpi-targets redirects everyone else to the Summary page, and the nav link (People section) is hidden for non-admins. Admin/Gandalf status is set per user in Signal's app_users records via the General Access screen (/users).

Q: How do I change a target number (RPE, MRR, or retention) for a role? A: You can't change it in Signal. Target numbers are owned by the People team's Google Sheet ("CX JD Review Process" and "SS JD Review Process" tabs). Edit the sheet (via the People team), then click Re-sync Matches on the KPI Targets page — the sync overwrites Signal's working copy with the sheet values and all downstream views pick up the new targets immediately.

Q: Why does an employee show "no target" in Company Capacity or the Employees view? A: Their Nova job title either isn't in Signal's curated title map (it will appear under "Show N unresolved titles" on the KPI Targets page), is explicitly excluded (non-KPI roles like engineering, finance, leadership), or matched a role that carries no revenue targets. Unresolved titles can't be fixed from the UI — the curated map in code (server/jd-title-map.ts) or the People-team sheet has to be updated, then re-synced.

Q: What does the "Re-sync Matches" button actually do? A: It runs the full pipeline server-side: pulls the current target numbers from the People-team Google Sheet into Signal's role records (updating, creating, renaming, and de-duplicating roles), pulls the active employee roster and job titles from Nova, matches every title through the curated title map, rewrites the match log, updates the "Last synced" timestamp, rebuilds the coverage breakdown, and deletes roles that matched zero employees. The same pipeline also runs automatically about 30 seconds after every backend restart.

Q: Why doesn't the sync banner's employee total match the coverage bar's total? A: They count different populations by design. The sync banner counts all active Nova employees who have a job title. The coverage bar counts only active employees assigned to at least one retained client account — the same population used by Company Capacity and Role Capacity, so those views agree with the coverage percentages.

Q: What decides whether a role is "MRR", "RPE", or "Excluded"? A: The targets stored on the role. MRR target only → MRR (book-of-business roles like Account Managers/Directors). RPE target only → RPE (delivery roles like strategists, specialists, analysts). Neither → Excluded (the role exists but carries no revenue target, e.g. leadership, project managers). If a role has both targets, the title decides: titles containing "account director" or "account manager" are MRR, everything else RPE.

Q: A role disappeared from the KPI Targets table — where did it go? A: Every sync deletes roles that matched zero employees (orphan cleanup). If the last person holding a title left or was retitled, the role is removed on the next sync. It will reappear if the Google Sheet still defines it and someone holds a matching title again, or if the sheet sync recreates it.

Q: The coverage bar is empty or shows zeros right after a deploy — is something broken? A: Usually not. The unresolved-titles list and coverage breakdown live in server memory and are rebuilt by an automatic sync roughly 30 seconds after the backend starts. Wait a minute and reload; if it's still empty, run "Re-sync Matches" manually.

Q: Can I trust the dollar defaults I've heard about, like "$175K MRR for Account Managers"? A: No — those figures are dormant code constants (ROLE_LEVEL_DEFAULTS) from an inactive auto-create path, not policy. The authoritative numbers are whatever the People-team Google Sheet says, as shown in the KPI Targets table after a sync.

Q: Why doesn't the revenue here match Vena? A: The KPI Targets page shows no revenue actuals at all — only target benchmarks (RPE/MRR/retention) per job title. Actual revenue figures come from Vena contract data and are computed in other views (Employees, Company Capacity, Role Capacity). If a target-vs-actual comparison looks wrong elsewhere, check here that the person's title matched a role and that the targets were recently synced from the sheet.

Q: Where do the "Matched Employees" counts come from, and can they be stale? A: They come from the match log written during the last sync (Signal's own records). If the database read is blocked (a known row-level-security quirk), the server silently falls back to in-memory counts cached at the last sync — so counts always reflect the last sync run, never live HR data. Re-sync to refresh them.