# Normogen Research Phase 1 Complete - Technology Stack Decisions

**Date**: 2026-02-14
**Status**: Research Phase 1 Complete

---

## Executive Summary

Normogen's technology stack has been defined through comprehensive research focused on the project's unique requirements:

- **Zero-knowledge encryption** requiring high-throughput data transfer
- **Mobile-first platform** with health sensor integration
- **Web companion** for complex visualizations
- **1000+ concurrent connections** in mid-term
- **70-80% code sharing** between mobile and web

### Technology Stack Decisions

| Layer | Technology | Rationale |
|-------|-----------|-----------|
| **Backend Framework** | Axum 0.7.x | 18% faster for large encrypted data, 25% less memory for concurrent connections |
| **Mobile Framework** | React Native 0.73+ | 70-80% code sharing, excellent health sensor integration |
| **Web Framework** | React 18+ | Code sharing with mobile, best chart ecosystem |
| **Database** | MongoDB | Encryption-compatible, flexible schema for health data |
| **Language** | Rust + TypeScript | Performance + code sharing |

---

## Research Completed

### 1. Backend Framework Research: Axum vs Actix

**Research Question**: Which Rust web framework is best for Normogen's encrypted health data platform?

**Key Findings**:

| Metric | Actix Web | Axum | Winner |
|--------|-----------|------|--------|
| I/O Performance (10MB response) | 8,000 RPS | 9,500 RPS | Axum (+18%) |
| Memory per Connection | 2KB | 1.5KB | Axum (-25%) |
| 1000 Connection Memory | ~2GB | ~1.5GB | Axum (-25%) |
| P95 Latency (Large) | 125ms | 110ms | Axum (-12%) |
| Streaming Support | Manual | Built-in | Axum |
| Middleware Ecosystem | Custom | Tower | Axum |

**Decision**: **Axum 0.7.x**

**Critical Advantages**:
- **I/O-bound workload**: Normogen transfers large encrypted data blobs to clients for decryption
- **Streaming responses**: Axum's streaming support is critical for 10MB+ encrypted health data
- **Memory efficiency**: 25% less memory enables scaling to 10K+ concurrent connections
- **Tower ecosystem**: Ideal for encryption middleware (compression, tracing, CORS)
- **MongoDB integration**: Excellent async driver support

**Risk Mitigation**:
- Pre-1.0 API is stable with strong backward compatibility
- Many production deployments exist
- Tower ecosystem compensates for smaller crate ecosystem

**Reference**: [2026-02-14-performance-findings.md](./2026-02-14-performance-findings.md)

---

### 2. Frontend Framework Research: Mobile-First Platform

**Research Question**: Which mobile and web frameworks best support Normogen's health sensor integration and zero-knowledge encryption?

**Platform Strategy Clarification**:

- **Primary Platform (Mobile)**: iOS + Android apps for daily health tracking, sensor integration, QR scanning, push notifications
- **Secondary Platform (Web)**: Browser-based companion for extensive reporting, visualization, and profile management

**Options Evaluated**:

| Criteria | React Native + React | Flutter + React/Svelte | Native + React |
|----------|---------------------|------------------------|----------------|
| Code Sharing | 70-80% | 0% | 0% |
| Development Cost | Low | Medium | High (2x platforms) |
| Time to Market | Fast | Medium | Slow |
| Health Sensors | Excellent | Excellent | Excellent |
| QR Scanning | Excellent | Excellent | Excellent |
| Performance | Good | Excellent | Excellent |
| Team Skills | JS/TS only | Dart + JS | Swift + Kotlin + JS |
| Ecosystem | Largest | Large | Native |

**Decision**: **React Native + React**

**Critical Advantages**:

1. **Code Sharing (70-80%)**
   - Business logic: State management, API client, encryption utilities
   - Data validation: Zod schemas
   - Date handling: date-fns
   - Monorepo shared package

2. **Health Sensor Integration**
   - iOS: react-native-health (Apple HealthKit)
   - Android: react-native-google-fit (Google Health Connect)
   - Background sensor data collection
   - Steps, heart rate, sleep, weight, blood pressure, temperature

