alvaro/normogen
1
0
Fork 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions

docs: reconcile documentation with reality (P3)

Browse source 
Make the project's documentation match the code and remove the sprawl. The docs
claimed Phase 2.8 (drug interactions) was 'planning/0%' and the backend '~91%
complete' — both wrong: 2.8 is implemented and live, plus the P0/P1 security
and test work is done. Five root CI/CD docs described a 'docker-build' CI job
that was removed; ~18 backend/ status snapshots and ~24 docs/implementation
duplicates cluttered the tree.

Deletions (85 files):
- Root: 4 stale CI/CD reports (CI-CD-{COMPLETION-REPORT,IMPLEMENTATION-SUMMARY,
  STATUS-REPORT,FINAL-STATUS}.md) — all describe the removed docker-build job.
- backend/: 18 phase/build/fix snapshots and code-dump .txt files.
- docs/: the 3 one-time reorg reports; ~17 docs/implementation duplicates and
  process artifacts; 4 stale docs/development CI docs + git snapshots;
  redundant deployment/testing files.
- thoughts/: STATUS.md (said Phase 2.4 in-progress), superseded phase notes and
  duplicative research inputs. tmp/ (928KB of CI debug logs, gitignored).

Moves (18 files):
- 9 genuine decision records -> docs/adr/ (Architecture Decision Records),
  date-prefixes stripped, with an index README.
- 8 historical-but-valuable phase plans/specs + the old CI-CD-FINAL-SOLUTION ->
  docs/archive/ (now-populated, with a README explaining it's superseded
  material). thoughts/ tree removed.

Rewrites (13 files) to match reality:
- Drop the fake '% complete' figures everywhere in favor of Implemented /
  In-Progress / Planned with concrete endpoint/feature lists.
- Phase 2.8 -> Implemented; add /api/interactions/* and /api/auth/{refresh,
  logout} to the endpoint lists; fix 'Rust 1.93' -> edition 2021.
- Add a Security section (token_version validation, hashed refresh-token
  persistence, fail-fast config, real-IP audit) and correct the test-coverage
  and deployment claims to reality.
- New canonical docs/development/CI-CD.md (4 jobs: format/clippy/build/test,
  mongo service, no docker-build + why).
- README, docs/README, product/{STATUS,ROADMAP,PROGRESS,README,introduction},
  implementation/README, development/README, testing/README, AI_AGENT_GUIDE,
  .cursorrules, .gooserules all updated.

Verified: greps for 'Phase 2.8 (Planning)', 'PLANNING (0%)', 'Rust 1.93',
'91%/10%/85% complete', and 'docker-build' return nothing outside docs/archive;
all internal doc links resolve; backend/src untouched (cargo build clean).
This commit is contained in:
goose 2026-06-27 16:02:16 -03:00
parent bd1b7c2925
commit 17efc4f656
119 changed files with 469 additions and 17801 deletions
Download patch file Download diff file Expand all files Collapse all files

504
docs/archive/PHASE28_COMPLETE_SPECS.md Normal file
View file

@ -0,0 +1,504 @@
# 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*