fff1ed2e6d
Resolve the operational/config sprawl (#10-#14 from the review): the app read NORMOGEN_*/MONGODB_* env vars but every env/compose file set SERVER_*/DATABASE_*, the ports were all over the place (8080/8000/6500/6800), there were 5 inconsistent Dockerfiles (rust:1.82 vs rust:1.93, missing curl), and an 18 MB binary was committed. Env-var names — standardize on what the code reads: * config/mod.rs: NORMOGEN_PORT default 8080 -> 6500 (avoid the over-common 8000/8080). * db/mod.rs: create_database() now reads MONGODB_DATABASE (was DATABASE_NAME). * .env.example, defaults.env, docker-compose.yml, docker-compose.dev.yml, DEPLOYMENT_GUIDE.md, deployment/README.md, deploy-and-test-solaria.sh, deploy-local-build.sh: use NORMOGEN_HOST/NORMOGEN_PORT/MONGODB_URI/ MONGODB_DATABASE/APP_ENVIRONMENT; drop the dead SERVER_*/DATABASE_URI/ DATABASE_NAME names. Ports — canonical container port 6500 everywhere: * Both Dockerfiles EXPOSE 6500; prod compose maps 6500:6500, dev 6501:6500. * Bulk-replaced the long tail of solaria:8000/localhost:8000/localhost:8080 in docs and test scripts -> 6500. Dockerfiles — 2 canonical, rust:latest, curl + healthcheck: * backend/Dockerfile (prod): rust:latest builder, debian runtime now installs curl (so the compose HEALTHCHECK actually works), EXPOSE 6500. * backend/docker/Dockerfile.dev (dev): rust:latest both stages, EXPOSE 6500. * Deleted 3 redundant Dockerfiles (Dockerfile.improved x2, docker/Dockerfile). * Deleted the committed 18 MB binary backend/docker/normogen-backend. * Deleted 2 stray fix-notes in backend/docker/. Compose: * docker-compose.yml: correct env names, 6500:6500, APP_ENVIRONMENT=production, JWT_SECRET/ENCRYPTION_KEY required via compose interpolation, dropped the obsolete top-level version: key. * docker-compose.dev.yml: correct env names, 6501:6500, mongo:7 (was 6.0), added a working backend healthcheck. * Deleted docker/docker-compose.improved.yml + backend/deploy-to-solaria-improved.sh (built around the now-deleted 'improved' Docker files). Verified: cargo fmt --check clean, build + clippy --all-targets clean, 18 unit tests pass; grep confirms no SERVER_*/DATABASE_* env names and no rust:1.x tags remain outside docs/archive and docs/adr (historical).
359 lines
9.1 KiB
Markdown
359 lines
9.1 KiB
Markdown
# 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: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
|
|
```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
|
|
|
|
**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](./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 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](./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) 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](./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: 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](./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](./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
|