Insights Tool

Overview

The Insights tool provides a single-page analytics dashboard for workforce metrics. It uses a summary + expand pattern: key KPI cards are always visible, with six collapsible sections that reveal detailed charts when expanded.

Data is sourced from the users table (employee fields synced from Xero) and pay_summaries (salary data). Charts are rendered with Recharts.

Permissions

Access Level	Can View	Can Manage
Executive	Yes	Yes
Head	Yes	No
Manager	Yes	No
Lead	No	No
Employee	No	No

All data shown is aggregate — no individual employee data is exposed in insights.

Page Layout

KPI Summary Row

Six cards always visible at the top:

• Total headcount — active employees, net growth in period
• Turnover rate — percentage of leavers vs headcount, average tenure
• Median salary — with min/max range
• Average age — from date of birth data
• Avg span of control — direct reports per manager, employee-to-manager ratio
• Locations — count of distinct locations

Filters

• Date range — from/to date pickers (defaults to last 12 months)
• Location — dropdown filter populated from location data
• Gender — optional filter

Expandable Sections

Each section shows inline summary stats when collapsed. Click to expand and reveal charts.

Headcount

• Area chart: total headcount over time (monthly)
• Stacked bar chart: starters vs leavers per month

Retention

• Line chart: turnover rate over time
• Bar chart: tenure distribution (0-6mo, 6-12mo, 1-2yr, 2-5yr, 5yr+)

Diversity

• Donut chart: gender breakdown with percentages
• Manager gender breakdown
• Bar chart: age distribution by decade

Compensation

• Min/median/max salary display
• Bar chart: salary band distribution (20k buckets)
• Employment basis breakdown (full-time, part-time, casual, contractor)

Org Structure

• Bar chart: span of control distribution
• Team sizes list sorted by size

Location

• Donut chart: location breakdown
• Table with location name, count, and percentage

Data Sources

Employee fields are populated via Xero Payroll sync during the /api/pays/refresh flow:

• start_date, end_date, employment_status — from Xero StartDate, TerminationDate, Status
• gender, date_of_birth — from Xero employee record
• location — derived from Xero HomeAddress.Region or HomeAddress.City
• employment_basis — from Xero EmploymentType
• Salary data — from pay_summaries.annual_salary (cached from Xero)

Fields can also be set manually via the admin user management UI.

Components

Component	Purpose
insights-page.tsx	Main page with filters, KPI row, and section layout
insight-section.tsx	Reusable collapsible section wrapper
headcount-chart.tsx	Headcount area chart + starters/leavers bar chart
retention-charts.tsx	Turnover line chart + tenure distribution
diversity-charts.tsx	Gender donut + age distribution bar chart
compensation-charts.tsx	Salary bands + employment basis
structure-charts.tsx	Span of control + team sizes
location-chart.tsx	Location donut + breakdown table