Signal — Portfolio Review

Route guard: both Portfolio Review routes (/predictions/portfolio and /predictions/portfolio/:clientId) are wrapped in MemberAllowedRoute in src/App.tsx. This guard redirects base-tier "Members" to /summary; every non-Member falls through.

Who is a "Member": in src/context/AuthContext.tsx, a Member is a signed-in user with none of the elevated flags: not Team Lead, not Admin, not Gandalf, not Sauron, and holding no Growth capability (isGrowthAllowed, canViewRadar, canManageGrowthAccess). Consequence: a Growth-only user (someone granted Growth People/Radar access but no Team Lead flag) is NOT a Member and can technically open Portfolio Review. In practice the intended audience is Team Lead and above.

Nav flag: the "Portfolio Review" link sits in the Client Health sidebar section with no per-link gate, so every non-Member sees it. Base Members' sidebars are stripped to Summary and Employees only.

How the Team Lead flag is granted: roles live in Signal's own app_users table (Signal's records, managed by Signal admins via the General Access screen). Additionally, on every sign-in, POST /api/auth/ensure-provisioned auto-sets is_team_lead = true for any user whose email matches a Nova client's executive_sponsor_id (Account Director) or group_director_id — i.e., ADs and GDs are auto-upgraded; the flag is never auto-downgraded. Admin and Gandalf implicitly include Team Lead.

API: GET /api/predictions/portfolio requires an authenticated session (requireAuth); there is no additional role check on the endpoint itself.

Sign-in is Google OAuth restricted to Power Digital and Cardinal email domains (ALLOWED_DOMAINS in AuthContext.tsx, includes cardinaldigitalmarketing.com).

MGP (Monthly Gross Profit) — gross profit actually booked for the current month for this client. Origin: Vena Finance actuals. May be $0 for newly active contracts before Finance posts entries. Default table sort is MGP descending.

Dept MGP (filtered) — the client's MGP within the currently filtered department only, with "% of book" (department MGP ÷ client's whole-book MGP). Origin: Vena Finance actuals per blueprint × department. Only populated when a Department filter is active.

MRR (Monthly Recurring Revenue) — gross monthly revenue from active retainer contracts for the current month; the top-line counterpart to MGP. Origin: Vena Finance actuals.

Past Due AR — total unpaid amount due for the client (TOTAL_AMOUNT_UNPAID_DUE in the modeled feature set). Origin: finance records surfaced via the data team's pipeline; the specific upstream finance system is not defined in the app repo.

