Signal — Platform Foundation (app shell: auth, tiers, data flow, shared UI, global search, Iris)

Signal is Power Digital's internal business-intelligence web app. The Platform Foundation is the cross-cutting shell every user interacts with regardless of which page they open: Google sign-in and the five-tier access model (Member → Team Lead → Admin → Gandalf → Sauron, plus a separate Growth grant system), the left sidebar with the shared period (month) selector, the top-header Global Search (Cmd/Ctrl+K), the Iris AI chat drawer (Cmd/Ctrl+I; enabled by the is_admin flag specifically — Admins and Saurons, not Gandalf-only users), and the central data pipeline that loads employees, client accounts, and revenue for the selected months. It answers "who can see what in Signal, and where does the data on screen actually come from." Top-level data origins: revenue and gross profit come from Vena (finance's system of record, read-only); people, clients, departments, and team assignments come from Nova (Power Digital's client/org platform); everything users change inside Signal (roles, Growth grants, favorites, usage logs) lives in Signal's own records; AI answers come from Anthropic Claude.

Signal's Platform Foundation exists so that one login, one navigation, one time-period selection, and one data pipeline serve every view in Signal. Before Signal, answers to "how much revenue does this client bring, who is staffed on it, and is it healthy?" lived in disconnected systems: Vena (finance), Nova (client/org platform), and spreadsheets. Signal's backend (Express, server/) joins those sources server-side — the browser never queries the data warehouse directly — and serves roughly 30 views to different leadership audiences. The foundation layer is also where access control happens: a five-tier role model (Member, Team Lead, Admin, Gandalf, Sauron) plus a separate division-scoped "Growth" grant system decide which sidebar sections, routes, and API endpoints each person can use. Finally, the foundation provides the two universal lookup tools: Global Search (instant fuzzy search over employees/accounts plus an optional AI answer) and Iris (an AI analyst chat drawer that sees the data currently on the user's screen).

Signal sign-in and the tier model (all mechanics below are code as of Jul 2026, in src/context/AuthContext.tsx and server/index.ts):

Sign-in: Google OAuth via Signal's own auth service. Only three email domains may sign in (hardcoded allowlist in AuthContext.tsx): powerdigitalmarketinginc.com, external.powerdigitalmarketinginc.com, cardinaldigitalmarketing.com. Any other domain is signed out with "Access restricted to authorized Power Digital and Cardinal email domains only." Deep links survive login (the path is stored and restored after the OAuth redirect). Local dev can bypass auth with VITE_DEV_BYPASS_AUTH=true.

First sign-in auto-provisioning: the frontend calls POST /api/auth/ensure-provisioned, which creates the user's row in Signal's app_users role table (all flags false), except that people who are an Executive Sponsor (Account Director) or Group Director on any active client in Nova are auto-upgraded to Team Lead (is_team_lead=true). The AD/GD email list is read from Nova's client records and cached server-side for 1 hour. Provisioning never downgrades an existing Team Lead.

The five tiers (resolved from Signal's app_users table; flags cached in the browser's sessionStorage so a page refresh doesn't flash access away, then reconciled against the database in the background):

Note: since a mid-2026 nav restructure, the prediction/health views (Portfolio Review, POC Management, Churn Risk, Division Forecast, Service Expansion), Staffing, and ETCR are open to every non-Member — they no longer require Team Lead. Client Profitability and Pulse Summary remain Admin+.

Growth access (orthogonal to the tiers): visibility into the Growth section (People Dash with salaries, Performance Radar) is not a tier. It is resolved by the backend from two of Signal's own tables — growth_access_grants (which divisions/departments a person may see; a NULL-division grant = all divisions) and growth_access_capabilities (three per-user booleans: can_view_people, can_view_radar, can_manage_access). The frontend fetches GET /api/growth/my-access at sign-in and caches the result in sessionStorage. On top of the grants there is a second factor: a shared unlock password. Each Growth tab prompts for it (GrowthTabGate in src/App.tsx); the backend enforces the same key (x-growth-key header, checked against the GROWTH_UNLOCK_KEY environment variable) on every /api/growth data request and on the Growth Access management endpoints, so a locked tab genuinely cannot load data. The key is held in browser memory only — a page reload forces re-entry, and it re-locks after the app has been backgrounded ≥ 5 minutes (code constant BACKGROUND_RELOCK_MS as of Jul 2026). Growth access is managed on the "Growth Access" screen (/growth/access), open to Sauron super-admins or anyone holding the delegated can_manage_access capability — it is not Gandalf-gated. Being Sauron does not by itself grant Growth data access; a super-admin must hold a grant like anyone else (only management is automatic).

Sidebar visibility mirrors the route guards: nav sections/links carry flags (teamLeadOnly, adminOnly, gandalfOnly, sauronOnly, peopleOnly, radarOnly, manageGrowthOnly) and are filtered per user. Members see exactly two destinations (Summary, Employees). An "Access" section (General Access for Gandalf; Growth Access for Growth managers) and the Admin section are pinned to the bottom of the sidebar. A separate hardcoded allowlist (PAYROLL_AUTHORIZED_EMAILS in server/index.ts, exactly 15 named emails as of Jul 2026) gates the payroll/personnel-expense API endpoints used by Divisional P&L — that list is independent of the tiers.

Server-side enforcement: every sensitive API route re-checks access with middleware (requireAuth validates the login token; requireAdmin, requireGandalf, requireGrowthAccess, requireGrowthManage, requirePayrollAccess re-read the role/grant tables with short caches of 2–5 minutes). Hiding a nav item is never the only protection.

The browser talks only to Signal's backend API (/api/*, fetch wrapper in src/services/api.ts) and to Signal's own record store for a few user-owned reads/writes. Origin systems below are the true source of each number, not the transport.

Sources that surface in other Signal modules (for orientation only): VABO monthly revenue (Vena), churn/service-expansion model scores and Salesforce history (ML pipeline + Salesforce), pulse answers (Nova), Deel and ADP payroll (Divisional P&L / Growth), NetSuite account costs (profitability), Google Sheets hiring pipeline, Asana task creation, Gong-derived meeting data where noted in those modules.

The foundation layer itself displays few metrics, but it defines the shared vocabulary every view (and Iris) uses:

The foundation layer writes little by itself — most writes belong to specific modules — but these are cross-cutting:

Q: Why can I only see Summary and Employees in Signal? A: You're on the base "Member" tier — any signed-in employee with no elevated role. Members see exactly two views (Summary and Employees) and have no Global Search or Iris. If your job needs more, ask a Gandalf-tier admin to raise your tier on Signal's General Access screen (it's a data change in Signal, not an IT ticket). Nova Account Directors and Group Directors are upgraded to Team Lead automatically at sign-in.

Q: Why doesn't the revenue in Signal match Vena exactly? A: Signal reads its revenue, outsource cost, and MGP directly from Vena (finance's system of record) — Signal never edits those numbers. Differences usually come from timing (Signal's server caches Vena data and the upstream pipeline refreshes on its own cadence), from the selected period (multi-month selections sum revenue across the range), or from a long-open browser tab running pre-deploy code (reload when the "new version" banner appears). If a number is genuinely wrong, the fix is upstream in Vena — flag it in Signal's Corrections view.

Q: Who can use Iris, and what data does it actually see? A: Iris (the chat drawer, Cmd/Ctrl+I or the top-right button) is enabled by the is_admin flag specifically (IrisContext.tsx): Admins and Saurons have it (Sauron forces all flags true), but a Gandalf-only user without is_admin does not get the drawer, and Members never see the button. It sees only a snapshot of what's loaded in your session for the selected period — employees, accounts, and the computed KPIs — plus which page you're on. It does not run database queries, so it can't answer about months outside your selected period. Every Iris conversation is logged (your email, full prompt, and response) to Signal's own records. For deep client-data questions beyond the on-screen snapshot, use iris.novapower.io.

Q: Why is Signal asking me for a password on the Growth People tab when I already have access? A: That's by design — Growth data (salaries, performance) has a second factor on top of your division grant. The shared unlock password is enforced by the backend on every Growth data request, is kept only in your browser's memory, and re-locks after a page reload or ≥5 minutes with Signal in the background. If you don't know the password or your grant is missing, ask a Growth access manager (the Growth Access screen is run by super-admins and delegated managers).

Q: I was just given Admin/Team Lead but Signal still shows my old access. Why? A: Role flags are cached for resilience: your browser keeps them in sessionStorage and the server caches role checks for a few minutes, and ambiguous reads deliberately keep the cached value instead of revoking access. Sign out and back in (or wait a few minutes and refresh) and the new role will apply. The same logic means a revoked role can also linger briefly.

Q: What do the period presets actually select, and why is next month missing? A: The sidebar period selector offers Current month, Last 3 months, Last 6 months, All time, or a custom month range. Presets anchor to the current calendar month. Future months are excluded server-side — the finance source contains scheduled future contract months (through 2027) that aren't real actuals yet — and months with zero revenue are skipped. Every view in Signal filters to this selection; multi-month picks aggregate revenue across the range.

Q: Where does the team shown on an account come from — Nova or Signal? A: Both, with clear precedence. Signal's own team assignments (saved in Manage Leads) win whenever they exist; a client marked "managed" in Signal never falls back, even with an empty team. Otherwise Signal shows the team detected from Nova's assignment history. Account Director / Senior AD chips are the exception: for single-division, non-Consulting clients, live Nova is the source of truth and Signal syncs AD changes back into Nova; multi-division and Consulting clients keep Signal's per-division records. If a team looks wrong, fix it in Manage Leads; don't assume the data pipeline is broken.

Q: Is my Signal usage tracked? A: Yes. Every page visit logs a page_view event (your email, the route) into Signal's own records, severe UI freezes log a diagnostic event, and every AI interaction (Iris or Global Search "Ask AI") logs the full prompt and response with your email. These feed the super-admin-only Analytics dashboard. Retention policy is not defined in the app repo.

Q: What are "Gandalf" and "Sauron"? A: Internal code names for the top two access tiers (Signal has a Lord of the Rings naming theme — the loading screen quotes LOTR and releases carry names like "Legolas"). Gandalf ≈ executive tier (Divisional P&Ls, user administration, hiring tools); Sauron ≈ super-admin, a short hardcoded list of the app's owners whose access can't be revoked by a database change. In documentation for wider audiences, say "executive tier" and "super-admin".

Q: Global Search found nothing — what does "Press Enter to ask AI" do? A: Instant results are a local fuzzy match over the employees, accounts, and page names already loaded for your selected period (type ≥2 characters; VABO rows excluded). Pressing Enter with no matches sends your query plus a compact index of employees/accounts to Anthropic Claude, which returns interpreted matches or a short analytical answer, labeled "AI-powered". The AI call only happens on explicit Enter, and it's logged like every AI generation.

Q: Why did Signal show a banner saying a new version is available? A: Your tab has been open across a deploy, so the code running in it is older than what's live — numbers could be computed with outdated logic. Signal checks the deployed build id when you return to the tab (at most every 5 minutes) and prompts — never forces — a reload. Click Reload unless you're mid-edit; "Later" hides the banner only for that specific build.