3. **Encryption**
   - react-native-quick-crypto
   - AES-256-GCM encryption
   - PBKDF2 key derivation
   - Secure key storage (Keychain/Keystore)
   - Web Crypto API compatible for code sharing

4. **QR Code Scanning**
   - react-native-camera
   - Fast, accurate scanning for lab results

5. **Web Charts**
   - Recharts (React) for beautiful visualizations
   - Perfect for health data trends

6. **Team & Cost**
   - Single language: JavaScript/TypeScript
   - Single ecosystem: npm
   - Lower development cost
   - Faster time to market

**Why Flutter Was Not Chosen**:
- **No code sharing** between mobile and web (0% vs 70-80%)
- Team would need to learn Dart + JavaScript
- Double development cost for business logic
- Slower time to market

**Reference**: [2026-02-14-frontend-mobile-research.md](./2026-02-14-frontend-mobile-research.md)

---

## Technology Stack Summary

### Backend
- **Framework**: Axum 0.7.x
- **Runtime**: Tokio 1.x
- **Middleware**: Tower, Tower-HTTP
- **Database**: MongoDB (with zero-knowledge encryption)
- **Language**: Rust

### Mobile (iOS + Android)
- **Framework**: React Native 0.73+
- **Language**: TypeScript
- **State Management**: TBD (Redux/Zustand)
- **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
- **HTTP**: Axios
- **Date**: date-fns

### Web
- **Framework**: React 18+
- **Language**: TypeScript
- **State Management**: TBD (Redux/Zustand)
- **Routing**: React Router
- **Charts**: Recharts
- **HTTP**: Axios
- **Date**: date-fns
- **UI**: Tailwind CSS / Chakra UI

### Shared (Monorepo)
- **Language**: TypeScript
- **State Management**: Redux/Zustand (TBD)
- **API Client**: Axios
- **Encryption**: AES-256-GCM, PBKDF2
- **Validation**: Zod
- **Date**: date-fns
- **Utilities**: Shared package

---

## Architecture Overview

```
┌─────────────────────────────────────────────────────┐
│                   Shared Layer                       │
│  (Business Logic, State, API, Encryption)           │
│                                                     │
│  - Redux/Zustand Store                              │
│  - API Client (Axios)                               │
│  - Encryption Utilities (AES-GCM, PBKDF2)            │
│  - Data Validation (Zod)                            │
│  - Date Handling (date-fns)                          │
└─────────────────────────────────────────────────────┘
                        │
        ┌───────────────┴───────────────┐
        │                               │
        ▼                               ▼
┌──────────────────┐         ┌──────────────────┐
│  React Native    │         │  React (Web)      │
│  (Mobile)        │         │  (Companion)     │
│                  │         │                  │
│  - Native UI     │         │  - DOM UI        │
│  - Camera       │         │  - Charts        │
│  - HealthKit    │         │  - Tables        │
│  - Health Conn. │         │  - Forms         │
│  - Push Notif.  │         │  - Settings UI   │
│  - Background  │         │                  │
└──────────────────┘         └──────────────────┘
        │                               │
        │                               │
        ▼                               ▼
┌──────────────────┐         ┌──────────────────┐
│  iOS App         │         │  Browser         │
│  (App Store)     │         │  (Web)           │
└──────────────────┘         └──────────────────┘
┌──────────────────┐
│  Android App     │
│  (Play Store)    │
└──────────────────┘
```

```
Client Request → Rust API → MongoDB (Encrypted)
     ↓              ↓            ↓
  Encryption  Decryption  Zero-Knowledge
     ↓              ↓            ↓
  Response ← Axum Server ← Storage
```

---

## Data Flow: Zero-Knowledge Encryption

### Client-Side Encryption Flow

1. **User enters health data** in mobile/web app
2. **Client generates encryption key** from user password (PBKDF2)
3. **Client encrypts data** (AES-256-GCM)
4. **Encrypted data sent** to backend API
5. **Backend stores** encrypted data in MongoDB (never sees plaintext)
6. **User retrieves data** (still encrypted)
7. **Client decrypts** with user's key
8. **Plaintext displayed** to user

### Shareable Links Flow

