normogen/docs/implementation/PHASE28_COMPLETE_SPECS_V1.md

Phase 2.8 - Complete Technical Specifications

Status: Planning Phase
Created: 2026-03-07
Version: 1.0

---

🔔 YOUR INPUT NEEDED

I have created detailed technical specifications for all 7 Phase 2.8 features. Before implementation begins, please review and answer the CRITICAL QUESTIONS below.

---

Table of Contents

1. Drug Interaction Checker ⚠️ CRITICAL
2. Automated Reminder System ⭐ HIGH
3. Advanced Health Analytics ⭐⭐ MEDIUM
4. Healthcare Data Export ⭐⭐⭐ MEDIUM
5. Medication Refill Tracking ⭐⭐ LOW
6. User Preferences ⭐ LOW
7. Caregiver Access ⭐⭐ LOW

---

1. Drug Interaction Checker ⚠️ CRITICAL

Overview

Automatically detect drug-to-drug and drug-to-allergy interactions.

Database Schema

drug_interactions: {
  medication_1: String,
  medication_2: String,
  severity: "minor" | "moderate" | "severe",
  interaction_type: "drug-drug" | "drug-allergy" | "drug-condition",
  description: String,
  recommendation: String,
  sources: [String]
}

medication_ingredients: {
  medication_id: String,
  ingredients: [String],
  drug_class: String,
  atc_code: String,
  contraindications: [String],
  known_allergens: [String]
}

user_allergies: {
  user_id: String,
  allergen: String,
  severity: "mild" | "moderate" | "severe",
  reactions: [String]
}

API Endpoints

POST /api/interactions/check
{ "medications": ["Aspirin", "Ibuprofen"] }

Response:
{
  "interactions": [
    {
      "severity": "severe",
      "description": "May increase bleeding risk",
      "recommendation": "Avoid concurrent use"
    }
  ]
}

GET /api/interactions/allergies
POST /api/interactions/allergies
PUT /api/interactions/allergies/:id
DELETE /api/interactions/allergies/:id

🔴 CRITICAL QUESTIONS

1. Drug Database Source

   • Option A: OpenFDA API (FREE, limited data)
   • Option B: DrugBank ($500/month, comprehensive)
   • Which do you prefer?

2. Initial Data Set

   • Do you have a CSV/JSON of drug interactions to seed?
   • Or should we build a scraper for FDA data?

3. Medication Name → Ingredients Mapping

   • How should we map medications to ingredients?
   • Manual entry or automatic lookup?

4. Blocking Behavior

   • Should SEVERE interactions BLOCK medication creation?
   • Or just show warning requiring acknowledgment?

5. Liability Disclaimers

   • What disclaimers to show?
   • Require "consult provider" confirmation for severe?

---

2. Automated Reminder System ⭐ HIGH

Overview

Multi-channel medication reminders with flexible scheduling.

Database Schema

reminders: {
  medication_id: ObjectId,
  user_id: String,
  reminder_type: "push" | "email" | "sms",
  schedule: {
    type: "daily" | "weekly" | "interval",
    time: "HH:MM",
    days_of_week: [0-6],
    interval_hours: Number
  },
  timezone: String,
  active: Boolean,
  next_reminder: DateTime,
  snoozed_until: DateTime
}

reminder_logs: {
  reminder_id: ObjectId,
  sent_at: DateTime,
  status: "sent" | "delivered" | "failed" | "snoozed",
  channel: String,
  error_message: String
}

reminder_preferences: {
  user_id: String,
  default_timezone: String,
  preferred_channels: {
    email: Boolean,
    push: Boolean,
    sms: Boolean
  },
  quiet_hours: {
    enabled: Boolean,
    start: "HH:MM",
    end: "HH:MM"
  },
  snooze_duration_minutes: Number
}

API Endpoints

POST /api/medications/:id/reminders
GET /api/medications/:id/reminders
PUT /api/medications/:id/reminders/:id
DELETE /api/medications/:id/reminders/:id

POST /api/reminders/:id/snooze
POST /api/reminders/:id/dismiss

