alvaro/normogen
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
normogen/thoughts/research/2026-02-14-research-complete-summary.md
goose 1701ce4518 Research: Phase 1 complete - Technology stack defined 
- Created comprehensive research summary document
- Backend: Axum selected for I/O performance and memory efficiency
- Frontend: React Native + React selected for code sharing
- Mobile-first platform strategy defined
- Implementation timeline estimated (22-32 weeks)
- Next research priorities identified

Key decisions:
- Axum: 18% faster for large encrypted data, 25% less memory
- React Native: 70-80% code sharing between mobile and web
- Single language (TypeScript) reduces development cost

Next: State management research (Redux vs Zustand)
2026-02-14 11:39:59 -03:00

526 lines
17 KiB
Markdown
Raw Blame History

# 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
Reference in a new issue View git blame Copy permalink