1. **User generates share link** with embedded password
2. **Password hashed** in link (self-contained decryption key)
3. **Recipient clicks link** (password + key in URL)
4. **Client decrypts** with embedded key
5. **Data displayed** (or expired/invalid)

---

## Health Sensor Integration

### Apple HealthKit (iOS)

**Data Types**:
- Steps (count, distance)
- Heart rate (resting, walking, variability)
- Sleep analysis (duration, quality, stages)
- Weight, height, BMI
- Blood pressure
- Temperature
- Oxygen saturation
- Menstrual cycle data
- Workouts and activity

**Integration**: react-native-health

### Google Health Connect (Android)

**Data Types**:
- Steps (count, distance)
- Heart rate (resting, variability)
- Sleep (sessions, stages)
- Weight, height
- Blood pressure
- Temperature
- Oxygen saturation
- Nutrition
- Menstrual cycle
- Exercise sessions

**Integration**: react-native-google-fit

---

## Implementation Timeline

### Phase 1: Mobile MVP (8-12 weeks)
- [ ] Setup React Native project
- [ ] Integrate HealthKit (iOS)
- [ ] Integrate Health Connect (Android)
- [ ] Implement encryption utilities
- [ ] Build API client
- [ ] Implement authentication
- [ ] Build core UI (profile, data entry, sync)
- [ ] Test QR scanning
- [ ] Implement background sync

### Phase 2: Backend API (6-8 weeks)
- [ ] Setup Axum project
- [ ] Implement authentication (JWT)
- [ ] Create MongoDB collections
- [ ] Implement CRUD API
- [ ] Add encryption middleware
- [ ] Implement shareable links
- [ ] Add rate limiting
- [ ] Implement logging/metrics

### Phase 3: Web Companion (4-6 weeks)
- [ ] Setup React project
- [ ] Share business logic from mobile
- [ ] Build chart visualization
- [ ] Build profile management UI
- [ ] Build family structure UI
- [ ] Build reporting interface

### Phase 4: Polish & Launch (4-6 weeks)
- [ ] Performance optimization
- [ ] Security audit
- [ ] App store submission
- [ ] Marketing materials
- [ ] User testing
- [ ] Beta launch

**Total Estimated Time**: 22-32 weeks (5.5-8 months)

---

## Next Research Priorities

### 1. State Management (Priority: High)

**Research Question**: Which state management library (Redux vs Zustand) is best for Normogen's encrypted health data platform?

**Options**:
- **Redux** (mature, large ecosystem, more boilerplate)
- **Zustand** (simple, modern, less boilerplate)
- **Jotai** (atomic, minimal, new)

**Considerations**:
- 70-80% code sharing between React Native and React
- Complex state (family structure, multi-person profiles)
- Offline synchronization
- Encrypted data caching
- TypeScript support
- Bundle size (mobile)

**Estimated Research Time**: 1-2 hours

---

### 2. Authentication Strategy (Priority: High)

**Research Question**: How to implement zero-knowledge authentication with recovery phrase support?

**Options**:
- **JWT** (stateless, scalable)
- **Session-based** (traditional, easier revocation)
- **Passkey/WebAuthn** (passwordless, modern)

**Considerations**:
- Zero-knowledge password recovery (from encryption.md)
- Token revocation strategy
- Multi-factor authentication (future)
- Integration with client-side encryption keys
- Family member access control

**Estimated Research Time**: 2-3 hours

---

### 3. Database Schema Design (Priority: High)

**Collections to Design**:
- Users (authentication, profiles)
- Families (family structure)
- Health Data (encrypted health records)
- Lab Results (encrypted lab data)
- Medications (encrypted medication data)
- Appointments (encrypted appointment data)
- Shared Links (time-limited access tokens)

**Estimated Research Time**: 3-4 hours

---

## Git Repository Status

**Current Branch**: main
**Latest Commit**: 307f496

### Commits

1. **e72602d** - Initial commit: Project setup and documentation
2. **eef5aed** - Research: Axum selected as Rust web framework
3. **307f496** - Research: React Native + React selected for mobile and web

### Research Files Created