GET /api/user/preferences
PUT /api/user/preferences

🔴 CRITICAL QUESTIONS

6. Push Notification Provider

   • Option A: Firebase Cloud Messaging (FCM) - all platforms
   • Option B: Apple APNS - iOS only
   • Which provider(s)?

7. Email Service

   • Option A: SendGrid ($10-20/month)
   • Option B: Mailgun ($0.80/1k emails)
   • Option C: Self-hosted (free, maintenance)
   • Which service?

8. SMS Provider

   • Option A: Twilio ($0.0079/SMS)
   • Option B: AWS SNS ($0.00645/SMS)
   • Option C: Skip SMS (too expensive)
   • Support SMS? Which provider?

9. Monthly Budget

   • What's your monthly budget for SMS/email?
   • Expected reminders per day?

🟡 IMPORTANT QUESTIONS

10. Scheduling Precision

    • Is minute-level precision sufficient? (Check every 60s)
    • Or need second-level?

11. Quiet Hours

    • Global per-user or medication-specific?

12. Caregiver Fallback

    • If user doesn't dismiss, notify caregiver?
    • After how long? (30min, 1hr, 2hr?)

13. Timezone Handling

    • Auto-adjust for Daylight Saving Time?
    • Handle traveling users?

---

3. Advanced Health Analytics ⭐⭐ MEDIUM

Overview

AI-powered health insights, trends, anomalies, predictions.

Database Schema

health_analytics_cache: {
  user_id: String,
  stat_type: String,
  period_start: DateTime,
  period_end: DateTime,
  analytics: {
    trend: "increasing" | "decreasing" | "stable",
    slope: Number,
    r_squared: Number,
    average: Number,
    min: Number,
    max: Number,
    std_dev: Number
  },
  predictions: [{
    date: DateTime,
    value: Number,
    confidence: Number,
    lower_bound: Number,
    upper_bound: Number
  }],
  anomalies: [{
    date: DateTime,
    value: Number,
    severity: "low" | "medium" | "high",
    deviation_score: Number
  }],
  insights: [String],
  generated_at: DateTime,
  expires_at: DateTime
}

API Endpoints

GET /api/health-stats/analytics?stat_type=weight&period=30d&include_predictions=true

Response:
{
  "analytics": {
    "trend": "increasing",
    "slope": 0.05,
    "r_squared": 0.87,
    "average": 75.2
  },
  "predictions": [
    {
      "date": "2026-03-14",
      "value": 77.5,
      "confidence": 0.92
    }
  ],
  "anomalies": [...],
  "insights": [
    "Weight has increased 5% over 30 days"
  ]
}

GET /api/health-stats/correlations?medication_id=xxx&stat_type=weight

🟡 IMPORTANT QUESTIONS

14. Prediction Horizon

    • How many days ahead? (Default: 7)
    • Configurable per request?

15. Anomaly Threshold

    • Z-score threshold? (Default: 2.5)
    • Adjustable?

16. Minimum Data Points

    • Minimum for analytics? (Default: 3)
    • Show "insufficient data" below threshold?

17. Cache Duration

    • How long to cache analytics? (Default: 24hr)

18. Prediction Confidence

    • Minimum confidence to show predictions? (Default: r² > 0.7)
    • Hide low-confidence predictions?

---

4. Healthcare Data Export ⭐⭐⭐ MEDIUM

Overview

Generate PDF reports and CSV exports for providers.

API Endpoints

POST /api/export/medications
{
  "format": "pdf" | "csv",
  "date_range": { "start": "2026-01-01", "end": "2026-03-31" },
  "include_adherence": true
}

GET /api/export/:export_id/download

🟡 IMPORTANT QUESTIONS

19. Report Templates

    • Do you have specific template designs?
    • Include charts/graphs or just tables?

20. PDF Generation

    • Server-side (as specified)?
    • Or client-side using browser?

21. Export Limits

    • Max records per export?
    • Rate limiting?

22. Data Retention

    • How long to store export files?
    • Auto-delete after download?

---

