# Persona and Family Management - Product Definition

**Document Version**: 1.0  
**Date**: 2026-03-09  
**Status**: Draft - For Refinement  
**Purpose**: Consolidate all current information about persona and family management features for further product refinement

---

## 📋 Table of Contents

1. [Executive Summary](#executive-summary)
2. [User Personas](#user-personas)
3. [Family Management Concept](#family-management-concept)
4. [Current Implementation Status](#current-implementation-status)
5. [Data Models](#data-models)
6. [API Endpoints](#api-endpoints)
7. [User Stories](#user-stories)
8. [Security Considerations](#security-considerations)
9. [MVP Prioritization](#mvp-prioritization)
10. [Open Questions](#open-questions)

---

## Executive Summary

Normogen supports **multi-person health data management** through a persona and family management system. This enables:

- **Primary users** to manage their own health data
- **Family caregivers** to manage health data for dependents (children, elderly parents)
- **Data sharing** between family members and caregivers
- **Privacy control** through granular permissions

**Key Insight**: The persona/family feature is **CRITICAL for MVP** as it enables the core use case of parents tracking medications and health data for their entire family.

---

## User Personas

### Primary: Privacy-Conscious Individual

**Demographics:**
- Age: 25-45
- Tech-savvy
- Concerns about data privacy
- Wants to track personal medications and health stats

**Needs:**
- Secure medication tracking
- Health statistics monitoring
- Data ownership and control
- Privacy from corporations

**Motivations:**
- Values control over personal data
- Distrusts commercial health platforms
- Wants self-hosting option
- Needs comprehensive health tracking

---

### Secondary: Family Caregiver ⭐ MVP CRITICAL

**Demographics:**
- Age: 30-55
- Managing health for dependents (children, elderly parents)
- Often time-constrained
- Needs simple, efficient workflows

**Needs:**
- Multi-person health data management
- Easy data sharing with other caregivers
- Medication reminders for family members
- Family health history tracking
- Caregiver access management

**Motivations:**
- Ensure family medication adherence
- Coordinate care with other family members
- Monitor elderly parents' health remotely
- Track children's health over time

**Pain Points:**
- Juggling multiple medications for different family members
- Forgetting to give medications on time
- Difficulty sharing health info with doctors/caregivers
- Fragmented health records across different systems

**Daily Scenarios:**
1. **Morning Routine**: Check medications due for spouse, child, and self
2. **Doctor Visit**: Export family medication history for pediatrician
3. **Care Coordination**: Share child's health data with grandparent babysitter
4. **Travel**: Ensure medications are tracked while away from home

---

### Tertiary: Health Enthusiast

**Demographics:**
- Age: 20-40
- Tracks fitness, sleep, nutrition
- Uses wearables and sensors
- Data-driven approach to health

**Needs:**
- Integration with wearable devices
- Advanced analytics and trends
- Data visualization
- Export capabilities

**Motivations:**
- Optimize personal health
- Identify patterns in health data
- Quantified self movement
- Biohacking interests

---

## Family Management Concept

### Vision

Normogen enables **family-centered health data management** where one user account can manage health data for multiple people through:

1. **Person Profiles** - Individual health profiles for each family member
2. **Family Groups** - Logical grouping of related individuals
3. **Permission-Based Access** - Granular control over who can view/manage data
4. **Caregiver Roles** - Designated caregivers for dependents

### Core Concepts

#### User Account vs. Profile

**User Account**:
- Represents a login identity (email/password)
- Has authentication credentials
- Owns the data
- Can create multiple profiles

**Profile** (Persona):
- Represents an individual person's health data
- Belongs to a user account
- Can be the account owner (self) or a dependent (child, elderly parent)
- Has its own medications, health stats, lab results

**Example**:
```text
User Account: jane.doe@example.com (Jane)
├── Profile: Jane Doe (self) - age 35
├── Profile: John Doe (spouse) - age 37 - shared with Jane
├── Profile: Emma Doe (daughter) - age 8 - managed by Jane
└── Profile: Robert Smith (father) - age 72 - managed by Jane
```

#### Family Structure

**Family Group**:
- Collection of profiles related by family/caregiver relationship
- Enables sharing and permissions across family members
- One user can be part of multiple families (e.g., nuclear family + aging parents)

**Family Roles**:
- **Owner**: Primary account holder
- **Manager**: Can manage health data for dependents
- **Member**: Can view own data
- **Caregiver**: External person with granted access (e.g., nanny, home health aide)

---

## Current Implementation Status

### ✅ Implemented (Backend)

#### User Model (`backend/src/models/user.rs`)
- User authentication with email/password
- User profile management (username, email)
- Password recovery with recovery phrase
- Account deletion
- Settings management

**User Structure**:
```rust
pub struct User {
    pub id: Option<ObjectId>,
    pub email: String,
    pub username: String,
    pub password_hash: String,
    pub recovery_phrase_hash: Option<String>,
    pub recovery_enabled: bool,
    pub token_version: i32,
    pub created_at: DateTime,
    pub last_active: DateTime,
    pub email_verified: bool,
}
```

#### Profile Model (`backend/src/models/profile.rs`)
- Profile creation and management
- Link to user account
- Link to family group
- Role-based permissions
- Encrypted profile data

**Profile Structure**:
```rust
pub struct Profile {
    pub id: Option<ObjectId>,
    pub profile_id: String,
    pub user_id: String,              // Owner user account
    pub family_id: Option<String>,    // Family group ID
    pub name: String,                 // Encrypted
    pub name_iv: String,              // Encryption IV
    pub name_auth_tag: String,        // Encryption auth tag
    pub role: String,                 // Role in family
    pub permissions: Vec<String>,     // Permissions list
    pub created_at: DateTime,
    pub updated_at: DateTime,
}
```

#### Family Model (`backend/src/models/family.rs`)
- Family group creation
- Member management
- Encrypted family data

**Family Structure**:
```rust
pub struct Family {
    pub id: Option<ObjectId>,
    pub family_id: String,
    pub name: String,                 // Encrypted
    pub name_iv: String,
    pub name_auth_tag: String,
    pub member_ids: Vec<String>,      // Profile IDs
    pub created_at: DateTime,
    pub updated_at: DateTime,
}
```

#### Share/Permission System
- Create shares for health data
- Grant read/write/admin permissions
- Expiring access links
- Resource-level permissions

**Share Model** (`backend/src/models/share.rs`):
```rust
pub struct Share {
    pub id: Option<ObjectId>,
    pub share_id: String,
    pub resource_type: String,        // "medication", "health_stat", etc.
    pub resource_id: String,
    pub target_user_id: String,       // Who receives access
    pub permissions: Vec<String>,     // ["read", "write", "delete", "share", "admin"]
    pub expires_at: Option<DateTime>,
    pub active: bool,
}
```

### 🚧 Partially Implemented

#### Medication Management
- ✅ Create/list/update/delete medications
- ✅ Profile-based filtering (`profile_id` parameter)
- ✅ Log doses for specific profiles
- ✅ Calculate adherence by profile
- ✅ OpenFDA integration for drug data

**Medication Structure**:
```rust
pub struct Medication {
    pub id: Option<ObjectId>,
    pub user_id: String,
    pub profile_id: Option<String>,   // ✅ Multi-person support
    pub name: String,
    pub dosage: String,
    pub frequency: String,
    // ... other fields
}
```

**Example: Parent managing child's medication**:
```bash
# Create medication for child's profile
curl -X POST http://localhost:8000/api/medications \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "Amoxicillin",
    "dosage": "250mg",
    "frequency": "Twice daily",
    "profile_id": "child_profile_123"
  }'

# Log dose for child
curl -X POST http://localhost:8000/api/medications/{id}/log \
  -H "Authorization: Bearer <token>" \
  -d '{"profile_id": "child_profile_123"}'

# View child's adherence
curl http://localhost:8000/api/medications/{id}/adherence?profile_id=child_profile_123 \
  -H "Authorization: Bearer <token>"
```

### ❌ Not Implemented

#### Profile Management Endpoints
- No dedicated API for profile CRUD operations
- No UI for creating/managing family profiles
- No profile switching interface
- No family group management UI

#### Frontend Support
- Basic React app structure exists (~10% complete)
- No profile management UI
- No family management UI
- No profile switching functionality

---

## Data Models

### User Account

```typescript
interface User {
  id: string;
  email: string;
  username: string;
  passwordHash: string;
  recoveryPhraseHash?: string;
  recoveryEnabled: boolean;
  tokenVersion: number;
  createdAt: Date;
  lastActive: Date;
  emailVerified: boolean;
}
```

### Profile (Persona)

```typescript
interface Profile {
  id: string;
  profileId: string;
  userId: string;              // Owner user account
  familyId?: string;           // Optional family group
  name: string;                // Encrypted
  role: string;                // "self", "child", "dependent", "spouse"
  permissions: string[];       // ["read", "write", "delete", "share", "admin"]
  dateOfBirth?: Date;          // For age calculations
  relationship?: string;       // "daughter", "son", "father", "mother", etc.
  avatar?: string;             // Profile picture URL
  createdAt: Date;
  updatedAt: Date;
}
```

### Family Group

```typescript
interface Family {
  id: string;
  familyId: string;
  name: string;                // Encrypted (e.g., "Smith Family")
  memberIds: string[];         // Array of profile IDs
  createdAt: Date;
  updatedAt: Date;
}
```

### Share/Permission

```typescript
interface Share {
  id: string;
  shareId: string;
  resourceType: string;        // "medication", "health_stat", "lab_result"
  resourceId: string;
  targetUserId: string;        // User receiving access
  permissions: Permission[];   // ["read", "write", "delete", "share", "admin"]
  expiresAt?: Date;
  active: boolean;
  createdAt: Date;
}

type Permission = "read" | "write" | "delete" | "share" | "admin";
```

---

## API Endpoints

### Currently Implemented

#### User Profile Management
```typescript
GET    /api/users/me                    // Get current user profile
PUT    /api/users/me                    // Update user profile
DELETE /api/users/me                    // Delete account
POST   /api/users/me/change-password    // Change password
GET    /api/users/me/settings           // Get user settings
PUT    /api/users/me/settings           // Update user settings
```

#### Medication Management (with profile support)
```typescript
POST   /api/medications                 // Create medication (with profile_id)
GET    /api/medications                 // List medications (filter by profile_id)
GET    /api/medications/:id             // Get specific medication
PUT    /api/medications/:id             // Update medication
POST   /api/medications/:id/delete      // Delete medication
POST   /api/medications/:id/log         // Log dose (with profile_id)
GET    /api/medications/:id/adherence   // Get adherence (filter by profile_id)
```

#### Health Statistics (with profile support)
```typescript
POST   /api/health-stats                // Create health stat (with profile_id)
GET    /api/health-stats                // List health stats (filter by profile_id)
GET    /api/health-stats/:id            // Get specific health stat
PUT    /api/health-stats/:id            // Update health stat
DELETE /api/health-stats/:id           // Delete health stat
GET    /api/health-stats/trends         // Get trends (filter by profile_id)
```

#### Share/Permission Management
```typescript
POST   /api/shares                      // Create share
GET    /api/shares                      // List shares
PUT    /api/shares/:id                  // Update share
DELETE /api/shares/:id                  // Delete share
POST   /api/permissions/check           // Check permissions
```

### Needed for Complete Family Management

#### Profile CRUD
```typescript
GET    /api/profiles                    // List all profiles for current user
POST   /api/profiles                    // Create new profile (family member)
GET    /api/profiles/:id                // Get specific profile
PUT    /api/profiles/:id                // Update profile
DELETE /api/profiles/:id                // Delete profile
GET    /api/profiles/:id/medications    // Get medications for profile
GET    /api/profiles/:id/health-stats   // Get health stats for profile
```

#### Family Group Management
```typescript
GET    /api/families                    // List families
POST   /api/families                    // Create family
GET    /api/families/:id                // Get family details
PUT    /api/families/:id                // Update family
DELETE /api/families/:id                // Delete family
POST   /api/families/:id/members        // Add member to family
DELETE /api/families/:id/members/:id    // Remove member from family
```

#### Caregiver Access
```typescript
POST   /api/profiles/:id/caregivers     // Add caregiver to profile
DELETE /api/profiles/:id/caregivers/:id // Remove caregiver
GET    /api/profiles/:id/caregivers     // List caregivers
PUT   /api/profiles/:id/caregivers/:id  // Update caregiver permissions
```

---

## User Stories

### Story 1: Parent Managing Child's Medications

**As a parent**, I want to manage my child's medications so that I can ensure they take their medication correctly.

**Acceptance Criteria**:
- [ ] Create a profile for my child (name, DOB, relationship)
- [ ] Add medications to my child's profile
- [ ] Log doses for my child
- [ ] View my child's medication adherence
- [ ] Set up reminders for my child's medications
- [ ] Share my child's medication list with spouse

**Happy Path**:
1. Parent logs into Normogen
2. Creates profile for daughter "Emma" (DOB: 2016-05-15, relationship: "daughter")
3. Adds medication "Amoxicillin 250mg" to Emma's profile
4. Sets reminder for 8am and 8pm daily
5. Logs morning dose at 8:05am
6. Views Emma's medication adherence (95% this month)
7. Shares Emma's medications with spouse (read access)

---

### Story 2: Caring for Elderly Parent

**As an adult child**, I want to manage my elderly father's health data so that I can ensure he's taking his medications and monitor his health.

**Acceptance Criteria**:
- [ ] Create profile for elderly parent
- [ ] Add multiple medications with complex schedules
- [ ] Track blood pressure readings
- [ ] View medication adherence
- [ ] Receive alerts for missed doses
- [ ] Share health data with home health aide

**Happy Path**:
1. User creates profile for father "Robert" (age 72, relationship: "father")
2. Adds 5 medications with different schedules
3. Records BP readings twice daily
4. Gets notification: "Robert missed 6pm Lisinopril dose"
5. Views trends: BP average 135/85 this week
6. Grants read access to home health aide for 30 days

---

### Story 3: Family Sharing Health Data

**As a parent**, I want to share my child's health data with grandparents so that they can provide care when babysitting.

**Acceptance Criteria**:
- [ ] Create share for child's medications
- [ ] Set expiration on share (1 day, 7 days, 30 days)
- [ ] Grant read-only access
- [ ] Revoke access when needed
- [ ] Share multiple resources at once

**Happy Path**:
1. Parent creates share for daughter Emma's medications
2. Selects "Grandma" as target user
3. Grants "read" permission
4. Sets expiration to "1 day" (for sleepover)
5. Grandma receives link, views Emma's medication schedule
6. Next day, share expires automatically

---

### Story 4: Switching Between Family Profiles

**As a parent**, I want to easily switch between family members' profiles so that I can manage health data for each person.

**Acceptance Criteria**:
- [ ] View all profiles I have access to
- [ ] Switch active profile with one click
- [ ] See filtered data for selected profile
- [ ] Quick-switch from medication list
- [ ] Mobile-friendly profile switching

**Happy Path**:
1. Parent opens Normogen app
2. Sees profile switcher: "Jane ▼" in header
3. Clicks dropdown, sees: [Jane] [John] [Emma] [Robert]
4. Selects "Emma"
5. App filters to show only Emma's medications and health stats
6. Logs dose for Emma's medication
7. Switches back to "Jane" to view own data

---

## Security Considerations

### Data Ownership & Access Control

**Core Principle**: Users can only access profiles they own or have been granted access to.

**Implementation**:
1. **User Ownership Verification**: Every request verifies `user_id` matches JWT token
2. **Profile Ownership Verification**: Profile access checks if user owns the profile
3. **Permission Checking**: Share system enforces granted permissions
4. **Audit Logging**: All profile/medication access is logged

**Security Rules**:
- ✅ Users can only create profiles for their own account
- ✅ Users can only access medications they own or have been shared
- ✅ Profile data is encrypted at rest (AES-256-GCM)
- ✅ Share access expires automatically
- ✅ All access is logged for audit purposes

### Children's Data Protection

**Additional Protections for Dependent Profiles**:
- No public sharing of children's data
- Limited caregiver access (read-only by default)
- Explicit consent required for any sharing
- Audit logging for all children's data access
- Parent can revoke any caregiver access immediately

**Implementation**:
```rust
if profile.role == "child" || profile.age < 18 {
    // Enforce stricter sharing rules
    require_explicit_parent_consent(share)?;
    limit_to_read_only(share)?;
}
```

### Encryption

**Zero-Knowledge Encryption**:
- Profile names are encrypted (AES-256-GCM)
- Family names are encrypted
- Only users with correct password can decrypt
- Server cannot see profile names

**Encrypted Fields**:
- `profile.name` - Person's name
- `family.name` - Family group name
- Medication data (when implemented)

---

## MVP Prioritization

### Priority: 🔴 CRITICAL for MVP

**Profile Management** is marked as CRITICAL in Phase 2.7 MVP prioritization:

| Feature | Priority | MVP Value | Effort | Status |
|---------|----------|-----------|--------|--------|
| **Profile Management** | 🔴 CRITICAL | 🔥🔥🔥🔥 | Low | 🚧 Partial (model exists, no API) |
| **Multi-Person Medications** | 🔴 CRITICAL | 🔥🔥🔥🔥🔥 | Medium | ✅ Implemented |
| **Profile-Based Filtering** | 🔴 CRITICAL | 🔥🔥🔥🔥 | Low | ✅ Implemented |
| **Basic Sharing** | 🔴 IMPORTANT | 🔥🔥🔥🔥 | Medium | ✅ Implemented |

**Why Critical?**
- Enables the core use case: parents tracking family health
- Differentiates from competitors (single-person apps)
- Essential for family caregiver persona
- Low implementation effort (models exist, just need API endpoints)

---

## Open Questions

### Product Definition

1. **Profile Types**: Should we have explicit profile types (child, adult, elderly) or just roles?
   - Option A: Explicit types with validation rules
   - Option B: Flexible roles defined by user
   - **Recommendation**: Start with flexible roles, add types later

2. **Family Membership**: Can a profile belong to multiple families?
   - Example: Spouse in nuclear family + member of extended family
   - **Recommendation**: Yes, support multiple families

3. **Caregiver Access**: How do external caregivers access shared data?
   - Option A: Must have Normogen account
   - Option B: Email-based magic link (no account required)
   - **Recommendation**: Start with Normogen account, add magic links later

4. **Profile Deletion**: What happens when deleting a profile?
   - Soft delete (mark as deleted)?
   - Hard delete (remove all data)?
   - Export option before deletion?
   - **Recommendation**: Soft delete + export option

### Technical Implementation

1. **Profile Limit**: How many profiles per user account?
   - Suggested: 10 profiles (reasonable for most families)

2. **Family Size Limit**: How many members per family?
   - Suggested: 20 members (extended family)

3. **Share Limit**: How many active shares per resource?
   - Suggested: No limit (but audit heavily)

4. **Data Retention**: How long to keep deleted profile data?
   - Suggested: 30 days (soft delete period)

### UI/UX

1. **Profile Switching**: Where should profile switcher be located?
   - Header dropdown? Sidebar? Separate page?
   - **Recommendation**: Header dropdown for quick access

2. **Profile Creation**: What information is required?
   - Minimum: Name + Relationship
   - Optional: DOB, avatar, medical info
   - **Recommendation**: Start with name + relationship, add fields later

3. **Family View**: Should we have a "family dashboard"?
   - Show all family members at once
   - Medications due today for all profiles
   - **Recommendation**: Phase 3 feature (not MVP)

---

## Next Steps for Refinement

### 1. Clarify Product Requirements

- [ ] Define exact profile types/roles needed
- [ ] Specify required vs optional profile fields
- [ ] Define caregiver access model (account vs magic link)
- [ ] Specify profile deletion behavior

### 2. Prioritize API Endpoints

- [ ] Profile CRUD (create, read, update, delete)
- [ ] Family group management
- [ ] Caregiver management
- [ ] Profile switching in UI

### 3. Security Review

- [ ] Finalize children's data protection rules
- [ ] Define audit logging requirements
- [ ] Specify encryption scope
- [ ] Define share expiration policies

### 4. UI/UX Design

- [ ] Design profile creation flow
- [ ] Design profile switching interface
- [ ] Design family management dashboard
- [ ] Design caregiver invitation flow

---

## Appendix: Related Documentation

### Product Documents
- `docs/product/introduction.md` - User personas and target audience
- `docs/product/ROADMAP.md` - Development phases and timeline
- `docs/product/STATUS.md` - Current implementation status

### Implementation Documents
- `docs/implementation/MVP_PHASE_2.7_SUMMARY.md` - MVP prioritization (profiles as critical)
- `docs/implementation/PHASE_2.7_MVP_PRIORITIZED_PLAN.md` - Detailed sprint plan

### Code
- `backend/src/models/profile.rs` - Profile data model
- `backend/src/models/family.rs` - Family data model
- `backend/src/models/user.rs` - User data model
- `backend/src/models/medication.rs` - Medication model with profile_id support

---

**Document Status**: Ready for refinement and feedback  
**Next Review**: After product team discussion  
**Owner**: Product Team  
**Contributors**: Development Team, UX Team