- 2026-02-14-performance-findings.md (11,546 bytes)
- 2026-02-14-performance-research-notes.md (1,878 bytes)
- 2026-02-14-research-summary.md (4,141 bytes)
- 2026-02-14-rust-framework-comparison.md (5,901 bytes)
- 2026-02-14-rust-framework-performance-research.md (6,751 bytes)
- 2026-02-14-rust-framework-research-notes.md (3,938 bytes)
- 2026-02-14-tech-stack-decision.md (1,550 bytes)
- 2026-02-14-frontend-decision-summary.md (3,405 bytes)
- 2026-02-14-frontend-mobile-research.md (20,576 bytes)
- 2026-02-14-research-complete-summary.md (this file)

---

## Key Decisions Summary

### Backend: Axum
- **I/O Performance**: 18% faster for large encrypted data
- **Memory Efficiency**: 25% less memory for concurrent connections
- **Streaming**: Built-in support for large response streaming
- **Ecosystem**: Tower middleware ideal for encryption layers

### Frontend: React Native + React
- **Code Sharing**: 70-80% between mobile and web
- **Health Sensors**: Excellent HealthKit and Health Connect integration
- **Encryption**: Native crypto with Web Crypto API compatibility
- **Team Skills**: Single language (TypeScript) reduces development cost

---

## Risk Assessment

### Axum Risks

| Risk | Severity | Mitigation |
|------|----------|------------|
| Pre-1.0 API changes | Low | Strong backward compatibility maintained |
| Smaller ecosystem | Medium | Tower ecosystem compensates |
| Less mature than Actix | Low | Many production deployments exist |

### React Native Risks

| Risk | Severity | Mitigation |
|------|----------|------------|
| Performance overhead | Low | Good enough for health apps |
| JavaScript engine | Low | Hermes engine (faster, smaller) |
| Dependency issues | Medium | Careful management, stable libraries |

---

## Success Criteria

### Performance Targets
- **1000+ concurrent connections** (mid-term)
- **10,000+ concurrent connections** (long-term)
- **<100ms P95 latency** for API responses
- **<500ms encryption time** for 10MB data

### Feature Targets
- **Health sensor integration** (iOS + Android)
- **QR code scanning** for lab results
- **Background sync** every 5 minutes
- **Push notifications** for reminders
- **Zero-knowledge encryption** for all data
- **Shareable links** with expiring access

### User Experience Targets
- **Mobile-first** design for daily tracking
- **Web companion** for complex visualizations
- **Family structure** management
- **Multi-person profiles** (children, elderly)
- **Offline support** with sync

---

## Conclusion

**Research Phase 1 is complete**. Normogen's technology stack is now defined:

- **Backend**: Axum (Rust) for high-throughput encrypted data transfer
- **Mobile**: React Native for health sensor integration and code sharing
- **Web**: React for companion visualization and management
- **Database**: MongoDB for flexible encrypted storage

The chosen stack enables:
- **70-80% code sharing** between mobile and web
- **Zero-knowledge encryption** for privacy
- **Health sensor integration** for comprehensive tracking
- **Scalable architecture** for 1000+ concurrent connections
- **Single language** (TypeScript) for reduced development cost

**Next Steps**:
1. State management research (Redux vs Zustand)
2. Authentication system design (JWT with recovery phrases)
3. Database schema design
4. Proof-of-concept implementation

---

## References

### Backend
- [Axum Documentation](https://docs.rs/axum/)
- [Tokio Runtime](https://tokio.rs/)
- [Tower Middleware](https://docs.rs/tower/)
- [MongoDB Rust Driver](https://mongodb.github.io/mongo-rust-driver/)

### Frontend
- [React Native](https://reactnative.dev/)
- [React](https://react.dev/)
- [React Native Health](https://github.com/anthonyecamps/react-native-health)
- [React Native Google Fit](https://github.com/StasDoskalenko/react-native-google-fit)
- [React Native Quick Crypto](https://github.com/margelo/react-native-quick-crypto)
- [Recharts](https://recharts.org/)

### Health Platforms
- [Apple HealthKit Documentation](https://developer.apple.com/documentation/healthkit)
- [Google Health Connect](https://developer.android.com/health-and-fitness/google/health-connect)

### Security
- [AES-256-GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode)
- [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2)
- [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API)

---

**Last Updated**: 2026-02-14
**Status**: Ready for Phase 2 Research