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

316
thoughts/research/2026-02-14-tech-stack-decision.md
View file

@ -1,316 +0,0 @@
# 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](./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](./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](./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](./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**:
```javascript
// 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](./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](./2026-02-14-performance-findings.md)
- [Frontend Mobile Research](./2026-02-14-frontend-mobile-research.md)
- [State Management Research](./2026-02-14-state-management-research.md)
- [JWT Authentication Research](./2026-02-14-jwt-authentication-research.md)
- [MongoDB Schema Design](./2026-02-14-mongodb-schema-design-research.md)
- [Normogen Encryption Guide](../encryption.md)
- [Project Introduction](../introduction.md)