Analytics Domain
Location: api/nextango/apps/analytics/
Last Updated: 2026-03-06
Overview
The Analytics domain provides composed dashboard endpoints that aggregate data from multiple business domains into unified page payloads. Each endpoint returns a {meta, data} envelope with a standard comparison window and a source field indicating whether data came from live queries or pre-aggregated tables.
The domain has no models of its own. It reads from the transactions, products, users, promotions, and integrations domains, and exposes endpoints organized into four groups: Commerce, Operations, People, and Growth. A separate System endpoint covers infrastructure health.
Architecture
Response Envelope
Every endpoint returns the same top-level structure:
{
"meta": {
"store_id": "uuid-or-sanity-id",
"period": {"start": "2026-01-01", "end": "2026-01-31"},
"compare_to": "prior_period",
"comparison_period": {"start": "2025-12-01", "end": "2025-12-31"},
"generated_at": "2026-03-06T12:00:00Z",
"source": "live"
},
"data": { ... }
}
The source field is "live" for all current endpoints. When pre-aggregated table routing is active (see Analytics Pre-Aggregation), reads from those tables will report "pre_aggregated".
KPI Values
Numeric KPIs that compare current vs. prior period use the KpiValue shape:
{
"current": "12345.00",
"comparison": "10000.00",
"delta_pct": 23.45
}
delta_pct is null when the comparison period value is zero (avoids division by zero).
Comparison Windows
All date-range endpoints accept a compare_to query parameter:
| Value | Comparison window |
|---|---|
prior_period (default) | Same number of days, immediately before the start date |
prior_year | Same date range shifted back 365 days |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
start_date | YYYY-MM-DD | Start of reporting period (default: 30 days ago) |
end_date | YYYY-MM-DD | End of reporting period (default: today) |
store_id | string | Filter by store UUID or Sanity ID (optional) |
compare_to | string | Comparison window: prior_period or prior_year |
The commerce/hourly-traffic/ and active-orders/ endpoints are always real-time and do not accept date parameters.
The system/infrastructure/ endpoint accepts ?days=N (7–365, default 30) instead of date range parameters.
Endpoint Groups
| Group | Prefix | Endpoints |
|---|---|---|
| Commerce | /analytics/commerce/ | overview, sales, products, hourly-traffic |
| Active Orders | /analytics/ | active-orders |
| Operations | /analytics/operations/ | inventory, fulfillment, procurement |
| People | /analytics/people/ | customers, team (stub) |
| Growth | /analytics/growth/ | promotions |
| System | /analytics/system/ | infrastructure |
Domain Services Used
Analytics views delegate all data retrieval to domain-owned services:
| Service | Domain | Used by |
|---|---|---|
TransactionAnalyticsService | transactions | commerce/overview, commerce/sales, operations/fulfillment |
ProductAnalyticsService | products | commerce/overview, commerce/products |
InventoryAnalyticsService | products | commerce/overview, operations/inventory |
CustomerAnalyticsService | users | commerce/overview, people/customers |
ProcurementAnalyticsService | procurement | operations/procurement |
PromotionAnalyticsService | promotions | growth/promotions |
ActiveOperationsService | analytics | active-orders |
InfrastructureService | analytics | system/infrastructure |
ProcurementAnalyticsService and PromotionAnalyticsService are imported lazily — if the module is not available, the endpoint returns empty data rather than an error.