normogen/README.md

# Normogen

## Overview

Normogen is a privacy-focused health data tracking and management platform. The name comes from Mapudungun, relating to Balanced Life.

## Vision

To record as many variables related to health as possible, store them in a secure, private manner, to be used by you, not by corporations. From medication reminders to pattern analysis, Normogen puts you in control of your health data.

## Technology Stack

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

### Mobile (iOS + Android)
- **Framework**: React Native 0.73+
- **Language**: TypeScript
- **State Management**: Redux Toolkit 2.x
- **Data Fetching**: RTK Query 2.x
- **Health Sensors**: react-native-health, react-native-google-fit
- **Encryption**: react-native-quick-crypto

### Web
- **Framework**: React 18+
- **Language**: TypeScript
- **State Management**: Redux Toolkit 2.x
- **Data Fetching**: RTK Query 2.x
- **Charts**: Recharts

### Deployment
- Docker on Linux

## Platform Strategy

**Primary: Mobile Apps** - Daily health tracking, sensor integration, QR scanning, push notifications

**Secondary: Web Browser** - Extensive reporting, visualization, profile management

## Key Features

- Zero-knowledge encryption
- Multi-person profiles
- Family structure management
- Secure sharing with expiring links
- Mobile apps with health sensor integration
- Web interface for complex visualizations
- JWT-based authentication with token rotation

## Security Model

- Client-side encryption: Data encrypted before leaving device
- Zero-knowledge: Server stores only encrypted data
- Proton-style encryption: AES-256-GCM with PBKDF2 key derivation
- Shareable links: Self-contained decryption keys in URLs
- Privacy-first: No data selling, subscription-based revenue
- JWT authentication with token rotation and revocation
- PBKDF2 password hashing (100,000 iterations)

## Documentation

- [Introduction](./introduction.md) - Project vision and detailed feature specification
- [Encryption Implementation Guide](./encryption.md) - Zero-knowledge encryption architecture
- [Research](./thoughts/research/) - Technical research and planning documents
- [Project Status](./thoughts/STATUS.md) - Development progress tracking

## Monorepo Structure

This is a **monorepo** containing backend, mobile, web, and shared code:

```
normogen/
├── backend/    # Rust backend (Axum + MongoDB)
├── mobile/     # React Native (iOS + Android)
├── web/        # React web app
├── shared/     # Shared TypeScript code
└── thoughts/   # Research & design docs
```

Each platform has its own `src/` directory to keep codebases separate while sharing common code through the `shared/` directory.

## Development Status

**Current Phase: Phase 2 - Backend Development**

### Completed

#### Phase 1 - Planning
- ✅ Project vision and requirements
- ✅ Security architecture design
- ✅ Encryption implementation guide
- ✅ Git repository initialization

#### Phase 2 - Backend (In Progress)
- ✅ **Phase 2.1** - Backend Project Initialization
  - Rust project setup with Axum
  - Docker configuration
  - Docker Compose setup
  - Kubernetes manifests
- ✅ **Phase 2.2** - MongoDB Connection & Models
  - MongoDB connection pooling
  - User model (email, password_hash, family_id, token_version)
  - RefreshToken model (token_hash, user_id, expires_at)
  - Family, Profile, HealthData models
  - Medication, LabResult, Appointment models
- ✅ **Phase 2.3** - JWT Authentication
  - JWT access tokens (15 min expiry)
  - JWT refresh tokens (30 day expiry)
  - Token rotation (old tokens revoked on refresh)
  - Token revocation (logout)
  - PBKDF2 password hashing (100K iterations)
  - Auth endpoints: register, login, refresh, logout
  - Protected routes with JWT middleware
  - Health check endpoints

### In Progress

#### Phase 2 - Backend
- 🚧 **Phase 2.4** - User Management Enhancement
  - Password recovery (zero-knowledge phrases)
  - Email verification flow
  - Enhanced profile management
  - Account settings endpoints

#### Future Phases
- **Phase 2.5** - Access Control
  - Permission-based middleware
  - Token version enforcement
  - Family access control
  
- **Phase 2.6** - Security Hardening
  - Rate limiting
  - Account lockout policies
  - Security audit logging

- **Phase 3** - Core API Development
- **Phase 4** - Encryption Layer
- **Phase 5** - Mobile App Development
- **Phase 6** - Web App Development

## Backend Quick Start

### Prerequisites

- Rust 1.70+
- MongoDB 4.4+
- Docker (optional, for containerized deployment)

### Local Development

```bash
# Clone repository
git clone <forgejo-url> normogen
cd normogen/backend

# Copy environment file
cp .env.example .env

# Edit .env with your configuration
# Required variables:
#   MONGODB_URI=mongodb://localhost:27017
#   DATABASE_NAME=normogen
#   JWT_SECRET=<your-secret-key-minimum-32-characters>

# Install dependencies
cargo build

# Run the server
cargo run

# Server will start on http://127.0.0.1:8000
```

### Docker Development

```bash
# Using Docker Compose (dev mode)
cd backend
docker compose -f docker-compose.dev.yml up -d

# Check status
curl http://localhost:8000/health

# View logs
docker compose logs -f backend
```

### Testing

```bash
# Run unit tests
cargo test

# Run integration tests (requires MongoDB)
cargo test --test auth_tests

# Manual testing with provided script
./thoughts/test_auth.sh
```

## Backend API Endpoints

### Public Endpoints (No Authentication)
```
POST /api/auth/register - User registration
POST /api/auth/login    - User login
POST /api/auth/refresh  - Token refresh (rotates tokens)
POST /api/auth/logout   - Logout (revokes token)
GET  /health            - Health check
GET  /ready             - Readiness check
```

### Protected Endpoints (JWT Required)
```
GET /api/users/me - Get user profile
```

## Environment Configuration

### Backend Environment Variables

```bash
# MongoDB Configuration
MONGODB_URI=mongodb://localhost:27017
DATABASE_NAME=normogen

# JWT Configuration
JWT_SECRET=<your-secret-key-minimum-32-characters>
JWT_ACCESS_TOKEN_EXPIRY_MINUTES=15
JWT_REFRESH_TOKEN_EXPIRY_DAYS=30

# Server Configuration
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
```

See `backend/.env.example` for a complete template.

## Repository Management

- **Git Hosting**: Forgejo (self-hosted)
- **CI/CD**: Forgejo Actions
- **Branch Strategy**: `main`, `develop`, `feature/*`
- **Deployment**: Docker Compose (homelab), Kubernetes (future)

## Deployment

### Backend Deployment (Production)

```bash
# Clone repository
git clone <forgejo-url> normogen
cd normogen/backend

# Setup configuration
cp .env.example .env
# Edit .env with production values

# Build and run with Docker Compose
docker compose up -d

# Check status
curl http://localhost:6000/health
```

**Resource Limits** (Homelab):
- CPU: 1000m (1 core)
- Memory: 1000Mi (1GB RAM)

**Ports**:
- Backend API: `6000` (host) → `8000` (container)
- MongoDB: `27017` (standard port)

## Open Source

Normogen is open-source. Both server and client code will be publicly available.

## Contributing

See [thoughts/STATUS.md](./thoughts/STATUS.md) for current development progress and next steps.

## License

[To be determined]