Building Dashboards

Dashboards are collections of widgets arranged on a 12-column grid. This guide covers the admin workflow.

Creating a Dashboard

Go to Settings → Dashboards → New Dashboard
Set name, description, and role visibility
Optionally set as default dashboard for specific roles

Role visibility controls who sees the dashboard:

admin, manager, viewer — everyone
admin — admin only
admin, manager — admins and managers

Adding Widgets

Click "Add Widget" and choose:

KPI Card

Shows a single metric with period comparison.

Config field	What it does
`metric`	Which metric to display (from semantic model)
`period`	Time period: `this_month`, `this_week`, `last_30_days`
`comparison_period`	Previous period for % change: `last_month`, `last_week`
`icon`	PrimeIcons class (e.g., `pi pi-dollar`)
`color`	CSS variable or hex color

Chart

Time-series or categorical visualization.

Config field	What it does
`metric`	What to measure
`dimension`	How to slice (time or categorical)
`chart_type`	`line`, `bar`, or `area`
`period`	Time range
`show_trend`	Show trend line overlay

Top N Table

Ranked list by metric value.

Config field	What it does
`metric`	What to rank by
`dimension`	What to list
`limit`	How many items (e.g., 5 for top 5)
`sort_dir`	`desc` (highest first) or `asc`
`show_percentage`	Show % of total

Alert Feed

Recent agent alerts.

Config field	What it does
`max_items`	How many alerts to show
`severity_filter`	`["warning", "critical"]`
`show_timestamp`	Display time ago

Layout Configuration

Widgets are positioned on a 12-column grid:

┌──────────────────────┬──────────────────────┐
│   KPI: Bookings      │   KPI: Revenue       │
│   (w:6, h:4)         │   (w:6, h:4)         │
├──────────────────────────────┬───────────────┤
│   Chart: Daily Bookings      │  Alert Feed   │
│   (w:8, h:6)                 │  (w:4, h:6)   │
└──────────────────────────────┴───────────────┘

Position is stored as JSON: { "i": "w1", "x": 0, "y": 0, "w": 6, "h": 4 }

Setting a Default Dashboard

Mark one dashboard per role as default. When a user with that role logs in, they see this dashboard first. Each role can have a different default.

Metric Source of Truth

All widget metrics reference tenant_semantic.metrics by name. If a metric is renamed or deleted, affected widgets show a configuration warning in the admin UI.