Summary
Add a unified contextual-factor layer that brings together HealthLog’s existing behavioral, treatment, illness, reproductive, travel, and recovery context while also supporting structured manual logging of factors such as alcohol, caffeine, nicotine, meals, hydration, stress, sauna, sleep aids, and other user-defined events.
The goal is not to replace or duplicate existing medication, workout, illness, mood, sleep, or cycle models. Those should remain authoritative. Instead, HealthLog should expose them through a common contextual-factor contract so timelines, analytics, correlations, and Coach features can reason over existing and newly logged contributors consistently.
Problem
HealthLog already stores many factors that can influence later health measurements:
- Medication intake, missed doses, dose changes, and treatment periods.
- Workouts, training load, and recovery.
- Illness episodes and symptoms.
- Mood tags and rated factors.
- Sleep timing and naps.
- Menstrual-cycle context when enabled.
- Travel and timezone changes.
- Environmental context.
However, these contributors live in separate domain models and do not form a unified contextual timeline. HealthLog also lacks a general structured way to record common lifestyle factors such as the time and quantity of alcohol or caffeine consumption.
A simple boolean tag such as “alcohol” is useful, but it cannot answer questions such as whether one drink five hours before sleep differs from four drinks immediately before sleep. The same limitation applies to caffeine quantity and timing, meal timing, nicotine use, hydration, and similar contributors.
Proposed design
1. Common contextual-factor contract
Introduce a stable internal representation or adapter interface that projects existing records into a common analytics shape, for example:
- Stable factor key and category.
- Start time and optional end time.
- Local timezone and canonical timestamp.
- Quantity and unit where applicable.
- Structured attributes.
- Provenance/source.
- Confidence when inferred rather than directly reported.
- Links back to the authoritative underlying record.
- Created, updated, and deleted state.
This does not require one giant polymorphic database table. Existing domain records should remain the source of truth and be projected through adapters. A dedicated event model is appropriate only for factors that currently have no authoritative HealthLog model.
2. New structured lifestyle events
Support user-created events such as:
- Alcohol: standard drinks or grams of ethanol, drink type, start/end time, last drink before sleep, consumed with food.
- Caffeine: amount in mg where known, beverage/product type, time consumed.
- Nicotine: product type, approximate amount, start/end time.
- Meals: meal type, timing, approximate size, optional attributes such as late, spicy, high-fat, or unusually large.
- Hydration: amount and unit.
- Stressful event: timing and optional severity.
- Sleep aids or supplements where these are not already represented as medication.
- Sauna, hot bath, cold exposure, meditation, and similar optional factors.
- Custom user-defined factors with a stable reusable key.
The initial schema should remain general enough that every future factor does not require a new table and migration.
3. Timeline and logging UX
Provide a contextual timeline that combines existing and manually logged contributors without flattening their provenance.
Suggested UX:
- One-tap quick logging for favorites and recent factors.
- Reusable templates, such as “coffee, 120 mg” or “2 standard drinks.”
- Sensible defaults with easy editing of time and quantity.
- Start/end time where duration matters.
- Edit and delete support.
- Optional notes, not required for routine use.
- Clear source labels: manual, Apple Health, medication record, workout, inferred, imported, environment, and so on.
- Optional reminders for a selected factor, but no mandatory daily questionnaire.
4. Data semantics and safeguards
- Store timestamps precisely enough for same-night and next-day analysis.
- Preserve the timezone that applied when the event occurred.
- Define canonical units while retaining the original user-entered unit.
- Treat inferred events separately from confirmed events.
- Make all records exportable and deletable.
- Include new data in account deletion and backup/export flows.
- Avoid silently converting free-text notes into confirmed structured events.
- Encrypt sensitive free text and any fields whose sensitivity matches existing encrypted health-profile data.
- Keep modules optional; users should not be required to track alcohol, nicotine, diet, or other sensitive factors.
Existing contributors that should be projected, not duplicated
The common layer should be able to consume at least:
- Medication intake and adherence events.
- Medication schedule or dose revisions.
- Workouts and activity sessions.
- Illness episodes and symptom logs.
- Mood entries, structured tags, and rated factors.
- Sleep sessions and naps.
- Cycle events where enabled.
- Travel/location periods and timezone changes.
- Environmental-context records.
This avoids creating a second medication or workout ledger merely to support correlations.
Example normalized records
factor: ALCOHOL
start: 2026-07-24T19:15+07:00
end: 2026-07-24T22:40+07:00
quantity: 3
unit: standard_drink
attributes: { withMeal: true }
source: MANUAL
confidence: confirmed
factor: MEDICATION_INTAKE
start: 2026-07-24T08:03+07:00
quantity: 10
unit: mg
source: MEDICATION_LEDGER
referenceId: <existing intake id>
confidence: confirmed
Acceptance criteria
- Existing authoritative records can be projected into a common contextual-factor shape without being copied into a second ledger.
- A user can create, edit, and delete timed lifestyle events with optional quantity and unit.
- At minimum, alcohol, caffeine, nicotine, and meals have structured presets.
- Custom reusable event types are supported without requiring a code release for each personal factor.
- Event timestamps preserve local-time context and remain correct across travel and timezone changes.
- Timeline entries retain source and confidence information.
- New records are covered by export, deletion, backup, and privacy controls.
- The analytics layer can query contextual factors over a bounded date range through one stable interface.
- The implementation includes tests for timezone handling, quantity normalization, edit/delete behavior, source projection, and non-duplication of existing records.
Out of scope for this issue
- Statistical discovery and causal interpretation.
- Proactive Coach explanations.
- Environmental-provider expansion.
- Changes to the Personal Health Score.
Those are better handled by separate feature requests that consume this foundation.
Summary
Add a unified contextual-factor layer that brings together HealthLog’s existing behavioral, treatment, illness, reproductive, travel, and recovery context while also supporting structured manual logging of factors such as alcohol, caffeine, nicotine, meals, hydration, stress, sauna, sleep aids, and other user-defined events.
The goal is not to replace or duplicate existing medication, workout, illness, mood, sleep, or cycle models. Those should remain authoritative. Instead, HealthLog should expose them through a common contextual-factor contract so timelines, analytics, correlations, and Coach features can reason over existing and newly logged contributors consistently.
Problem
HealthLog already stores many factors that can influence later health measurements:
However, these contributors live in separate domain models and do not form a unified contextual timeline. HealthLog also lacks a general structured way to record common lifestyle factors such as the time and quantity of alcohol or caffeine consumption.
A simple boolean tag such as “alcohol” is useful, but it cannot answer questions such as whether one drink five hours before sleep differs from four drinks immediately before sleep. The same limitation applies to caffeine quantity and timing, meal timing, nicotine use, hydration, and similar contributors.
Proposed design
1. Common contextual-factor contract
Introduce a stable internal representation or adapter interface that projects existing records into a common analytics shape, for example:
This does not require one giant polymorphic database table. Existing domain records should remain the source of truth and be projected through adapters. A dedicated event model is appropriate only for factors that currently have no authoritative HealthLog model.
2. New structured lifestyle events
Support user-created events such as:
The initial schema should remain general enough that every future factor does not require a new table and migration.
3. Timeline and logging UX
Provide a contextual timeline that combines existing and manually logged contributors without flattening their provenance.
Suggested UX:
4. Data semantics and safeguards
Existing contributors that should be projected, not duplicated
The common layer should be able to consume at least:
This avoids creating a second medication or workout ledger merely to support correlations.
Example normalized records
Acceptance criteria
Out of scope for this issue
Those are better handled by separate feature requests that consume this foundation.