normogen/docs/implementation/PHASE28_REQUIREMENTS_CONFIRMED.md

# Phase 2.8 - Technical Specifications (Updated with User Decisions)

**Status:** Requirements Confirmed - Ready to Implement  
**Updated:** 2026-03-07  
**Version:** 2.0

---

## ✅ Requirements Confirmed

All **9 critical questions** have been answered. Implementation can proceed.

---

## Confirmed Decisions

### 1. Drug Interaction Checker ⚠️ CRITICAL

#### Requirements
✅ **Database Source**: OpenFDA API (FREE)  
✅ **European Alternative**: Research EMA (European Medicines Agency) API  
✅ **Initial Data**: User will provide CSV/JSON of drug interactions  
✅ **Ingredient Mapping**: Automatic lookup from medication name  
✅ **Blocking Behavior**: WARN ONLY (do not block)  
✅ **Rationale**: "Many cases where reasons are plenty to allow for dangerous interactions"  
✅ **Disclaimer**: "Advisory only, consult with a physician for detailed information"

#### API Integration Points
- OpenFDA Drug Interaction API: https://api.fda.gov/drug/event.json
- EMA API: https://www.ema.europa.eu/en/medicines/human/EPAR (to research)

---

### 2. Automated Reminder System ⭐ HIGH

#### Requirements
✅ **Push Provider**: Firebase Cloud Messaging (FCM)  
✅ **Email Service**: Mailgun  
✅ **Testing**: Easy testing required  
✅ **Privacy**: Proton Mail for confidential emails (future)  
✅ **SMS Provider**: Skip SMS for now (cost concerns)  
✅ **Budget**: Minimal (proof-of-concept)

#### Implementation Notes
- Use Mailgun's free tier (1000 emails/month free)
- Firebase FCM (free tier available)
- No SMS support in Phase 2.8
- Focus on Push + Email notifications only

---

## 📋 Implementation Plan (Updated)

### Week 1: Core Safety Features (5-7 days)

#### Drug Interaction Checker
- [ ] Set up OpenFDA API integration
- [ ] Research EMA API for European drug data
- [ ] Create database schemas (3 collections)
- [ ] Build repository layer (5 methods)
- [ ] Implement API handlers (3 endpoints)
- [ ] Seed database with provided CSV/JSON
- [ ] Build automatic ingredient lookup
- [ ] Add warning system (non-blocking)
- [ ] Include physician consultation disclaimer
- [ ] Write comprehensive tests

**Estimated Duration**: 5-7 days

---

### Week 2-3: Reminder System (4-5 days)

#### Automated Reminders
- [ ] Set up Firebase Cloud Messaging
- [ ] Set up Mailgun email service
- [ ] Create reminder schemas (3 collections)
- [ ] Build reminder repository
- [ ] Implement background scheduler (60s interval)
- [ ] Create notification service (Push + Email)
- [ ] Build API handlers (6 endpoints)
- [ ] Implement snooze/dismiss functionality
- [ ] Add timezone handling
- [ ] Implement quiet hours
- [ ] Write comprehensive tests

**Estimated Duration**: 4-5 days

---

### Week 4: Remaining Features (5-7 days)

#### Advanced Health Analytics (2-3 days)
- Default parameters for:
  - Prediction horizon: 7 days
  - Anomaly threshold: Z-score 2.5
  - Minimum data points: 3
  - Cache duration: 24 hours
  - Prediction confidence: r² > 0.7

#### Healthcare Data Export (2 days)
- Server-side PDF generation
- Simple table-based reports
- CSV export for health stats
- Auto-delete after download

#### User Preferences (1 day)
- Metric/imperial units
- Notification preferences
- Timezone settings

#### Caregiver Access (2 days)
- View/Edit/Full permission levels
- Basic invitation system
- Activity logging

**Estimated Duration**: 5-7 days

---

## 🔧 Technical Stack Updates

### External APIs & Services

#### Drug Interaction Data
```toml
[dependencies]
# FDA API integration
reqwest = { version = "0.11", features = ["json"] }
serde_json = "1.0"

# For EMA (European Medicines Agency)
# Research: https://www.ema.europa.eu/en/medicines/human/EPAR
```

#### Firebase Cloud Messaging
```toml
[dependencies]
fcm = "0.9"
```

Environment variables:
```bash
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_SERVICE_ACCOUNT_KEY=path/to/key.json
```

#### Mailgun
```toml
[dependencies]
lettre = "0.11"  # Email sending
lettre_email = "0.11"
```

Environment variables:
```bash
MAILGUN_API_KEY=your-api-key
MAILGUN_DOMAIN=your-domain.com
MAILGUN_FROM_EMAIL=noreply@normogen.com
```

### No SMS Support
- SMS skipped for Phase 2.8 (cost concerns)
- Can be added later if budget allows

