feat(analytics): monthly totals series with same month last year #85

New issue

Closed

opened 2026-09-24 23:23:40 +00:00 by gabogg · 1 comment

gabogg commented

2026-09-24 23:23:40 +00:00

Owner

Route

GET /api/analytics/timeseries/monthly?end=YYYY-MM&months=13

One row per closed month ending at end: visitors, daily average, mean dwell, quality, and the same month one year earlier (null when there is no data).

Used by

Month view: visitors per month over 13 months against the previous year, and growth vs last year by month.

Notes

This is a comparison series for the Month view, not a Year period (out of scope).
Needs at least 13 months of production history to be complete; the deck must render gaps as "no data", not zero.

Context

Part of the statistics deck redesign, draft RFC in #80 (docs/architecture/rfc-statistics-deck-display-model.md; mockup linked there). Period selection is settled in #81; the parameters below assume a period is identified by granularity (day / week / month) and its first business day. A year period is out of scope.

Shared constraints (all statistics-deck routes)

Periods are closed business periods in facility time (daily_reset_time boundaries, app/facility_time.py); an in-progress cycle is never returned.
Only counted cameras contribute (_COUNTED_CAMERA_JOIN / _COUNTED_CAMERA_FILTER); quarantined events never do.
Every period-level figure carries its data quality: gap-estimated days (ingestion anomaly ledger), Data Trust and Cycle Completeness for the cycles involved, so the deck can mark estimates.
Dwell means the open-window Mean Dwell (ADR 0006), not the retired definitions.
Access is undecided: current analytics routes use require_admin; who can open the deck is open question 7 in the RFC.
Controllers stay thin; aggregation lives in analytics_service, SQL in repositories.

## Route `GET /api/analytics/timeseries/monthly?end=YYYY-MM&months=13` One row per closed month ending at `end`: visitors, daily average, mean dwell, quality, and the same month one year earlier (`null` when there is no data). ## Used by Month view: visitors per month over 13 months against the previous year, and growth vs last year by month. ## Notes - This is a comparison series for the Month view, not a Year period (out of scope). - Needs at least 13 months of production history to be complete; the deck must render gaps as "no data", not zero. ## Context Part of the statistics deck redesign, draft RFC in #80 (`docs/architecture/rfc-statistics-deck-display-model.md`; mockup linked there). Period selection is settled in #81; the parameters below assume a period is identified by `granularity` (`day` / `week` / `month`) and its first business day. A year period is out of scope. ## Shared constraints (all statistics-deck routes) - Periods are **closed** business periods in facility time (`daily_reset_time` boundaries, `app/facility_time.py`); an in-progress cycle is never returned. - Only **counted cameras** contribute (`_COUNTED_CAMERA_JOIN` / `_COUNTED_CAMERA_FILTER`); quarantined events never do. - Every period-level figure carries its data quality: gap-estimated days (ingestion anomaly ledger), **Data Trust** and **Cycle Completeness** for the cycles involved, so the deck can mark estimates. - Dwell means the open-window **Mean Dwell** (ADR 0006), not the retired definitions. - Access is undecided: current analytics routes use `require_admin`; who can open the deck is open question 7 in the RFC. - Controllers stay thin; aggregation lives in `analytics_service`, SQL in repositories.

gabogg added the

needs-triage

label

2026-09-24 23:23:40 +00:00

gabogg referenced this issue

2026-09-24 23:24:08 +00:00

feat(statistics-deck): choose which complete day, week or month the deck shows #81

gabogg commented

2026-09-24 23:31:42 +00:00

Author

Owner

Closing: the Month view no longer shows multi-month or yearly trends (the maintainer ruled yearly scope out; see #80). The month graphs are served by #84 (daily totals) over the month and the previous month. Reopen if a trend view comes back into scope.

gabogg

2026-09-24 23:31:43 +00:00