refactor(insights): move the comprehensive overview builder out of its route

This commit is contained in:
Marc-André Bombeck committed 2026-10-23 15:25:20 +02:00
1 parent 2e13b7754e
commit 98875debf4
11 files changed
+863 -710

No files matched your search

@@ -31,7 +31,7 @@ const CALL_SITES: Array<{ file: string; surface: string }> = [
surface: "insight targets",
},
{
file: "src/app/api/insights/comprehensive/route.ts",
file: "src/lib/insights/comprehensive-overview/medication-compliance.ts",
surface: "comprehensive insight",
},
{
@@ -0,0 +1,198 @@
/**
* The Insights overview's response body, computed from the record.
*
* SQL-side aggregates served by `buildComprehensiveAggregate` replace the
* 100k-row-in-JS aggregation the route once ran; the medication-compliance
* block keeps its bounded Prisma reads (medications + intake events). No
* provider is called anywhere on the path: `hasProvider` is the presence
* probe only.
*
* Every day-bucketing pass (resting-pulse proxy, medication continuity, BP
* pairing) shares the one per-user tz resolved here.
*/
import { prisma } from "@/lib/db";
import { probeProviderPresence } from "@/lib/ai/provider";
import type { DataSummary } from "@/lib/analytics/trends";
import { summarize } from "@/lib/analytics/trends";
import { getBpTargets } from "@/lib/analytics/bp-targets";
import { computeBpInTargetPct } from "@/lib/analytics/bp-in-target";
import {
classifyBMI,
classifyBP,
generateAlerts,
} from "@/lib/analytics/classifications";
import { annotate } from "@/lib/logging/context";
import { buildComprehensiveAggregate } from "@/lib/insights/comprehensive-aggregator";
import { DEFAULT_TIMEZONE } from "@/lib/tz/format";
import { overviewCorrelations } from "./correlations";
import {
bpMedicationContinuity,
readMedicationCompliance,
} from "./medication-compliance";
import { readOverviewMoodSeries } from "./mood-series";
import { readRestingPulseDaily } from "./resting-pulse-daily";
/** Who the overview is computed for: the record, with its zone. */
export interface OverviewRecord {
id: string;
timezone?: string | null;
}
export type ComprehensiveOverviewBody = Awaited<
ReturnType<typeof buildComprehensiveResponse>
>;
/** BMI and the 30-day BP classification against the record's profile. */
function classifyProfile(
summaries: Record<string, DataSummary>,
dbUser: { heightCm: number | null; dateOfBirth: Date | null } | null,
) {
let bmi: number | null = null;
let bmiClassification = null;
if (dbUser?.heightCm && summaries.WEIGHT?.latest) {
const heightM = dbUser.heightCm / 100;
bmi = Math.round((summaries.WEIGHT.latest / (heightM * heightM)) * 10) / 10;
bmiClassification = classifyBMI(bmi);
}
let bpClassification = null;
const bpTargets = getBpTargets(dbUser?.dateOfBirth ?? null);
if (
summaries.BLOOD_PRESSURE_SYS?.avg30 &&
summaries.BLOOD_PRESSURE_DIA?.avg30
) {
bpClassification = classifyBP(
summaries.BLOOD_PRESSURE_SYS.avg30,
summaries.BLOOD_PRESSURE_DIA.avg30,
);
}
return { bmi, bmiClassification, bpClassification, bpTargets };
}
export async function buildComprehensiveResponse(user: OverviewRecord) {
const userId = user.id;
const ninetyDaysAgo = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000);
const userTz = user.timezone || DEFAULT_TIMEZONE;
// Height + DOB drive BMI + BP targets.
const dbUser = await prisma.user.findUnique({
where: { id: userId },
select: {
heightCm: true,
dateOfBirth: true,
},
});
// SQL-side rollup: per-type DataSummary identical to the JS `summarize()`
// semantics over the 90-day window, plus the bounded raw rows the BP target
// adherence pairing needs, plus daily-mean buckets for the correlations.
const aggregate = await buildComprehensiveAggregate(userId);
const { dailyMoodEntries, moodDataPoints, moodEntryCount } =
await readOverviewMoodSeries(userId, ninetyDaysAgo);
const moodSummary =
moodDataPoints.length > 0 ? summarize(moodDataPoints) : null;
const summaries: Record<string, DataSummary> = aggregate.summaries;
const { bmi, bmiClassification, bpClassification, bpTargets } =
classifyProfile(summaries, dbUser);
// BP target adherence over the trailing 90 days, through the canonical
// `computeBpInTargetPct` so this figure shares ONE definition with the
// dashboard tile, the insight cards, the AI snapshot and the targets
// endpoint. The helper pairs sys+dia on the 5-minute window with the
// same-local-day fallback (keyed on the user's OWN tz) and keeps the
// ESH-2023 band + 90/50 hypotension floor. Window is the aggregator's
// 90-day raw pull — a "recent control" figure, not the all-time headline.
let bpPctInTarget: number | null = null;
if (bpTargets) {
bpPctInTarget =
computeBpInTargetPct(
aggregate.bpRawRows.sys,
aggregate.bpRawRows.dia,
bpTargets,
userTz,
)?.pct ?? null;
}
const restingPulseDaily = await readRestingPulseDaily(
userId,
ninetyDaysAgo,
userTz,
);
const sysDaily = aggregate.dailyByType.BLOOD_PRESSURE_SYS ?? [];
const correlations = overviewCorrelations({
aggregate,
dailyMoodEntries,
restingPulseDaily,
userTz,
});
const { medications, medCompliance, bpMedications, bpMedicationEvents } =
await readMedicationCompliance({
userId,
since: ninetyDaysAgo,
timezone: user.timezone || DEFAULT_TIMEZONE,
});
const { bpMedicationCorrelation, bpMedicationScatterData } =
bpMedicationContinuity({ bpMedications, bpMedicationEvents, sysDaily });
const alerts = generateAlerts({
bmi,
bpAvgSys: summaries.BLOOD_PRESSURE_SYS?.avg30 ?? null,
bpAvgDia: summaries.BLOOD_PRESSURE_DIA?.avg30 ?? null,
bpPctInTarget,
weightSlope30: summaries.WEIGHT?.slope30?.slope ?? null,
pulseAvg30: summaries.PULSE?.avg30 ?? null,
pulseAnomalyCount: summaries.PULSE?.anomalyCount ?? 0,
medications: medCompliance.map((m) => ({
name: m.name,
compliance7: m.compliance7,
compliance30: m.compliance30,
})),
});
// Data span — derived from the earliest 90-day measurement.
const dataSpanDays = aggregate.firstMeasurementAt
? Math.ceil(
(Date.now() - aggregate.firstMeasurementAt.getTime()) /
(24 * 60 * 60 * 1000),
)
: 0;
annotate({
action: { name: "insights.comprehensive" },
meta: {
totalMeasurements: aggregate.totalMeasurements,
moodEntries: moodEntryCount,
medications: medications.length,
},
});
return {
summaries,
bmi,
bmiClassification,
bpClassification,
bpPctInTarget,
bpTargets,
weightBpCorrelation: correlations.weightBpCorrelation,
scatterData: correlations.scatterData,
bpMedicationCorrelation,
bpMedicationScatterData,
moodSummary,
moodBpCorrelation: correlations.moodBpCorrelation,
moodBpScatterData: correlations.moodBpScatterData,
moodWeightCorrelation: correlations.moodWeightCorrelation,
moodWeightScatterData: correlations.moodWeightScatterData,
moodPulseCorrelation: correlations.moodPulseCorrelation,
moodPulseScatterData: correlations.moodPulseScatterData,
medications: medCompliance,
alerts,
// Presence only: no client is built and no token is refreshed on a read.
hasProvider: await probeProviderPresence(userId),
dataSpanDays,
totalMeasurements: aggregate.totalMeasurements,
};
}
@@ -0,0 +1,78 @@
/**
* The overview's correlations: weight × systolic, and mood against
* systolic, weight and resting pulse. Pure: every series is already read.
*/
import {
significantPearsonCorrelation,
type PairedPoint,
} from "@/lib/analytics/correlations";
import type { ComprehensiveAggregate } from "@/lib/insights/comprehensive-aggregator";
import {
deriveDailyLocalMeans,
joinDailyByDay,
pairMoodWithDaily,
type DailyValue,
} from "./daily-series";
export function overviewCorrelations(args: {
aggregate: ComprehensiveAggregate;
dailyMoodEntries: DailyValue[];
restingPulseDaily: DailyValue[];
userTz: string;
}) {
const { aggregate, dailyMoodEntries, restingPulseDaily, userTz } = args;
// Weight × Sys BP, daily-key pairing. Both sides come from the UTC
// `dailyByType` series, so they share one UTC day-key space and are
// internally consistent; re-keying it to local migrates with the rollup
// tier.
const weightDaily = aggregate.dailyByType.WEIGHT ?? [];
const sysDaily = aggregate.dailyByType.BLOOD_PRESSURE_SYS ?? [];
const weightBpPairs: PairedPoint[] = joinDailyByDay(weightDaily, sysDaily);
const weightBpCorrelation = significantPearsonCorrelation(weightBpPairs);
const scatterData = weightBpPairs.map((p) => ({
weight: p.a,
sysBP: p.b,
}));
// Mood × {sys BP, weight, pulse}. The mood series is LOCAL-day-keyed and
// `pairMoodWithDaily` joins on an EXACT YYYY-MM-DD key, so the partners
// are exact local-day means from the raw rows already on the request path
// (canonical-source deduped in the aggregator), NOT the UTC `dailyByType` —
// a UTC-day MEAN cannot be relabeled into a local-day mean.
const sysDailyLocal = deriveDailyLocalMeans(aggregate.bpRawRows.sys, userTz);
const weightDailyLocal = deriveDailyLocalMeans(
aggregate.weightRawRows,
userTz,
);
const moodBpPairs = pairMoodWithDaily(dailyMoodEntries, sysDailyLocal);
const moodBpCorrelation = significantPearsonCorrelation(moodBpPairs);
const moodBpScatterData = moodBpPairs.map((p) => ({ mood: p.a, sysBP: p.b }));
const moodWeightPairs = pairMoodWithDaily(dailyMoodEntries, weightDailyLocal);
const moodWeightCorrelation = significantPearsonCorrelation(moodWeightPairs);
const moodWeightScatterData = moodWeightPairs.map((p) => ({
mood: p.a,
weight: p.b,
}));
const moodPulsePairs = pairMoodWithDaily(dailyMoodEntries, restingPulseDaily);
const moodPulseCorrelation = significantPearsonCorrelation(moodPulsePairs);
const moodPulseScatterData = moodPulsePairs.map((p) => ({
mood: p.a,
pulse: p.b,
}));
return {
weightBpCorrelation,
scatterData,
moodBpCorrelation,
moodBpScatterData,
moodWeightCorrelation,
moodWeightScatterData,
moodPulseCorrelation,
moodPulseScatterData,
};
}
@@ -0,0 +1,110 @@
/**
* Day-keyed series helpers for the Insights overview's correlations: local
* day means from raw rows, and the two joins that pair one daily series with
* another.
*/
import type { PairedPoint } from "@/lib/analytics/correlations";
import { userDayKey } from "@/lib/tz/format";
export interface DailyValue {
day: string;
value: number;
}
/**
* Derive exact local-day mean series from raw measurement rows, keyed by the
* user's timezone via `userDayKey`. The mood series is local-day-keyed, and
* `pairMoodWithDaily` joins on an exact YYYY-MM-DD key, so its metric
* partners must be local-day-keyed too. A UTC-day mean (from `dailyByType`)
* cannot be relabeled into a local-day mean, so the mean is recomputed here
* from raw rows already on the request path. `userDayKey` formats via a
* memoised `Intl.DateTimeFormat` — no offset arithmetic — so DST-transition
* days (23 h / 25 h) bucket correctly and the result is host-TZ-independent
* (CI runs UTC). `round2` mirrors the aggregator's `ROUND(AVG, 2)` so
* correlation thresholds don't drift. Returns `{ day, value }[]` sorted ASC
* by day, the shape `pairMoodWithDaily` expects.
*/
export function deriveDailyLocalMeans(
rows: Array<{ measuredAt: Date; value: number }>,
tz: string,
): DailyValue[] {
const byDay = new Map<string, { sum: number; count: number }>();
for (const r of rows) {
const key = userDayKey(r.measuredAt, tz);
const cur = byDay.get(key) ?? { sum: 0, count: 0 };
cur.sum += r.value;
cur.count += 1;
byDay.set(key, cur);
}
return Array.from(byDay.entries())
.sort(([a], [b]) => a.localeCompare(b))
.map(([day, stats]) => ({
day,
value: Math.round((stats.sum / stats.count) * 100) / 100,
}));
}
/**
* Daily-key inner join between two daily-aggregated series. Returns
* `PairedPoint` shapes compatible with `significantPearsonCorrelation`.
*
* Inputs are sorted ASC by `day` (the aggregator's ORDER BY
* guarantees that). The walk is O(n + m) merge-join style instead of
* Map.lookup-per-element so it scales with the worst-case 90 buckets
* x 90 buckets case without surprises.
*/
export function joinDailyByDay(
a: DailyValue[],
b: DailyValue[],
): PairedPoint[] {
const pairs: PairedPoint[] = [];
let i = 0;
let j = 0;
while (i < a.length && j < b.length) {
const ai = a[i];
const bj = b[j];
if (ai.day === bj.day) {
pairs.push({
a: ai.value,
b: bj.value,
date: new Date(`${ai.day}T12:00:00.000Z`),
});
i += 1;
j += 1;
} else if (ai.day < bj.day) {
i += 1;
} else {
j += 1;
}
}
return pairs;
}
/**
* Pair the daily mood series (left side) with a daily-aggregated
* metric (right side). Matches the legacy `buildMoodMetricPairs`
* helper byte-for-byte: same daily YYYY-MM-DD key, same
* `T12:00:00.000Z` anchor for the `date` field.
*/
export function pairMoodWithDaily(
dailyMood: DailyValue[],
dailyMetric: DailyValue[],
): PairedPoint[] {
if (dailyMood.length === 0 || dailyMetric.length === 0) return [];
const metricByDay = new Map<string, number>();
for (const m of dailyMetric) {
metricByDay.set(m.day, m.value);
}
const pairs: PairedPoint[] = [];
for (const mood of dailyMood) {
const metric = metricByDay.get(mood.day);
if (metric !== undefined) {
pairs.push({
a: mood.value,
b: metric,
date: new Date(`${mood.day}T12:00:00.000Z`),
});
}
}
return pairs;
}
@@ -0,0 +1,235 @@
/**
* The overview's medication block: per-medication compliance over 7 and 30
* days, and the blood-pressure medication continuity × systolic correlation
* that pairs the BP medications' intake days with the daily systolic means.
*/
import { prisma } from "@/lib/db";
import {
buildComplianceMedicationContext,
COURSES_COMPLIANCE_SELECT,
calculateCompliance,
expectsDoses,
lastNonSkippedTakenAt,
SCHEDULE_COMPLIANCE_SELECT,
} from "@/lib/analytics/compliance";
import { significantPearsonCorrelation } from "@/lib/analytics/correlations";
import { resolveMedicationCategories } from "@/lib/medication-category";
import { TRACKED_INTAKE_WHERE } from "@/lib/medications/intake-tracking";
import { dayKeyAsUtcMidnight } from "@/lib/tz/date-only";
import type { DailyValue } from "./daily-series";
interface BpIntakeEvent {
scheduledFor: Date;
takenAt: Date | null;
skipped: boolean;
}
/** Read the tracked scheduled medications with what compliance needs. */
async function readScheduledMedications(userId: string) {
const medicationRows = await prisma.medication.findMany({
// As-needed (PRN) medications never surface a compliance rate (no
// expected doses).
where: { userId, active: true, asNeeded: false, ...TRACKED_INTAKE_WHERE },
include: {
// Schedules through the shared compliance select so the configured
// per-dose windows reach this surface like every other.
schedules: { select: SCHEDULE_COMPLIANCE_SELECT },
// Archived schedule eras for era-aware compliance.
scheduleRevisions: { orderBy: { validFrom: "asc" } },
// Pause eras so paused days drop out of the denominator.
pauseEras: { select: { pausedAt: true, resumedAt: true } },
// The courses, so a gap between two expects nothing (#1024).
courses: COURSES_COMPLIANCE_SELECT,
},
});
// A medication with no schedule expects no dose, and `calculateCompliance`
// answers 100 % for that case. The `asNeeded: false` filter above catches
// only the PRN arm; the empty schedule is reachable on a scheduled
// medication and would otherwise report perfect adherence.
return medicationRows.filter(expectsDoses);
}
/**
* Per-medication compliance, plus the intake events of the blood-pressure
* medications for the continuity correlation.
*/
export async function readMedicationCompliance(args: {
userId: string;
since: Date;
timezone: string;
}) {
const { userId, since, timezone } = args;
const medications = await readScheduledMedications(userId);
const resolvedCategories = await resolveMedicationCategories(
medications.map((m) => m.id),
);
const categoryMap = Object.fromEntries(
Object.entries(resolvedCategories).map(([id, r]) => [id, r.category]),
);
const medCompliance = [];
const bpMedicationEvents: BpIntakeEvent[] = [];
const bpMedications = medications.filter(
(med) => (categoryMap[med.id] ?? "OTHER") === "BLOOD_PRESSURE",
);
// Single round-trip for all medications instead of N+1: one query keyed
// on `medicationId IN (...)`, then group in memory.
const allEvents = medications.length
? await prisma.medicationIntakeEvent.findMany({
where: {
medicationId: { in: medications.map((m) => m.id) },
userId,
// Tombstoned rows are excluded.
deletedAt: null,
scheduledFor: { gte: since },
},
orderBy: { scheduledFor: "desc" },
})
: [];
const eventsByMed = new Map<string, typeof allEvents>();
for (const ev of allEvents) {
const list = eventsByMed.get(ev.medicationId);
if (list) list.push(ev);
else eventsByMed.set(ev.medicationId, [ev]);
}
for (const med of medications) {
const events = eventsByMed.get(med.id) ?? [];
const mapped = events.map((e) => ({
takenAt: e.takenAt,
skipped: e.skipped,
scheduledFor: e.scheduledFor,
}));
// Engine-routed denominator.
const medicationContext = buildComplianceMedicationContext(
med,
lastNonSkippedTakenAt(mapped),
timezone,
);
const c7 = calculateCompliance(mapped, med.schedules, 7, med.createdAt, {
medicationContext,
});
const c30 = calculateCompliance(mapped, med.schedules, 30, med.createdAt, {
medicationContext,
});
medCompliance.push({
id: med.id,
name: med.name,
dose: med.dose,
category: categoryMap[med.id] ?? "OTHER",
// The label of a custom category; null for a built-in (#1041).
categoryLabel: resolvedCategories[med.id]?.categoryLabel ?? null,
compliance7: c7.rate,
compliance30: c30.rate,
streak: c7.streak,
taken7: c7.taken,
skipped7: c7.skipped,
missed7: c7.missed,
});
if ((categoryMap[med.id] ?? "OTHER") === "BLOOD_PRESSURE") {
bpMedicationEvents.push(
...events.map((e) => ({
scheduledFor: e.scheduledFor,
takenAt: e.takenAt,
skipped: e.skipped,
})),
);
}
}
return { medications, medCompliance, bpMedications, bpMedicationEvents };
}
/**
* Correlation: BP medication continuity × systolic BP.
*
* Uses the same daily BP_SYS series the aggregator pre-computed — no second
* round-trip. The intake-side aggregation matches the legacy code:
* continuity = min(1, taken / expectedPerDay), pairing every day that had a
* sys reading.
*/
export function bpMedicationContinuity(args: {
bpMedications: Array<{ schedules: unknown[] }>;
bpMedicationEvents: BpIntakeEvent[];
sysDaily: DailyValue[];
}) {
const { bpMedications, bpMedicationEvents, sysDaily } = args;
let bpMedicationCorrelation: {
r: number;
strength: string;
n: number;
medicationCount: number;
} | null = null;
const bpMedicationScatterData: Array<{
continuityPct: number;
sysBP: number;
}> = [];
const expectedBpIntakesPerDay = bpMedications.reduce(
(sum, med) => sum + med.schedules.length,
0,
);
if (expectedBpIntakesPerDay > 0) {
// Daily systolic means (already keyed YYYY-MM-DD) from the SQL pass.
// `sysDaily` (UTC `date_trunc` from the aggregator's `dailyByType`) and
// `takenByDay` below (intake `scheduledFor` truncated to UTC) both live
// in the SAME UTC day-key space and are internally consistent with each
// other, so this join stays UTC. Only the mood pairings moved to a
// separately derived local-day series (their partner, the mood series,
// is local-day-keyed). This correlation migrates to local when the
// measurement-rollup tier buckets per-user tz; re-keying it here without
// the local-bucketed rollup would mean per-request raw re-aggregation.
const sysByDay = new Map<string, number>();
for (const row of sysDaily) {
sysByDay.set(row.day, row.value);
}
const takenByDay = new Map<string, number>();
// Days that carry an intake record of ANY kind. A logged skip is a real
// zero and belongs in the series; a day the person never touched is not a
// zero, it is nothing, and pairing it against that day's systolic reading
// invented a data point they never produced. Absence is not zero, here as
// everywhere else in this project, so the unlogged day drops out of both
// the scatter and the coefficient rather than dragging continuity down.
const loggedDays = new Set<string>();
for (const event of bpMedicationEvents) {
// eslint-disable-next-line healthlog/no-utc-day-key -- UTC by design: pairs intake days with the DAY rollup buckets in sysByDay, which are UTC days
const dayKey = event.scheduledFor.toISOString().slice(0, 10);
loggedDays.add(dayKey);
if (event.skipped || !event.takenAt) continue;
takenByDay.set(dayKey, (takenByDay.get(dayKey) ?? 0) + 1);
}
const pairs: Array<{ a: number; b: number; date: Date }> = [];
for (const [dayKey, avgSys] of sysByDay.entries()) {
if (!loggedDays.has(dayKey)) continue;
const taken = takenByDay.get(dayKey) ?? 0;
const continuity = Math.min(1, taken / expectedBpIntakesPerDay);
pairs.push({
a: continuity,
b: avgSys,
date: dayKeyAsUtcMidnight(dayKey),
});
bpMedicationScatterData.push({
continuityPct: Math.round(continuity * 100),
sysBP: Math.round(avgSys * 10) / 10,
});
}
const corr = significantPearsonCorrelation(pairs);
if (corr) {
bpMedicationCorrelation = {
...corr,
medicationCount: bpMedications.length,
};
}
}
return { bpMedicationCorrelation, bpMedicationScatterData };
}
@@ -0,0 +1,92 @@
/**
* The overview's 90-day mood series, read from the mood-rollup DAY tier.
*
* The two consumers downstream — `dailyMoodEntries` for the mood × metric
* correlations and the mood summary for the dashboard mood block — read at a
* per-day resolution, which is precisely the shape the rollup writer emits,
* so the tier replaces an unbounded `prisma.moodEntry.findMany`.
*
* Coverage-fallback: when the user has mood entries but zero rollup rows yet
* (legacy account before the boot-time backfill has caught up), fall back to
* a bounded 90-day raw walk once and fire the warm-up so the next request
* lands on the rollup tier. Same posture as `/api/mood/analytics`.
*
* The mood rollup writer mints `bucketStart` from the canonical local
* `MoodEntry.date` label at UTC midnight, so `.toISOString().slice(0, 10)`
* recovers the user's LOCAL calendar day — byte-identical to the live
* fallback's `entry.date`. Both mood paths therefore emit local-day keys, and
* the mood × metric pairing partners (sys BP, weight, resting pulse) are
* derived in the user's tz so both join sides share ONE local-day key space.
* The measurement-rollup tier itself still buckets UTC (`dailyByType`); the
* two internally-consistent UTC joins (weight × BP, BP-med continuity) are
* left on it deliberately (see their call sites in `build.ts`).
*/
import { prisma } from "@/lib/db";
import type { DataPoint } from "@/lib/analytics/trends";
import {
ensureUserMoodRollupsFresh,
readMoodDayRollups,
} from "@/lib/rollups/mood-rollups";
import { dateOnlyKey } from "@/lib/tz/date-only";
import type { DailyValue } from "./daily-series";
export interface OverviewMoodSeries {
dailyMoodEntries: DailyValue[];
moodDataPoints: DataPoint[];
moodEntryCount: number;
}
export async function readOverviewMoodSeries(
userId: string,
since: Date,
): Promise<OverviewMoodSeries> {
void ensureUserMoodRollupsFresh(userId);
const moodRollupDayRows = await readMoodDayRollups(userId, since);
if (moodRollupDayRows.length > 0) {
return {
dailyMoodEntries: moodRollupDayRows.map((r) => ({
day: dateOnlyKey(r.bucketStart),
value: Math.round(r.mean * 100) / 100,
})),
moodDataPoints: moodRollupDayRows.map((r) => ({
date: r.bucketStart,
value: r.mean,
})),
moodEntryCount: moodRollupDayRows.reduce((s, r) => s + r.count, 0),
};
}
// Coverage-fallback: legacy account with mood entries but no
// rollup coverage yet. Bounded by the 90-day window so the walk is
// capped even when the rollup miss happens.
const moodEntries = await prisma.moodEntry.findMany({
// Tombstoned rows are excluded.
where: { userId, deletedAt: null, moodLoggedAt: { gte: since } },
orderBy: { moodLoggedAt: "asc" },
select: { date: true, score: true, moodLoggedAt: true },
});
const moodByDay = new Map<string, { sum: number; count: number }>();
for (const entry of moodEntries) {
const current = moodByDay.get(entry.date) ?? { sum: 0, count: 0 };
current.sum += entry.score;
current.count += 1;
moodByDay.set(entry.date, current);
}
const dailyMoodEntries = Array.from(moodByDay.entries())
.sort(([a], [b]) => a.localeCompare(b))
.map(([day, stats]) => ({
day,
value: Math.round((stats.sum / stats.count) * 100) / 100,
}));
return {
dailyMoodEntries,
// Per-day means feed `summarize()` so the live-fallback path shares the
// rollup-tier semantic (one DataPoint per day, the daily mean), the same
// reading mood/analytics uses.
moodDataPoints: dailyMoodEntries.map((e) => ({
date: new Date(`${e.day}T12:00:00.000Z`),
value: e.value,
})),
moodEntryCount: moodEntries.length,
};
}
@@ -0,0 +1,49 @@
/**
* The Insights overview read: the computed body through the analytics
* cache. The route resolves the per-request AI state beside it, which is
* never cached with the body.
*/
import { annotate } from "@/lib/logging/context";
import {
cachedSwrWithMeta,
caches,
type ServerCache,
} from "@/lib/cache/server-cache";
import {
buildComprehensiveResponse,
type ComprehensiveOverviewBody,
type OverviewRecord,
} from "./build";
export async function readComprehensiveOverview(
user: OverviewRecord,
): Promise<{ body: ComprehensiveOverviewBody; revalidating: boolean }> {
// Read-through the analytics cache keyed on (userId, "comprehensive"). The
// /insights page mount routinely fans out to this endpoint alongside the
// Coach drawer + the recommendations grid; the 60s TTL converts every
// duplicate mount within the window to a Map lookup. Invalidation is
// handled by `invalidateUserMeasurements`, which marks every key under the
// `${userId}|` prefix stale (see `lib/cache/invalidate.ts`).
//
// Stale-while-revalidate: this is the single heaviest SQL-side aggregation
// on the /insights mount; serving the prior body instantly while ONE
// background recompute refreshes it keeps the page interactive across the
// bucket's 10-minute stale window (a measurement sync used to bust the
// entry into a blocking cold rebuild on the very next mount, all day). The
// truly-cold first read of the day still computes inline — there is no
// prior body to serve — but it no longer recurs per visit.
//
// The `revalidating` flag marks a stale-served body honestly so the client
// can poll (bounded) until the background rebuild lands — mirroring the
// `/api/insights/generate` GET contract. It rides on the response, never
// inside the cached body, so a warmed entry doesn't freeze the flag.
const { value: body, outcome } = await cachedSwrWithMeta(
caches.analytics as ServerCache<ComprehensiveOverviewBody>,
`${user.id}|comprehensive`,
() => buildComprehensiveResponse(user),
annotate,
);
return { body, revalidating: outcome === "stale" };
}
@@ -0,0 +1,65 @@
/**
* The overview's daily resting-pulse series, the mood × pulse correlation's
* partner.
*
* The correlation is labelled "Resting pulse (bpm)", so it is scored against
* the RESTING series, not the raw PULSE day-mean: the aggregator's
* `dailyByType.PULSE` is a per-day AVG that folds in workout HR for
* Apple-Health users and inflates the "resting" figure. The clean
* RESTING_HEART_RATE rows win; only without them does the low-percentile
* daily proxy over raw pulse stand in. The proxy folds in Postgres (#1023):
* it needs one percentile per day, and reading the raw samples to get it
* walked 130 000 rows per page view on a watch that records once a minute.
*
* Keyed on `userDayKey(d, userTz)`: its only pairing partner is the mood
* series, which is local-day-keyed, and a UTC key here would offset every
* evening logger west of UTC by one day and sell a lag-1 correlation as
* same-day. Unlike the mood side, this series builds from raw rows, so it
* re-keys directly with no rollup-tier change.
*/
import { prisma } from "@/lib/db";
import { resolveRestingPulseSeries } from "@/lib/analytics/resting-pulse";
import { readRestingPulseProxy } from "@/lib/analytics/resting-pulse-read";
import { userDayKey } from "@/lib/tz/format";
import type { DailyValue } from "./daily-series";
export async function readRestingPulseDaily(
userId: string,
since: Date,
userTz: string,
): Promise<DailyValue[]> {
const restingPulseRows = await prisma.measurement.findMany({
where: {
userId,
type: "RESTING_HEART_RATE",
deletedAt: null,
measuredAt: { gte: since },
},
select: { measuredAt: true, value: true },
});
const localDayKey = (d: Date) => userDayKey(d, userTz);
const restingPulseSeries =
restingPulseRows.length > 0
? resolveRestingPulseSeries({
restingSamples: restingPulseRows,
pulseSamples: [],
dayKeyOf: localDayKey,
}).series
: await readRestingPulseProxy({
userId,
since,
timeZone: userTz,
});
const restingByDay = new Map<string, { sum: number; count: number }>();
for (const s of restingPulseSeries) {
const key = localDayKey(s.measuredAt);
const cur = restingByDay.get(key) ?? { sum: 0, count: 0 };
cur.sum += s.value;
cur.count += 1;
restingByDay.set(key, cur);
}
return Array.from(restingByDay.entries())
.sort(([a], [b]) => a.localeCompare(b))
.map(([day, stats]) => ({ day, value: stats.sum / stats.count }));
}