---

## 📊 Updated Database Collections

### Drug Interactions
```javascript
db.drug_interactions        // Drug-drug, drug-allergy interactions
db.medication_ingredients    // Ingredient mapping
db.user_allergies            // User allergy profiles
```

### Reminders
```javascript
db.reminders                 // Reminder schedules
db.reminder_logs            // Delivery logs
db.reminder_preferences     // User settings
```

### Analytics & Export
```javascript
db.health_analytics_cache   // Cached analytics
db.medications.correlations  // Med-health correlations
db.export_jobs              // Export task tracking
```

---

## 🚀 Implementation Order

1. **Drug Interaction Checker** (Week 1)
   - Safety-critical feature
   - Blocking on other features (should check on med creation)
   - OpenFDA + CSV seeding

2. **Automated Reminder System** (Week 2-3)
   - High user value
   - Firebase + Mailgun setup
   - Background scheduler

3. **Advanced Health Analytics** (Week 4)
   - Uses default parameters
   - Builds on existing health stats

4. **Healthcare Data Export** (Week 4)
   - PDF + CSV generation
   - Provider integration

5. **User Preferences** (Week 4)
   - Simple settings management

6. **Caregiver Access** (Week 4)
   - Basic permissions system

---

## 🎯 Success Metrics

### Drug Interaction Checker
- 90%+ coverage of common medications
- <1s response time for interaction checks
- 100% warning rate for severe interactions

### Reminder System
- >95% delivery rate (Push + Email)
- <1min scheduling precision
- 100% quiet hours compliance

### Overall
- 90%+ test coverage
- All features functional
- Production-ready deployment

---

## 📝 Implementation Checklist

### Prerequisites
- [ ] User provides CSV/JSON of drug interactions
- [ ] Set up Firebase project and get service account key
- [ ] Set up Mailgun account and get API key
- [ ] Research EMA API for European drug data

### Phase 2.8.1: Drug Interactions (Week 1)
- [ ] Create `backend/src/models/interactions.rs`
- [ ] Create `backend/src/repositories/interaction_repository.rs`
- [ ] Create `backend/src/handlers/interactions.rs`
- [ ] Implement OpenFDA API client
- [ ] Build automatic ingredient lookup
- [ ] Add routes to main.rs
- [ ] Seed database with provided data
- [ ] Write tests
- [ ] Deploy and test

### Phase 2.8.2: Reminders (Week 2-3)
- [ ] Create `backend/src/models/reminders.rs`
- [ ] Create `backend/src/repositories/reminder_repository.rs`
- [ ] Create `backend/src/services/reminder_scheduler.rs`
- [ ] Create `backend/src/services/notification_service.rs`
- [ ] Create `backend/src/handlers/reminders.rs`
- [ ] Set up Firebase integration
- [ ] Set up Mailgun integration
- [ ] Add background scheduler to main.rs
- [ ] Add routes to main.rs
- [ ] Write tests
- [ ] Deploy and test

### Phase 2.8.3: Analytics & Export (Week 4)
- [ ] Create `backend/src/models/analytics.rs`
- [ ] Create `backend/src/services/analytics_engine.rs`
- [ ] Create `backend/src/handlers/analytics.rs`
- [ ] Create `backend/src/handlers/export.rs`
- [ ] Add routes to main.rs
- [ ] Write tests
- [ ] Deploy and test

### Phase 2.8.4: Final Features (Week 4)
- [ ] Create `backend/src/handlers/preferences.rs`
- [ ] Create `backend/src/handlers/caregivers.rs`
- [ ] Add routes to main.rs
- [ ] Write tests
- [ ] Deploy and test

---

## 📖 Additional Research Needed

### EMA (European Medicines Agency)
- Explore EMA's drug data APIs
- Check for interaction data availability
- Compare with OpenFDA coverage
- Document any limitations

### Privacy-First Email
- Research Proton Mail API availability
- Check integration complexity
- Consider for Phase 2.9 or 3.0

---

## 🎉 Ready to Implement!

All critical requirements confirmed:
- ✅ Drug database source selected (OpenFDA + EMA research)
- ✅ Initial data source confirmed (user-provided CSV/JSON)
- ✅ Ingredient mapping method (automatic)
- ✅ Interaction behavior (warn, don't block)
- ✅ Liability disclaimer wording
- ✅ Push notification provider (Firebase FCM)
- ✅ Email service selected (Mailgun)
- ✅ SMS decision (skip for now)
- ✅ Budget constraints understood (minimal, proof-of-concept)

**Estimated Timeline**: 3 weeks  
**Start Date**: Awaiting user to provide interaction CSV/JSON and Firebase/Mailgun credentials

---

*Version: 2.0*  
*Status: Requirements Confirmed*  
*Updated: 2026-03-07*