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.9
- **Runtime**: Tokio 1.41.1
- **Middleware**: Tower, Tower-HTTP
- **Database**: MongoDB (with zero-knowledge encryption)
- **Language**: Rust
- **Authentication**: JWT (PBKDF2 password hashing)

### Mobile (iOS + Android) - Planned
- **Framework**: React Native 0.73+
- **Language**: TypeScript
- **State Management**: Redux Toolkit 2.x
- **Data Fetching**: RTK Query 2.x

### Web - Planned
- **Framework**: React 18+
- **Language**: TypeScript
- **State Management**: Redux Toolkit 2.x

### Deployment
- Docker on Linux (Homelab)

## Key Features

- 🔐 **Zero-knowledge encryption** - Your data is encrypted before it reaches the server
- 👥 **Multi-person profiles** - Track health data for yourself, children, elderly family members
- 👨‍👩‍👧‍👦 **Family structure** - Manage family health records in one place
- 🔗 **Secure sharing** - Share specific data via expiring links with embedded passwords
- 📱 **Mobile apps** - iOS and Android with health sensor integration (planned)
- 🌐 **Web interface** - Access from any device (planned)

## Health Data Tracking

- Lab results storage
- Medication tracking (dosage, schedules, composition)
- Health statistics (weight, height, trends)
- Medical appointments
- Regular checkups
- Period tracking
- Pregnancy tracking
- Dental information
- Illness records
- Phone sensor data (steps, activity, sleep, blood pressure, temperature)

## Security Model

- **Client-side encryption**: Data encrypted before leaving the 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**: Token rotation and revocation
- **PBKDF2**: 100,000 iterations for password hashing

## 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](./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) - Planned
├── web/        # React web app - Planned
├── shared/     # Shared TypeScript code
└── thoughts/   # Research & design docs
```

## Development Status

**Current Phase: Phase 2 - Backend Development (75% Complete)**

### Completed

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

#### Phase 2 - Backend (In Progress)
- ✅ **Phase 2.1** - Backend Project Initialization
- ✅ **Phase 2.2** - MongoDB Connection & Models
- ✅ **Phase 2.3** - JWT Authentication
- ✅ **Phase 2.4** - User Management Enhancement
- ✅ **Phase 2.5** - Access Control
- ⏳ **Phase 2.6** - Security Hardening
- ⏳ **Phase 2.7** - Health Data Features

## Quick Start

### Backend Development

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

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

# Run with Docker Compose
docker compose up -d

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

### Testing

```bash
# Run unit tests
cargo test

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

## Backend API Endpoints

### Authentication (`/api/auth`)
- `POST /register` - User registration
- `POST /login` - User login
- `POST /refresh` - Token refresh (rotates tokens)
- `POST /logout` - Logout (revokes token)
- `POST /recover` - Password recovery

### User Management (`/api/users`)
- `GET /profile` - Get current user profile
- `PUT /profile` - Update profile
- `DELETE /profile` - Delete account
- `POST /password` - Change password
- `GET /settings` - Get user settings
- `PUT /settings` - Update settings

### Share Management (`/api/shares`)
- `POST /` - Create new share
- `GET /` - List all shares for current user
- `GET /:id` - Get specific share
- `PUT /:id` - Update share
- `DELETE /:id` - Delete share

### Permissions (`/api/permissions`)
- `GET /check` - Check if user has permission

## Environment Configuration

```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=6800
```

## Repository Management

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

## Open Source

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

## License

[To be determined]

## Contributing

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