feat(analytics): add churn risk scoring provider

[storm-beyndtech]

Closes #521

Adds GetChurnRiskProvider, which flags users whose activity in the most recent
bucket has dropped sharply against their own historical baseline. Accepts
DateRangeDto with optional granularity and returns a typed
AnalyticsMetricResult.

On the data source

Following up on my comment in the issue, since this shaped the implementation.

Churn risk is a per-user metric, but retention_cohorts is cohort-level and
carries no userId, so it can't produce per-user flags. The fallback is raw
analytics_events, which had no indexes at all — while every other module
indexes this shape (progress.entity.ts has ['userId','attemptedAt']).

So "query pre-aggregated tables where one exists" and "index-backed, no full
table scan" couldn't both be satisfied as the repo stood. I took the cheaper of
the two paths: index analytics_events and aggregate in Postgres, rather than
introduce a per-user rollup entity plus an aggregation job, which is a much
larger change than the two files the issue lists.

If you'd rather have the rollup, the scoring logic transfers unchanged —
only fetchBucketCounts gets swapped. Happy to do that in a follow-up, or redo
this PR that way if you prefer it up front.

The query aggregates via date_trunc + GROUP BY, so only one row per
(user, bucket) crosses the wire rather than every raw event.

On the scoring

The hard part isn't the drop calculation, it's that a naive frequency ratio
flags the wrong people. A user doing 40 puzzles a day who drops to 8 reads as an
80% collapse; a user doing one a day who stops entirely reads as a smaller move.

So the drop is divided by that user's own standard deviation. A naturally spiky
player needs a much larger drop to flag than a metronomic one. There's a test
covering exactly this: two users land on an identical recent count, and the
steady one scores 100 while the spiky one scores 27.

Decisions worth pushing back on

• ACTIVITY_EVENT_TYPES excludes one-shot onboarding events. Including them
  would inflate a new user's first buckets and manufacture a "sharp drop" for
  every account the week after signup. It also excludes xp_awarded and
  user_leveled_up, which are consequences of the actions already counted. This
  is an opinion about the taxonomy — easy to disagree with.
• Baseline starts at a user's first observed activity, not the range start,
  so accounts aren't penalised for buckets that predate signup. From there,
  silent buckets are materialised as zeros; dropping them would average only the
  active days and hide the decline. Both behaviours have tests.
• Insufficient history returns null, not 0, matching how cohortSize === 0
  already returns null instead of dividing. A 0 would render as "no risk" for a
  user we know nothing about.
• Buckets are pinned to UTC so boundaries don't move with the DB session
  timezone, and the JS grid mirrors date_trunc exactly, including Monday-start
  weeks. This is the most fragile part of the change and the bit I'd most want a
  second pair of eyes on.
• A missing start defaults to a bounded 90-day lookback rather than epoch.
  The existing providers default to new Date(0), which against an unindexed
  table is a scan of everything.

Known limitation

A user who went quiet early in the window scores modestly (22, "low") even
though they're plainly gone — this measures the drop, and by then the
transition already happened outside the comparison. I nearly folded a dormancy
term into the score and deliberately didn't: it would have over-flagged exactly
the spiky users the variance normalisation exists to protect.

Instead consecutiveSilentBuckets is reported unscored, and there's a test
asserting the 22 with a comment explaining why. Sustained dormancy probably
wants its own metric — worth your call.

Other changes

• AnalyticsMetricResult.data was hardcoded to RetentionDataPoint[], so it's
  now AnalyticsMetricResult<T = RetentionDataPoint>. The default keeps the
  retention provider, its spec, and the users/retention route compiling
  unchanged.
• Adds GET /analytics/users/churn-risk behind AnalyticsAdminGuard, matching
  the route added in Add /analytics/users/retention endpoint #527. Because the result type is now generic, the response
  schema is declared with ApiExtraModels + getSchemaPath rather than
  @ApiResponse({ type: ... }) — the latter would advertise RetentionDataPoint
  as the element type. Happy to align both routes on one style if you prefer.
• Drops an unused ApiQuery import while restructuring that import block.

Rebased onto main after #588, #586 and #583. The only conflict was
analytics.module.ts, where #588 added AnalyticsService to the same arrays.

Verification

• tsc --noEmit — clean
• jest src/analytics — 30/30 passing, 4 suites (17 new, 13 existing). Both
  existing analytics specs still pass, so the generic change didn't break
  retention.
• eslint on the changed files — clean

Heads-up on lint

npm run lint is eslint "{src,apps,libs,test}/**/*.ts" --fix — --fix is
baked into the script. On Windows with core.autocrlf=true it rewrites line
endings across the entire backend and produces a ~170-file diff. It's a footgun
for any Windows contributor, given CONTRIBUTING tells everyone to run it before
a PR. Might be worth splitting into lint and lint:fix.

Separately, lint exits 1 on main already — 112 pre-existing errors in
health.*, main.ts and others, none in this PR's files. So a red lint check
here isn't from these changes.

[vercel]

@storm-beyndtech is attempting to deploy a commit to the aminubabafatima8-gmailcom's projects Team on Vercel.

A member of the Team first needs to authorize it.

[A6dulmalik]

Kindly resolve conflict and have the CI checks pass too. Thank you
@storm-beyndtech

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
mind-block-app-frontend	Skipped		Jul 22, 2026 4:19pm

[storm-beyndtech]

Sure @A6dulmalik, done, and you're welcome