normogen/thoughts/research/2026-02-14-tech-stack-decision.md

Technology Stack Decisions

Last Updated: 2026-02-14

---

Decisions Made

1. Rust Web Framework: Axum

Decision: Axum 0.7.x

Rationale:

• Superior I/O performance for encrypted data transfer
• Better streaming support for large encrypted responses
• Lower memory usage for concurrent connections
• Tower middleware ecosystem
• Excellent async patterns for lazy loading

Reference: 2026-02-14-performance-findings.md

---

2. Mobile Framework: React Native

Decision: React Native 0.73+ for iOS + Android

Platform Strategy:

• Primary: Mobile apps (iOS + Android) - Daily health tracking, sensor integration
• Secondary: Web browser - Extensive reporting, visualization, profile management

Rationale:

• 70-80% code sharing between mobile and web (single language: TypeScript)
• Health sensor integration: react-native-health (HealthKit), react-native-google-fit (Health Connect)
• QR code scanning: react-native-camera
• Encryption: react-native-quick-crypto (AES-256-GCM, PBKDF2)
• Web charts: Recharts for React (beautiful visualizations)
• Team skills: Single language (JavaScript/TypeScript) reduces development cost
• Time to market: Faster than native or Flutter

Reference: 2026-02-14-frontend-mobile-research.md

---

3. Web Framework: React

Decision: React 18+ for web companion app

Rationale:

• 70-80% code sharing with React Native (business logic, state, API, encryption)
• Charts: Recharts for beautiful health data visualizations
• Ecosystem: Largest npm ecosystem
• Team skills: Single language (TypeScript)

---

4. State Management: Redux Toolkit

Decision: Redux Toolkit 2.x for React Native + React

Score: 9.2/10

Rationale:

• Best for complex state: Family structure, multi-person profiles, permissions
• Built-in normalization: createEntityAdapter for efficient data management
• Best for offline sync: RTK Query for server state, optimistic updates, background sync
• Largest ecosystem: Most resources, tutorials, examples, production deployments
• Best developer experience: Time-travel debugging, predictable state updates
• TypeScript: Excellent support, full type safety
• Code sharing: 100% between React Native and React

Trade-offs:

• More boilerplate: More code, but clearer structure
• Steeper learning curve: More concepts, but better patterns
• Larger bundle: 60KB vs 3KB (negligible impact on 50-100MB app)

Reference: 2026-02-14-state-management-research.md

---

5. Authentication: JWT with Refresh Tokens

Decision: JWT (JSON Web Tokens) with Refresh Tokens + Recovery Phrases

Score: 9.5/10

Rationale:

• Stateless design: Scales to 1000+ concurrent connections (no session storage)
• Mobile-friendly: Works perfectly with React Native (AsyncStorage)
• Zero-knowledge compatible: Integrates with recovery phrases from encryption.md
• Token revocation: Refresh token blacklist (MongoDB) + token versioning
• Token rotation: Prevents reuse of stolen refresh tokens
• Family access control: Permissions in JWT claims (parent, child, elderly)
• Security best practices: Short-lived access tokens (15 min), long-lived refresh tokens (30 days)

Trade-offs:

• Revocation requires storage (MongoDB for refresh tokens, optional Redis for access tokens)
• More complex than sessions (but better for scaling)

Reference: 2026-02-14-jwt-authentication-research.md

---

6. Database: MongoDB with Zero-Knowledge Encryption

Decision: MongoDB 6.0+ with client-side encryption (ALL sensitive data + metadata)

Score: 9.8/10

Core Principle: ALL sensitive data AND metadata must be encrypted client-side before reaching MongoDB

Example: Blood Pressure Reading:

// Before encryption (client-side)
{
  value: "120/80",
  type: "blood_pressure",
  unit: "mmHg",
  date: "2026-02-14T10:30:00Z"
}

// After encryption (stored in MongoDB)
{
  healthDataId: "health-123",
  userId: "user-456",
  profileId: "profile-789",
  
  // Encrypted (value + metadata)
  healthData: [
    {
      encrypted: true,
      data: "a1b2c3d4...",
      iv: "e5f6g7h8...",
      authTag: "i9j0k1l2..."
    }
  ]
}

Rationale:

• Zero-knowledge: Server NEVER decrypts data
• Metadata encryption: Health data type, unit, doctor, lab ALL encrypted
• Privacy-preserving: No plaintext metadata leaks
• Client-side encryption: AES-256-GCM, PBKDF2 key derivation
• Plaintext queries: Query by userId, profileId, familyId, date, tags
• Tagging system: Client adds searchable tags for encrypted data
• Flexible schema: MongoDB document structure fits health data
• Scalable: Horizontal scaling with sharding

Collections:

• users: Authentication, profiles, family relationships
• families: Family structure, encrypted family name/metadata
• profiles: Person profiles, encrypted profile name/metadata
• health_data: Encrypted health records (value + metadata)
• lab_results: Encrypted lab data (value + metadata)
• medications: Encrypted medication data + reminders
• appointments: Encrypted appointment data + reminders
• shares: Time-limited access to shared data
• refresh_tokens: JWT refresh token storage