Last Mo VABO / VABO-2mo — VABO revenue (performance-based revenue; the acronym's expansion is not defined in the app repo) for the last month and two months back. Origin: Vena Finance actuals. VABO-2mo > 0 with no active contract and MGP ≤ 0 marks a client "VABO only".

Churn Risk — the data-science churn model's enhanced risk score, 0–1. Risk categories used by the filter (code constants as of Jul 2026): Critical ≥ 0.6, High 0.5–0.6, Medium 0.3–0.5, Low < 0.3.

Profile Risk — the normalized profile-risk component (risk_norm) of the churn model. Origin: data-science churn model.

Readiness Score (SE Readiness) — the service-expansion model's 0–1 readiness score; Portfolio uses the raw current model value. Origin: data-science SE model.

SE Sentiment / SE Performance — SE model sub-scores, rendered as text labels: Strong ≥ 0.7, Moderate ≥ 0.4, Low < 0.4 (code constants as of Jul 2026, matching the Service Expansion view's buckets). Origin: data-science SE model (Gong and Pulse inputs).

Gong Sentiment — Gong-derived call-sentiment score for the client; a value of exactly 0.5 is a "no data" convention and renders as "—". Origin: Gong via the SE model.

Priority (P1/P2/P3) — pre-computed priority tier from the data-science pipeline (FINAL_FEATURES.PRIORITY_TIER). UI labels: "P1 — Act now", "P2 — Plan this week", "P3 — Healthy / Monitor". Clients with no tier default to P3. The trigger rules are owned by the data team and can change without an app deploy.

Status chip — computed in the browser from recommended-action triage (Signal's own records): Acknowledged = the assigned AD/GD completed or dismissed every recommended action; Reviewed = someone other than the assigned owner triaged everything; Needs Review = actions remain untriaged (shown only for the priority set: top-25 by risk × MGP among clients with risk ≥ 0.5); Unassigned = no AD/GD on record (priority set only); no chip = client has no generated actions or is outside the nudge set.

Pulse Sentiment / Pacing to Goal / WoW Changes / GD Review Notes — fields from the Account Director's weekly Pulse submission for the selected Monday week. Origin: Signal's own records (entered by ADs in Signal).

Pulse Submitted / QBP Submitted — Yes/No flags: whether an active weekly Pulse row exists for the selected week / an active QBP row exists for the quarter derived from the selected week.

Days to End / Contract Ending filter — days until the latest active contract end date (computed server-side from the contract-details JSON); negative (expired) renders red. Filter buckets: within 30/60/90 days.

Active Book MGP (summary card) — sum of MGP across currently filtered clients, with client count. P1/P2/P3 summary cards show per-tier count + MGP and toggle a priority filter on click.

"Your week" strip — Today's calls: top 3 P1 clients ranked by churn risk × active retainer value; SE-ready: up to 2 clients with readiness ≥ 0.7, ≥ 90 days since last SE (or no SE on record), and no open/failed SE; acknowledged last 7 days: count of scoped clients whose Status is Acknowledged with a triage timestamp in the last 7 days (clicking filters the table). All thresholds are code constants as of Jul 2026.

GD Review Notes + WoW Changes editors (expanded panel) — edit the current week's "GD Review Notes" and "week-over-week changes" fields on the client's weekly Pulse submission. Saves go through POST /api/pulse/weekly into Signal's pulse_weekly_submissions (the same store the Pulse Submission module writes). The endpoint enforces ownership: only the client's assigned AD, its GD, or a Pulse admin may save (others get a 403). Past weeks are read-only; if no Pulse exists for the current week the editor links to the Pulse submit form instead.

Create Asana task (expanded panel) — "+ New task" opens a modal that creates a real task via the Asana API (POST /api/asana/tasks) and records the task↔client link in Signal's asana_links table.

Client notes (expanded panel) — add/edit churn-side and SE-side notes, stored in Signal's client_notes; visible from the Churn and Service Expansion screens too.

Recommended-action triage (embedded Churn Risk tab) — marking actions done/dismissed writes Signal's recommended_action_feedback; this is exactly what flips the Status chip to Acknowledged/Reviewed. Action-level notes land in Signal's action_notes.

Generate Brand Intel (expanded panel) — triggers a paid Anthropic Claude generation (~$0.50), persisted to Signal's macro_brand_insights (one cached result per client per month; per-user cap of 50 fresh generations/day, env-tunable).

Implicit side effects — every page view, row expand, and briefing-strip click writes Signal's signal_usage_events; loading the page also triggers the server-side Nova→Signal Account Director sync (writes Signal's client_account_directors and team_assignments, freshness-guarded so it never overwrites newer manual Manage Leads edits; 1-hour TTL).

Local only — column visibility and category-preset choices persist per browser under localStorage key portfolio-review-columns-v9, not to any database.

"Why flagged" column is always empty. Priority moved to the warehouse-computed PRIORITY_TIER; the client-side signal chips were retired, so the column renders "—" for every client. It remains selectable and exports as empty.

Confirmed Churn MRR and Per-Client ETCR columns are placeholders ("ETCR pipeline pending — owned by Lily"). They render "—", are not sortable, and export empty.

Priority definitions live upstream. P1/P2/P3 comes from the data-science pipeline (FINAL_FEATURES.PRIORITY_TIER); the rules can change without any app deploy, and the app repo does not define them. A client missing a tier silently defaults to P3.

Freshness is mixed by design. The client/risk/finance base is served from a 15-minute stale-while-revalidate server cache (shared with POC Management); Pulse and QBP columns are read fresh on every request. The separate churn and SE calls have their own 15-minute caches, so signals can be up to 15 minutes apart from each other.

Upstream refresh cadence is not authoritative in this repo. Code comments describe a roughly weekly model refresh for the churn/SE/feature tables; the actual schedule lives in the data team's pipeline. Not defined in the app repo.

Code-constant thresholds (as of Jul 2026, all tunable only via deploy unless noted): risk buckets 0.3/0.5/0.6; SE Strong/Moderate/Low at 0.7/0.4; briefing-strip SE-ready readiness ≥ 0.7 and ≥ 90 quiet days; Status-chip priority set = top-25 by risk × MGP among risk ≥ 0.5; Cardinal = acquisition_id 1005; Brand Intel daily cap 50 (env-tunable); Contract Ending buckets 30/60/90 days; Pulse History fetch defaults to 5 weeks.

Gong sentiment of exactly 0.5 is a "no data" convention and renders as "—" rather than a score.

Account Director attribution is layered: manual Manage Leads picks (Signal's records) win over the Nova executive-sponsor fallback, and overrides pointing at terminated users fall back to Nova. The Nova sync only overwrites a Signal row when Nova's record is strictly newer.

Week selector semantics: weeks are Monday-anchored; the default selected week is the most recent week with any active Pulse submission (else the current Monday). Selecting a past week makes the Pulse-notes editors read-only. QBP columns follow the quarter derived from the selected week; QBP dates may be entered up to one year ahead.

Column set churns frequently — the localStorage key is at v9 — so avoid relying on exact column positions.

Who holds Team Lead in practice is runtime data in Signal's app_users table (plus the AD/GD auto-grant at sign-in); the roster is not in code.

Churn Risk (/predictions/churn) — Portfolio Review consumes the same churn feed and embeds the churn client detail as its "Churn Risk" tab; recommended-action triage is shared (same recommended_action_feedback rows), so acknowledging in either view updates both.

Service Expansion (/predictions/se) — same relationship: the SE feed is merged into Portfolio Review and the SE client detail (including its Salesforce history tab) is embedded; Strong/Moderate/Low buckets intentionally match.

Pulse Submission / My Submissions (/pulse/submit, /pulse/my-submissions) — ADs submit weekly Pulse and QBP there; Portfolio Review is the primary consumption surface, and its GD Review Notes / WoW Changes editors write back to the same table.

Pulse Summary (/predictions/pulse-summary, admin-gated) — sentiment/pacing across the portfolio in a Pulse-first layout.

POC Management (/predictions/poc-management) — shares the exact same server-side portfolio base cache (a full churn+SE recompute happens at most once per 15 minutes across both views).

Manage Leads (/leads) — Account Director attribution flows through the same client_account_directors table Manage Leads edits; the AD shown in Portfolio Review reflects those edits plus the Nova sync.

ETCR (Beta) (/etcr) — the two ETCR placeholder columns in Portfolio Review will light up when the ETCR pipeline ships.

Analytics (/analytics, Sauron-gated) — usage events logged from Portfolio Review surface in the internal adoption dashboard.