Clinical Application for Tracking and Managing Autoimmune Diseases

This is the alpha version of Theme Health, focused on the data collection phase. The core of this release establishes the foundational infrastructure for capturing, storing, and beginning to make sense of patient health data across MS, RA, and Lupus.

1. Onboarding & Health Profile Setup The onboarding flow captures a patient complete health baseline without requiring clinical credentials. The API covers diagnosis timeline, primary and secondary condition selection, medication mapping with real side-effect statistics drawn from existing user data, symptom baselines, flare frequency history, demographics, and wearable device preferences. Race conditions on account creation are handled gracefully, profile completion scores are initialized (35–40% at baseline), and default user preferences are seeded — ensuring a clean, fully initialized profile on first login.

At the end of onboarding, the /community_insight endpoint fires — querying community posts and extracted entities for the user's condition and medications, passing the data to Claude AI, and returning a personalized community insight with cohort size and confidence level (e.g., "Many people with MS on Methotrexate report that fatigue peaks in the first few weeks. Most find it stabilizes after 2–3 months."). This gives every new patient immediate, relevant context before they've logged a single check-in.

2. Daily Check-In — The Core Data Collection Engine The daily check-in is the heartbeat of the data collection phase. Each submission via POST /v1/checkin/daily captures:

• Energy level, and severity scores for Pain, Stress, Fatigue, and Brain Fog

• Comparison to baseline ("about the same", "worse", "better")

• Triggers — both from a condition-scoped master list and free-text custom triggers created by the user

• Medication adherence status

• Additional symptoms beyond the four static ones, including custom symptom names

• Time-of-day context (morning, afternoon, evening) derived from the client-side timestamp in the user's local timezone

Every submission returns a motivational message, the user's current consecutive day streak, and asynchronously fires a background insight generation job — so AI processing never blocks the response. A companion Boost Accuracy flow (GET/POST /v1/checkin/boost-accuracy) incrementally captures activity level, age range, region, and work status, pushing profile completion toward 100% over time.

3. Flare Reporting The POST /v1/flare/report endpoint captures disease exacerbation events with structured severity scoring (mild = 3, moderate = 6, severe = 9), relative start date resolution, full symptom and trigger logging, and a supportive message generated from the patient's personal flare history. If notifications are enabled in Supabase user preferences, a follow-up check-in is automatically scheduled 4 hours post-report. Flares are tagged as user_reported in the flare_history table — laying the groundwork to distinguish self-reported events from algorithm-detected drift events in future releases.

4. Apple Watch & Fitbit Data Ingestion The POST /v1/wearable/data endpoint accepts 14 biometric metrics per submission from Apple Watch and Fitbit — HRV, resting heart rate, sleep duration and efficiency, deep/REM/light/awake sleep stages, steps, active calories, SpO2, respiratory rate, and exercise type. All data is persisted in Supabase across wearable_device_master and wearable_data_points tables. Device management is fully automated: new devices register on first submission, previously disconnected devices reactivate without data loss, and users can toggle connection status via PUT /v1/wearable/connection or retrieve their full device history via GET /v1/wearable/devices.

5. Personalized Community Insights at Onboarding The /community_insight endpoint is the alpha's first AI-powered feature. It accepts the user's condition and medication list as query parameters, queries the extracted_entities tables for community-sourced discussions relevant to that profile, and passes the data to Claude AI to generate a personalized insight. The response includes the insight text, cohort size, and a confidence level (low / medium / high). This is the first moment a patient sees that the platform knows something specific about people like them — before they've contributed any data of their own.

6. Drift Detection — Laying the Early Warning Foundation The GET /v1/drift_detection endpoint runs z-score analysis against each user's personal Supabase-stored baseline. For each metric — energy, stress, fatigue, pain, brain fog — it computes the user's personal mean and standard deviation across all historical check-ins, then calculates the z-score for the most recent day. Energy is flagged at z < -2.0 (significant decline); all other metrics are flagged at z > +2.0 (significant spike). Human-readable descriptions are returned for every flagged metric. In this alpha phase, this endpoint establishes the statistical foundation for the proactive flare prediction layer planned for the next release.