Engineering Patient Retention: How MealCircle Tracks Adherence, Not Just Meals

Why "Retention-First" Changes the Data Model

Most nutrition apps model meals. MealCircle models adherence — the relationship between what a patient was coached to do and what they actually did. That distinction sounds minor. It changes the entire data model.

A meal log entry in a traditional nutrition app is a nutritional record: calories, macros, meal time. A meal log entry in MealCircle is an adherence data point: did the patient follow the coach's recommendation, did the meal match their stated goal, and where does this data point land on the patient's compliance curve over time?

The Adherence Data Model

CREATE TABLE care_plan_targets (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    patient_id  UUID NOT NULL REFERENCES patients(id),
    practice_id UUID NOT NULL REFERENCES practices(id),
    week_start  DATE NOT NULL,
    targets     JSONB NOT NULL,  -- {calories: 1800, protein_g: 120, ...}
    set_by      UUID REFERENCES coaches(id),
    created_at  TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE meal_logs (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    patient_id      UUID NOT NULL REFERENCES patients(id),
    practice_id     UUID NOT NULL REFERENCES practices(id),
    logged_at       TIMESTAMPTZ NOT NULL,
    meal_data       JSONB NOT NULL,
    -- Adherence context
    target_week_id  UUID REFERENCES care_plan_targets(id),
    adherence_score NUMERIC(3,2) GENERATED ALWAYS AS (
        compute_adherence(meal_data, target_week_id)
    ) STORED
);

Each meal log is linked to the care plan target that was active during that week. Adherence score is computed at write time and stored — making weekly and monthly aggregations fast without recalculating on every dashboard load.

The Retention Risk Score

The retention risk score surfaces at the practice dashboard level — coaches see at a glance which patients are trending toward churn before they miss their next appointment.

The signal is based on three weighted factors:

1. Logging frequency: Patient logging less than 3 days per week in the last two weeks — high churn predictor
2. Adherence trend: Adherence score declining week-over-week for 3 or more consecutive weeks
3. Session gap: More than 14 days since last coach interaction or message

def compute_retention_risk(patient_id: str, practice_id: str) -> float:
    """Returns a 0–1 risk score. Above 0.7 surfaces as high-risk in the dashboard."""
    logging_freq = get_recent_logging_frequency(patient_id, days=14)
    adherence_trend = get_adherence_trend(patient_id, weeks=3)
    session_gap = get_days_since_last_interaction(patient_id, practice_id)

    freq_score = max(0, 1 - (logging_freq / 3))  # 0 if logging daily, 1 if not logging
    trend_score = 1 if adherence_trend < -0.1 else 0  # declining adherence
    gap_score = min(1, session_gap / 21)  # normalised to 0–1 over 21-day window

    return (freq_score * 0.4) + (trend_score * 0.35) + (gap_score * 0.25)

This is the same predictive scoring logic that appears in the CCM/PCM Operations Platform case study — applied there to employee performance in care coordination, applied here to patient engagement. The engineering pattern is the same: aggregate behavioral signals, compute a risk score, surface it as a proactive action item.

What This Looks Like for Practices

Dietitians using MealCircle open their dashboard and see a prioritized list of patients — with the highest-risk ones at the top, not buried in a flat alphabetical list. They spend less time reviewing logs manually and more time on interventions that actually prevent dropout.

See the for clinics page for how this is positioned for nutrition practices, and the features page for the full product capability set.

Building predictive scoring or retention analytics into a custom healthcare platform is a core part of the Custom Practice Management service.