What Must Be Encrypted:

• ✅ Health data values (e.g., "120/80")
• ✅ Health data metadata (e.g., "blood_pressure", "mmHg")
• ✅ Lab test results (e.g., "cholesterol", "200", "LabCorp")
• ✅ Medication data (e.g., "Aspirin", "100mg", "daily")
• ✅ Appointment data (e.g., "checkup", "Dr. Smith")
• ✅ Profile data (e.g., "John Doe", "1990-01-01")
• ✅ Family data (e.g., "Smith Family", "123 Main St")

What Can Be Plaintext:

• ✅ User IDs (userId, profileId, familyId) - for queries
• ✅ Email addresses - for authentication
• ✅ Dates (createdAt, updatedAt) - for sorting
• ✅ Data sources (healthKit, googleFit) - for analytics
• ✅ Tags (cardio, daily) - for client-side search

Reference: 2026-02-14-mongodb-schema-design-research.md

---

Technology Stack Summary

Backend

• Framework: Axum 0.7.x
• Runtime: Tokio 1.x
• Middleware: Tower, Tower-HTTP
• Authentication: JWT with refresh tokens
• Database: MongoDB 6.0+ (with zero-knowledge encryption)
• Language: Rust

Mobile (iOS + Android)

• Framework: React Native 0.73+
• Language: TypeScript
• State Management: Redux Toolkit 2.x
• Data Fetching: RTK Query 2.x
• Authentication: JWT with AsyncStorage
• Navigation: React Navigation
• Health Sensors:
  • react-native-health (iOS HealthKit)
  • react-native-google-fit (Android Health Connect)
• QR Scanning: react-native-camera
• Encryption: react-native-quick-crypto
• Persistence: Redux Persist 6.x (AsyncStorage)
• HTTP: Axios

Web

• Framework: React 18+
• Language: TypeScript
• State Management: Redux Toolkit 2.x
• Data Fetching: RTK Query 2.x
• Authentication: JWT with localStorage (or httpOnly cookies)
• Routing: React Router
• Charts: Recharts
• Persistence: Redux Persist 6.x (localStorage)
• HTTP: Axios

Shared (Monorepo)

• Language: TypeScript
• State Management: Redux Toolkit 2.x
• Reducers: Shared reducers (user, family, encryption)
• Selectors: Shared selectors (Reselect 5.x)
• API: Axios
• Encryption: AES-256-GCM, PBKDF2
• Validation: Zod
• Date: date-fns
• Utilities: Shared package

---

All Major Decisions Complete ✅

1. ✅ Rust Framework: Axum 0.7.x
2. ✅ Mobile Framework: React Native 0.73+
3. ✅ Web Framework: React 18+
4. ✅ State Management: Redux Toolkit 2.x
5. ✅ Authentication: JWT with refresh tokens
6. ✅ Database: MongoDB 6.0+ with zero-knowledge encryption

---

Implementation Phases

• Phase 1: Research (COMPLETE)

  • Rust framework selection
  • Mobile/web framework selection
  • State management selection
  • Authentication design
  • Database schema design

• Phase 2: Backend Development (NEXT)

  • Axum server setup
  • MongoDB connection
  • JWT authentication
  • CRUD API endpoints
  • Zero-knowledge encryption (client-side)

• Phase 3: Mobile Development (AFTER BACKEND)

  • React Native app setup
  • Redux Toolkit setup
  • JWT authentication
  • Health sensor integration
  • QR code scanning
  • Encryption implementation

• Phase 4: Web Development (PARALLEL WITH MOBILE)

  • React app setup
  • Redux Toolkit setup
  • JWT authentication
  • Charts and visualizations
  • Profile management
  • Encryption implementation

---

Next Steps

1. Backend Development (Axum + MongoDB)

   • Create Axum server
   • Setup MongoDB connection
   • Implement JWT authentication
   • Create MongoDB indexes
   • Implement CRUD endpoints

2. Client-Side Encryption (React Native + React)

   • Implement AES-256-GCM encryption
   • Implement PBKDF2 key derivation
   • Create encryption utilities
   • Test encryption flow

3. API Development (Axum)

   • Users API (register, login, logout)
   • Families API (create, update, delete)
   • Profiles API (CRUD)
   • Health Data API (CRUD)
   • Lab Results API (import via QR)
   • Medications API (reminders)
   • Appointments API (reminders)
   • Shares API (time-limited access)

---

Timeline Estimate

• Phase 1: Research (COMPLETE)
• Phase 2: Backend Development (8-10 weeks)
• Phase 3: Mobile Development (8-12 weeks)
• Phase 4: Web Development (4-6 weeks)
• Phase 5: Testing & Polish (4-6 weeks)

Total: 24-34 weeks (6-8.5 months)

---

References

• Axum Performance Research
• Frontend Mobile Research
• State Management Research
• JWT Authentication Research
• MongoDB Schema Design
• Normogen Encryption Guide
• Project Introduction