# Normogen - Product Documentation

Welcome to the **Normogen** product documentation. Normogen (Mapudungun for "Balanced Life") is an open-source health data platform for private, secure health data management.

---

## 🚀 Quick Start

### For Users

#### 1. Quick Setup (Docker)
```bash
# Clone the repository
git clone <repository-url>
cd normogen

# Start the backend with Docker
cd backend
docker compose up -d

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

#### 2. Access the API
The backend API will be available at `http://localhost:8000`

### For Developers

#### 1. Prerequisites
- **Backend**: Rust 1.93+, Docker
- **Frontend**: Node.js 18+, npm

#### 2. Backend Development
```bash
cd backend
cargo build              # Build
cargo test               # Run tests
cargo run                # Run locally
```

#### 3. Frontend Development
```bash
cd web/normogen-web
npm install              # Install dependencies
npm start                # Start dev server
npm test                 # Run tests
```

#### 4. Learn the Project
1. Read [introduction.md](./introduction.md) - Project background and purpose
2. Check [STATUS.md](./STATUS.md) - Current development status
3. Review [ROADMAP.md](./ROADMAP.md) - Development phases and timeline
4. Understand [encryption.md](./encryption.md) - Security architecture

---

## 📊 Current Status

**Phase**: 2.8 - Drug Interactions & Advanced Features (Planning)  
**Backend**: 91% complete  
**Frontend**: 10% complete  
**Deployment**: Docker on Solaria (production-ready)

See [STATUS.md](./STATUS.md) for detailed progress tracking.

---

## 📚 Documentation Files

### Core Documentation

#### [README.md](./README.md)
This file - Product documentation overview and quick start.

#### [STATUS.md](./STATUS.md)
**Current project status and progress tracking**

- Overall progress (Backend 91%, Frontend 10%)
- Phase-by-phase completion status
- Recently completed features
- Next milestones

**Last Updated**: 2026-03-09  
**Updates**: Real-time progress tracking

---

#### [ROADMAP.md](./ROADMAP.md)
**Development phases and milestones**

- Phase breakdown (1-5)
- Timeline estimates
- Feature planning
- Technology stack

**Last Updated**: 2026-03-09  
**Scope**: Complete project timeline through 2027

---

### Background & Context

#### [introduction.md](./introduction.md)
**Project introduction, motivation, and background**

- Naming origin (Mapudungun)
- Purpose and vision
- Business model (subscriptions, not data selling)
- Architecture overview
- Feature list

**Last Updated**: 2026-01-04  
**Length**: 82 lines

---

#### [encryption.md](./encryption.md)
**Security architecture and encryption design**

- Zero-knowledge encryption for MongoDB
- Shareable links with embedded passwords
- Security best practices
- Advanced features (recovery, revocation)
- Code examples (currently JavaScript, needs Rust)

**Size**: 32KB (1,248 lines)  
**Last Updated**: 2026-01-10  
**Note**: Comprehensive security documentation

---

## 🔑 Key Information

### Project Overview
- **Name**: Normogen (Balanced Life in Mapudungun)
- **Goal**: Open-source health data platform for private, secure health data management
- **Current Phase**: 2.8 - Drug Interactions & Advanced Features
- **Backend**: Rust + Axum + MongoDB (91% complete)
- **Frontend**: React + TypeScript + Material-UI (10% complete)

### Technology Stack

**Backend**:
- Rust 1.93, Axum 0.7
- MongoDB 7.0
- JWT authentication (15min access, 30day refresh)
- PBKDF2 password hashing (100K iterations)

**Frontend**:
- React 19.2.4, TypeScript 4.9.5
- Material-UI (MUI) 7.3.9
- Zustand 5.0.11 (state management)
- Axios 1.13.6 (HTTP client)

---

## 🎯 Key Features

### Implemented ✅
- JWT authentication with token rotation
- User management and profiles
- Permission-based access control
- Share management (share resources with others)
- Security hardening (rate limiting, audit logging)
- Medication management (CRUD, adherence tracking)
- Health statistics tracking
- Lab results storage
- OpenFDA integration

### In Progress 🚧
- Drug interaction checking (Phase 2.8)
- Automated reminder system
- Advanced health analytics

### Planned 🔮
- Healthcare data export (FHIR, HL7)
- Medication refill tracking
- Caregiver access
- Frontend dashboard
- Mobile apps (iOS, Android)
- AI/ML features

---

## 🔒 Security

Normogen implements enterprise-grade security:

- **Zero-knowledge encryption**: Data encrypted at rest
- **PBKDF2**: Password hashing with 100K iterations
- **JWT**: Secure authentication with token rotation
- **Rate limiting**: Protection against brute force
- **Audit logging**: Track all security events

See [encryption.md](./encryption.md) for comprehensive security documentation.

---

## 📡 API Endpoints

### Authentication
- `POST /api/auth/register` - User registration
- `POST /api/auth/login` - User login
- `POST /api/auth/logout` - User logout
- `POST /api/auth/refresh` - Refresh access token
- `POST /api/auth/recover-password` - Password recovery

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

### Medications
- `POST /api/medications` - Create medication
- `GET /api/medications` - List medications
- `GET /api/medications/:id` - Get medication
- `POST /api/medications/:id` - Update medication
- `POST /api/medications/:id/delete` - Delete medication
- `POST /api/medications/:id/log` - Log dose
- `GET /api/medications/:id/adherence` - Get adherence

### Health Statistics
- `POST /api/health-stats` - Create health stat
- `GET /api/health-stats` - List health stats
- `GET /api/health-stats/:id` - Get health stat
- `PUT /api/health-stats/:id` - Update health stat
- `DELETE /api/health-stats/:id` - Delete health stat
- `GET /api/health-stats/trends` - Get trends

### Shares & Permissions
- `POST /api/shares` - Create share
- `GET /api/shares` - List shares
- `PUT /api/shares/:id` - Update share
- `DELETE /api/shares/:id` - Delete share
- `POST /api/permissions/check` - Check permissions

### Sessions
- `GET /api/sessions` - List sessions
- `DELETE /api/sessions/:id` - Revoke session
- `DELETE /api/sessions/all` - Revoke all sessions

### Health Check
- `GET /health` - Health check endpoint

---

## 🛠️ Development

### Backend Development
```bash
cd backend
cargo build              # Build backend
cargo test               # Run tests
cargo clippy             # Lint
cargo run                # Run locally
docker compose up -d     # Run with Docker
```

### Frontend Development
```bash
cd web/normogen-web
npm install              # Install dependencies
npm start                # Start dev server
npm test                 # Run tests
```

### Testing
```bash
# Backend tests
cd backend && cargo test

# Frontend tests
cd web/normogen-web && npm test

# Integration tests
./docs/testing/quick-test.sh
./docs/testing/test-api-endpoints.sh
```

---

## 📈 Project Progress

### Backend: 91% Complete ✅
- ✅ Authentication & authorization
- ✅ User management
- ✅ Medication management
- ✅ Health statistics
- ✅ Lab results
- ✅ Security features
- 🚧 Drug interactions (Phase 2.8)

### Frontend: 10% Complete 🚧
- 🚧 Basic React structure
- 🚧 Login/register pages
- 📋 Dashboard (planned)
- 📋 Medication UI (planned)

See [STATUS.md](./STATUS.md) for detailed progress.

---

## 🗺️ Roadmap

### Phase 2.8 (Current - Planning)
- Drug interaction checking
- Automated reminders
- Advanced analytics
- Data export (FHIR, HL7)

### Phase 3 (Planned - Q2 2026)
- Complete frontend app
- Dashboard and visualization
- Medication management UI

### Phase 4 (Future - 2027)
- Mobile apps (iOS, Android)
- AI/ML features
- Third-party integrations

See [ROADMAP.md](./ROADMAP.md) for complete roadmap.

---

## 🤝 Contributing

We welcome contributions! See:
- [AI_AGENT_GUIDE.md](../AI_AGENT_GUIDE.md) - For AI agents and developers
- [development/README.md](../development/README.md) - Development workflow
- [implementation/README.md](../implementation/README.md) - Implementation details

---

## 📞 Support & Resources

### Documentation
- [Main Documentation Index](../README.md)
- [AI Agent Guide](../AI_AGENT_GUIDE.md)
- [Deployment Guide](../deployment/DEPLOYMENT_GUIDE.md)
- [Testing Guide](../testing/README.md)

### External Resources
- [Axum Documentation](https://docs.rs/axum/)
- [MongoDB Rust Driver](https://docs.rs/mongodb/)
- [React Documentation](https://react.dev/)
- [Material-UI](https://mui.com/)

---

## 📝 License

TBD (not yet decided)

---

**Last Updated**: 2026-03-09  
**Maintained By**: Project maintainers  
**For Questions**: Create an issue or discussion