alvaro/normogen
1
0
Fork 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions
normogen/docs/product/README.md
goose 17efc4f656 docs: reconcile documentation with reality (P3) 
Make the project's documentation match the code and remove the sprawl. The docs
claimed Phase 2.8 (drug interactions) was 'planning/0%' and the backend '~91%
complete' — both wrong: 2.8 is implemented and live, plus the P0/P1 security
and test work is done. Five root CI/CD docs described a 'docker-build' CI job
that was removed; ~18 backend/ status snapshots and ~24 docs/implementation
duplicates cluttered the tree.

Deletions (85 files):
- Root: 4 stale CI/CD reports (CI-CD-{COMPLETION-REPORT,IMPLEMENTATION-SUMMARY,
  STATUS-REPORT,FINAL-STATUS}.md) — all describe the removed docker-build job.
- backend/: 18 phase/build/fix snapshots and code-dump .txt files.
- docs/: the 3 one-time reorg reports; ~17 docs/implementation duplicates and
  process artifacts; 4 stale docs/development CI docs + git snapshots;
  redundant deployment/testing files.
- thoughts/: STATUS.md (said Phase 2.4 in-progress), superseded phase notes and
  duplicative research inputs. tmp/ (928KB of CI debug logs, gitignored).

Moves (18 files):
- 9 genuine decision records -> docs/adr/ (Architecture Decision Records),
  date-prefixes stripped, with an index README.
- 8 historical-but-valuable phase plans/specs + the old CI-CD-FINAL-SOLUTION ->
  docs/archive/ (now-populated, with a README explaining it's superseded
  material). thoughts/ tree removed.

Rewrites (13 files) to match reality:
- Drop the fake '% complete' figures everywhere in favor of Implemented /
  In-Progress / Planned with concrete endpoint/feature lists.
- Phase 2.8 -> Implemented; add /api/interactions/* and /api/auth/{refresh,
  logout} to the endpoint lists; fix 'Rust 1.93' -> edition 2021.
- Add a Security section (token_version validation, hashed refresh-token
  persistence, fail-fast config, real-IP audit) and correct the test-coverage
  and deployment claims to reality.
- New canonical docs/development/CI-CD.md (4 jobs: format/clippy/build/test,
  mongo service, no docker-build + why).
- README, docs/README, product/{STATUS,ROADMAP,PROGRESS,README,introduction},
  implementation/README, development/README, testing/README, AI_AGENT_GUIDE,
  .cursorrules, .gooserules all updated.

Verified: greps for 'Phase 2.8 (Planning)', 'PLANNING (0%)', 'Rust 1.93',
'91%/10%/85% complete', and 'docker-build' return nothing outside docs/archive;
all internal doc links resolve; backend/src untouched (cargo build clean).
2026-06-27 16:02:16 -03:00

359 lines
9.1 KiB
Markdown
Raw Blame History

# 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 (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
Reference in a new issue View git blame Copy permalink