normogen/docs/product

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)

# 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:6500/health

2. Access the API

The backend API will be available at http://localhost:6500

For Developers

1. Prerequisites

• Backend: Rust (edition 2021 toolchain), Docker
• Frontend: Node.js 18+, npm

2. Backend Development

cd backend
cargo build              # Build
cargo test               # Run tests
cargo run                # Run locally

3. Frontend Development

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 - Project background and purpose
2. Check STATUS.md - Current development status
3. Review ROADMAP.md - Development phases and timeline
4. Understand encryption.md - Security architecture

---

📊 Current Status

Backend: ✅ Phase 2.x feature-complete (through drug interactions); security-hardened; deployed on Solaria. Frontend: 🚧 Early (Login/Register + API/store layer; router not yet wired). Deployment: Docker on Solaria (image built manually — not in CI). Tests: 18 unit + 13 integration (auth + medication), CI-gated with MongoDB.

See STATUS.md for detailed progress tracking.

---

📚 Documentation Files

Core Documentation

README.md

This file - Product documentation overview and quick start.

STATUS.md

Current project status and progress tracking

• Overall status (Backend feature-complete through Phase 2.8; Frontend early stage)
• Phase-by-phase completion status
• Recently completed features
• Next milestones

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

---

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

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

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) implemented; open work is the frontend (Phase 3)
• Backend: Rust + Axum + MongoDB (Phase 2.x feature-complete, security-hardened)
• Frontend: React + TypeScript + Material-UI (early stage — Login/Register + API/store layer)

Technology Stack

Backend:

• Rust (edition 2021), 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 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

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

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

Testing

# 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: Phase 2.x feature-complete ✅

• ✅ Authentication & authorization (JWT, refresh-token rotation, token_version invalidation)
• ✅ User management
• ✅ Medication management
• ✅ Health statistics
• ✅ Lab results
• ✅ Security features (audit logging, account lockout, fail-fast config, real-IP audit)
• ✅ Drug interactions (Phase 2.8)

Frontend: Early stage 🚧

• 🚧 Login/register pages + API/store layer
• 📋 Router wiring, dashboard (planned)
• 📋 Medication UI (planned)

See STATUS.md for detailed progress.

---

🗺️ Roadmap

Phase 2.8 follow-ups (not started)

• 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 for complete roadmap.

---

🤝 Contributing

We welcome contributions! See:

• AI_AGENT_GUIDE.md - For AI agents and developers
• development/README.md - Development workflow
• implementation/README.md - Implementation details

---

📞 Support & Resources

Documentation

• Main Documentation Index
• AI Agent Guide
• Deployment Guide
• Testing Guide

External Resources

• Axum Documentation
• MongoDB Rust Driver
• React Documentation
• Material-UI

---

📝 License

TBD (not yet decided)

---

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