normogen/docs/implementation/PHASE28_COMPLETE_SPECS.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](#1-drug-interaction-checker) ⚠️ CRITICAL
2. [Automated Reminder System](#2-automated-reminder-system) ⭐ HIGH
3. [Advanced Health Analytics](#3-advanced-health-analytics) ⭐⭐ MEDIUM
4. [Healthcare Data Export](#4-healthcare-data-export) ⭐⭐⭐ MEDIUM
5. [Medication Refill Tracking](#5-medication-refill-tracking) ⭐⭐ LOW
6. [User Preferences](#6-user-preferences) ⭐ LOW
7. [Caregiver Access](#7-caregiver-access) ⭐⭐ LOW

---

## 1. Drug Interaction Checker ⚠️ CRITICAL

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

### Database Schema
```javascript
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
```javascript
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
```javascript
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*