What this is
Swappr’s admin dashboard has two kinds of charts:- “What is true right now?” — total users, active listings, mutual matches, recently-active chats, MRR/ARR. Recomputed against the live collections.
- “How has it trended?” — DAU/MAU, new users, trial→paid, churn, top boroughs. Read from a per-day snapshot table.
lastSeenAt scans on every admin browse. Computing the “right now” totals from yesterday’s snapshot would make the dashboard misleading immediately after launch. Swappr ships both paths, side by side.
This page documents that split, the rollup pipeline that backs the trend surface, and the limitations of the launch-slice implementation (QUESTIONS.md §10.2, SWAPPR_BACKEND_PLAN.md §5 + §13).
These are product analytics for the admin dashboard — they complement, not replace, the operational dashboards (worker queue health, error rates, latency p95s). Operational metrics live in your observability stack, not in
analytics_daily.The two paths at a glance
The overview path (live + 60s cache)
getOverview() is intentionally simple:
- Cache hit? Return the cached snapshot verbatim.
computedAtwill reflect the original compute time, so the client can see exactly how stale the snapshot is. - Cache miss? Issue every counter query in parallel (
Promise.allovercountDocumentsand the MRR aggregation), build the snapshot, write it to the cache withTTL = 60s, return it.
How each counter is computed
The rollup path (nightly)
The cohorts and locations surfaces read fromanalytics_daily — one row per UTC date, populated by the nightly rollup worker.
Schedule
The job is a BullMQ scheduled job that runs 02:00 UTC daily and computes yesterday’s row. The cron is deliberately staggered with the other heavy nightly jobs so they do not pile up:The job
The handler is intentionally a thin shell —yesterdayKey → compute → upsert → log. Pure logic lives in the ./analytics-rollup.ts handler; Mongo specifics live in ./analytics-rollup.adapter.ts. The store is a port (AnalyticsRollupStore), so unit tests inject an in-memory fake.
Idempotency
Upsert is keyed ondate (a unique index). Re-running the job for the same day overwrites the row in place — no duplicate analytics_daily rows can exist for a given UTC date. The worker can therefore be re-kicked safely after a failure, and a backfill loop can run a date range without special-casing collisions.
Failure semantics
The handler does not swallow errors fromcompute or upsert. A partial row would silently skew the trend chart. Any exception propagates to the BullMQ wrapper, which applies its retry policy. A failed nightly run is loud, observable, and self-healing on retry.
How each rollup metric is computed
Borough derivation
topBoroughs does not use official London-borough names. It groups by the UK postcode outward-area code, stripping any alpha subdistrict letter so the geography aligns with Royal Mail areas rather than councils:
This is good enough for “where are listings concentrated?” but the field is a key, not a label. Front-ends that want council names should map the area to a council via a static lookup.
Staleness contract
A client that needs “right now” totals must use
overview. A client that needs trend lines must use cohorts. These are not interchangeable.
MVP limitations
These are documented inanalytics-rollup.adapter.ts and flagged in each endpoint page. Listed once here as the canonical reference.
topBoroughs.demandHits is hard-zero
The spec calls for demandHits to count user_preferences whose desired-radius covers each borough’s centroid (i.e. “how many people want to live here”). That requires:
- A per-borough centroid lookup table (lat/lng per outward area).
- A
$geoWithinaggregation per borough, ideally driven off an indexed geo column.
demandHits: 0 for every row, so ranking is listingCount only. A one-time log line at worker boot reminds operators:
churn30d uses updatedAt as a proxy
The subscriptions collection has no dedicated statusChangedAt field. Any subscription whose current status is CANCELLED or EXPIRED and whose updatedAt falls in the trailing 30 days is counted as churn.
False positives are possible if a CANCELLED row was touched for an unrelated reason — e.g. a tax-metadata refresh, a webhook backfill, a manual admin edit. Acceptable for the dashboard. Not acceptable for accounting: do not reconcile financial reports against this number.
totalMatches uses the “mutual save” proxy
totalMatches counts matches rows where both savedByA and savedByB are non-null — i.e. both sides have saved each other. It is not a gate on chat: any engine match can open a conversation, so activeChats can exceed it. The overview’s totalEngineMatches counts every undismissed engine match.
trialToPaid does not count trial drops
TRIALING → ACTIVE (conversion) is counted; TRIALING → CANCELLED (drop) is not. This is correct by definition — a trial drop is not a conversion — but the metric is conversion count, not trial-outcome breakdown. If you want the conversion rate you also need the count of TRIALING cohorts started in the same window; that is not currently a stored metric.
Not in this surface
To set expectations on whatanalytics_daily deliberately does not capture:
- No PII. Rows are aggregate counts only — no user ids, no emails, no postcodes (only the outward-area key).
- No tenant dimension. Counters are platform-wide. The launch product is single-tenant.
- No per-cohort drill-down.
dauis a count; there is no list of which users were active. The audit log + user-search APIs serve that need. - No operational metrics. Queue depth, error rates, latency p95s — those live in your observability stack (Datadog/Grafana/etc.), not here.
See also
- Admin analytics overview — the live counter endpoint.
- Admin analytics cohorts — per-day trend metrics.
- Admin analytics locations — top boroughs.
- Worker bootstrap and queues — how the rollup job is scheduled alongside retention + erasure.
- Tenancy retention — the 03:00 UTC job that runs an hour after the rollup.
- GDPR data lifecycle — the 04:00 UTC erasure job.
apps/worker/src/jobs/analytics-rollup.ts— handler (source of truth).apps/worker/src/jobs/analytics-rollup.adapter.ts— Mongo store adapter, where each metric’s query lives.packages/db/src/models/analytics-daily.ts— the row schema.