Analytics Value Objects¶

Why This Exists¶

This document defines immutable or value-based concepts used by the Analytics Domain.

The owner is the Chief Product Officer and Enterprise Architect.

Value objects make analytical definitions, time periods, formulas, thresholds, and lineage consistent across dashboards and reports.

Value object	Purpose	Validation rules
KpiId	Identifies a KPI definition.	Must be unique and versioned.
DashboardId	Identifies a dashboard.	Must be unique.
ReportId	Identifies a report definition.	Must be unique.
MetricValue	Stores a calculated value.	Must include unit and data type.
MetricUnit	Defines unit of measure.	Examples: count, percent, currency, days, score.
ReportingPeriod	Defines time scope.	Must include start date, end date, and timezone.
DataFreshness	Indicates last refresh status.	Must include refreshed at and freshness status.
TrendDirection	Describes metric movement.	Allowed values: improving, declining, stable, unknown.
ThresholdBand	Classifies metric status.	Allowed values: green, amber, red, not_applicable.
InsightSeverity	Classifies insight importance.	Allowed values: low, medium, high, critical.
ConfidenceScore	Captures confidence in an insight or AI-assisted explanation.	Must be 0 to 1.
SourceLineage	Captures source domains, events, views, and calculation references.	Required for metric snapshots.
FormulaVersion	Identifies KPI formula version.	Immutable for historical snapshots.
DashboardAudience	Defines dashboard audience.	Examples: executive, practice, operations, customer, internal.
ReportCadence	Defines report schedule.	Examples: daily, weekly, monthly, quarterly, on_demand.
CurrencyAmount	Represents monetary values.	Must include amount and currency code.

Every metric snapshot must reference KPI definition and formula version.
Executive insights must include evidence and period.
Trend direction must be calculated from comparable periods.
AI-generated explanations must be labeled as such and include confidence where available.