5. Medication Refill Tracking ⭐⭐ LOW

Overview

Track medication supply and predict refill needs.

API Endpoints

POST /api/medications/:id/refill
{ "quantity": 30, "days_supply": 30 }

GET /api/medications/refills-needed

Response:
{
  "refills_needed": [
    {
      "medication_name": "Metformin",
      "days_remaining": 5,
      "urgency": "high"
    }
  ]
}

🟢 NICE-TO-HAVE QUESTIONS

23. Pharmacy Integration

    • Integrate with pharmacy APIs?
    • Or just manual tracking?

24. Prescription Upload

    • Allow prescription image uploads?
    • Storage/privacy requirements?

---

6. User Preferences ⭐ LOW

Overview

User customization settings.

API Endpoints

GET /api/user/preferences
PUT /api/user/preferences
{
  "units": "metric" | "imperial",
  "timezone": "America/New_York",
  "notifications": {
    "email": true,
    "push": true,
    "sms": false
  },
  "language": "en"
}

🟢 NICE-TO-HAVE QUESTIONS

25. Unit Systems

    • Support metric/imperial?
    • Per-user or per-stat-type?

26. Language Support

    • Phase 2.8 or later?

---

7. Caregiver Access ⭐⭐ LOW

Overview

Allow caregivers to view/manage health data.

API Endpoints

POST /api/caregivers/invite
{
  "email": "caregiver@example.com",
  "permission_level": "view" | "edit" | "full",
  "access_duration": "30d"
}

GET /api/caregivers
PUT /api/caregivers/:id/revoke
GET /api/caregivers/:id/activity-log

🟢 NICE-TO-HAVE QUESTIONS

27. Permission Levels

    • Which levels? (view, edit, full)
    • Granular per-data-type permissions?

28. Emergency Access

    • Caregiver emergency override?
    • How to activate?

---

📋 Summary: Questions Requiring Your Input

🔴 CRITICAL (Block Implementation)

1. Drug Database: OpenFDA (free) or DrugBank ($500/mo)?
2. Initial Data: Have CSV/JSON of interactions, or build scraper?
3. Ingredient Mapping: Manual or automatic?
4. Severe Interactions: Block creation or just warn?
5. Liability Disclaimers: What wording?
6. Push Provider: Firebase or APNS?
7. Email Service: SendGrid, Mailgun, or self-hosted?
8. SMS Provider: Support? Which one?
9. Monthly Budget: SMS/email budget and expected volume?

🟡 IMPORTANT (Affect Design)

10. Scheduling Precision: Minute-level sufficient?
11. Quiet Hours: Global or medication-specific?
12. Caregiver Fallback: After how long?
13. Timezone Handling: Auto DST adjustment?
14. Prediction Horizon: How many days?
15. Anomaly Threshold: What Z-score?
16. Minimum Data: What threshold?
17. Cache Duration: How long?
18. Prediction Confidence: Minimum r²?
19. Report Templates: Have designs?
20. PDF Generation: Server or client-side?
21. Export Limits: Max records?
22. Data Retention: How long?

🟢 NICE-TO-HAVE

23. Pharmacy Integration: Yes/no?
24. Prescription Upload: Allow uploads?
25. Unit Systems: Which ones?
26. Language Support: Phase 2.8 or later?
27. Permission Levels: Which levels?
28. Emergency Access: How activate?

---

🎯 Recommended Implementation Order

1. Drug Interaction Checker (Safety-critical)
2. Automated Reminder System (High user value)
3. Healthcare Data Export (Provider integration)
4. Advanced Health Analytics (Enhanced insights)
5. Medication Refill Tracking (Convenience)
6. User Preferences (UX)
7. Caregiver Access (Family care)

---

🚀 Next Steps

1. ✅ Review this document
2. 🔴 Answer CRITICAL questions (1-9)
3. 🟡 Review IMPORTANT questions (10-22)
4. 🟢 Consider NICE-TO-HAVE (23-28)
5. ▶️ Begin implementation

---

Version: 1.0 Status: Awaiting User Input Created: 2026-03-07