Skip to main content

​
Dashboard Wiring Map

Generated: 2025-11-XX
Purpose: Document all page → endpoint → params mappings for Nov 2025 validation

​
1. /ceo (Executive Dashboard)

File: dashboard/src/pages/ceo/index.tsx Endpoints Called:
EndpointMethodParamsPeriod FormatNotes
/api/v1/ceo-metricsGETperiod_label, period_type? (ytd/qtd)YYYY-MM-01Main CEO metrics with breakdowns
/api/v1/audit-checksGETperiod_labelYYYY-MM-01Audit check data
/api/v1/commissionsGETperiod_label, limit, offsetYYYY-MM-01Paginated commissions
/api/v1/growth-lossGETperiod_labelYYYY-MM-01Growth/loss summary
/api/v1/agents/performanceGETperiod_labelYYYY-MM-01Agent performance rankings
/api/v1/business-healthGETperiod_labelYYYY-MM-01Business health metrics
/api/v1/growth-loss-detailsGETperiod_label, limitYYYY-MM-01Detailed growth/loss
/api/v1/new-lost-businessesGETperiod_labelYYYY-MM-01Via renderCard() factory
/api/v1/top-businessesGETperiod_label, limit=10YYYY-MM-01Via renderCard() factory
/api/v1/top-agentsGETperiod_label, limit=10YYYY-MM-01Via renderCard() factory
Period Selection:
  • Uses CEO_PERIOD_OPTIONS constant (hardcoded array)
  • Converts YYYY-MM format to YYYY-MM-01 for API calls
  • Supports period_type toggle (MTD/YTD/QTD) for CEO metrics
Success Criteria:
  • All endpoints return HTTP 200 with correct shape
  • Non-empty arrays/counts for Nov 2025 data
  • KPI cards update when period changes
  • Charts/tables reflect selected period

​
2. /agent (Agent Overview Tab)

File: dashboard/src/pages/agent/index.tsx Endpoints Called:
EndpointMethodParamsPeriod FormatNotes
/api/v1/leaderboardGETperiod_label, limit=10YYYY-MM-01Top agents leaderboard
/api/v1/agents/{agentName}/kpi-metricsGETagentName, period_label, period_type?YYYY-MM-01Agent KPI metrics
/api/v1/agents/{agentName}/commissionsGETagentName, period_label, limit, period_type?YYYY-MM-01Agent commissions
/api/v1/agents/{agentName}/business-healthGETagentName, period_labelYYYY-MM-01Business health for agent
/api/v1/agents/{agentName}/trendsGETagentName, monthsDate rangeMulti-month trend data
Period Selection:
  • Uses AGENT_PERIOD_OPTIONS constant (hardcoded array)
  • Converts YYYY-MM format to YYYY-MM-01 for API calls
  • Supports period_type toggle (MTD/YTD/QTD) for some endpoints
Success Criteria:
  • All endpoints return HTTP 200 with correct shape
  • KPI cards show agent-specific metrics for selected period
  • Leaderboard reflects selected period
  • Trend charts include Nov 2025 in range

​
3. /agent?tab=detailed (Agent Detailed Reporting Tab)

File: dashboard/src/pages/agent/index.tsx (same file, different tab)
Component: <AgentDetail agentName={agentName} /> Endpoints Called:
EndpointMethodParamsPeriod FormatNotes
(Check AgentDetail.tsx for exact endpoints)Likely uses date range queries
Period Selection:
  • Same as Overview tab (uses AGENT_PERIOD_OPTIONS)
  • May use date range queries (2025-01 to 2025-12) that automatically include Nov
Success Criteria:
  • Detailed reports include Nov 2025 data
  • Aggregates reflect Nov in range
  • Charts update when period changes

​
4. /agent/insights (Agent Insights)

File: dashboard/src/pages/agent/insights/index.tsx Endpoints Called:
EndpointMethodParamsPeriod FormatNotes
/api/v1/top-businessesGETperiod_label, period_type?, limit=10YYYY-MM-01Top businesses by revenue
/api/v1/top-agentsGETperiod_label, period_type?, limit=10YYYY-MM-01Top agents by commission
Period Selection:
  • Hardcoded dropdown options (JSX <option> elements)
  • Converts YYYY-MM format to YYYY-MM-01 for API calls
  • Supports period_type toggle (MTD/YTD/QTD)
Success Criteria:
  • Both endpoints return HTTP 200 with correct shape
  • Tables update when period changes
  • Nov 2025 selectable in dropdown
  • Header always shows “Welcome back, Team”

​
Common Patterns

​
Period Format Conversion

  • Frontend: YYYY-MM (e.g., 2025-11)
  • API: YYYY-MM-01 (e.g., 2025-11-01)
  • Conversion: ${selectedPeriod}-01 in API calls

​
Period Type Support

  • MTD (Month-to-Date): Default, no period_type param
  • YTD (Year-to-Date): period_type=ytd
  • QTD (Quarter-to-Date): period_type=qtd

​
Success Response Shape

  • Valid Empty: HTTP 200 + correct shape (arrays/summary keys present, even if empty)
  • Invalid: 4xx/5xx status codes or shape mismatch

​
Error Handling

  • Loading states show placeholders
  • Error states show error messages
  • Headers never show email (contract enforced)

​
Validation Checklist

​
Pre-Pipeline (Part 2B)

  • All endpoints return HTTP 200 for period_label=2025-11-01
  • Response shapes match expected structure
  • Empty states are valid (correct shape, empty arrays)

​
Post-Pipeline (Part 5)

  • All endpoints return non-empty data for period_label=2025-11-01
  • Counts/arrays populated correctly
  • Sample JSON responses saved for evidence

​
UI Validation (Part 6)

  • CEO dashboard shows Nov 2025 data
  • Agent Overview shows Nov 2025 data
  • Agent Detailed includes Nov 2025 in trends
  • Agent Insights shows Nov 2025 data
  • All period selectors include Nov 2025 option