Docs: Update README with current status and add config/quickstart guides

Changes: - Updated README.md with current Phase 2.3 completion status - Added detailed development progress section - Added backend API endpoints documentation - Added environment configuration guide - Added local development and Docker quick start - Added deployment instructions New Documentation: - thoughts/CONFIG.md - Comprehensive configuration guide - thoughts/QUICKSTART.md - 5-minute quick start guide All configuration files are now documented and up-to-date.
2026-02-15 09:25:03 -03:00 · 2026-02-15 09:25:03 -03:00 · 1c9c092dfa
commit 1c9c092dfa
parent 4e58fb832e
3 changed files with 737 additions and 102 deletions
--- a/README.md
+++ b/README.md
@ -1,101 +1,73 @@
-### /home/asoliver/desarrollo/normogen/README.md
-```markdown
-1: # Normogen
-2: 
-3: ## Overview
-4: 
-5: Normogen is a privacy-focused health data tracking and management platform. The name comes from Mapudungun, relating to Balanced Life.
-6: 
-7: ## Vision
-8: 
-9: 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.
-10: 
-11: ## Technology Stack
-12: 
-13: ### Backend
-14: - **Framework**: Axum 0.7.x
-15: - **Runtime**: Tokio 1.x
-16: - **Middleware**: Tower, Tower-HTTP
-17: - **Database**: MongoDB (with zero-knowledge encryption)
-18: - **Language**: Rust
-19: 
-20: ### Mobile (iOS + Android)
-21: - **Framework**: React Native 0.73+
-22: - **Language**: TypeScript
-23: - **State Management**: Redux Toolkit 2.x
-24: - **Data Fetching**: RTK Query 2.x
-25: - **Health Sensors**: react-native-health, react-native-google-fit
-26: - **Encryption**: react-native-quick-crypto
-27: 
-28: ### Web
-29: - **Framework**: React 18+
-30: - **Language**: TypeScript
-31: - **State Management**: Redux Toolkit 2.x
-32: - **Data Fetching**: RTK Query 2.x
-33: - **Charts**: Recharts
-34: 
-35: ### Deployment
-36: - Docker on Linux
-37: 
-38: ## Platform Strategy
-39: 
-40: **Primary: Mobile Apps** - Daily health tracking, sensor integration, QR scanning, push notifications
-41: 
-42: **Secondary: Web Browser** - Extensive reporting, visualization, profile management
-43: 
-44: ## Key Features
-45: 
-46: - Zero-knowledge encryption
-47: - Multi-person profiles
-48: - Family structure management
-49: - Secure sharing with expiring links
-50: - Mobile apps with health sensor integration
-51: - Web interface for complex visualizations
-52: 
-53: ## Security Model
-54: 
-55: - Client-side encryption: Data encrypted before leaving device
-56: - Zero-knowledge: Server stores only encrypted data
-57: - Proton-style encryption: AES-256-GCM with PBKDF2 key derivation
-58: - Shareable links: Self-contained decryption keys in URLs
-59: - Privacy-first: No data selling, subscription-based revenue
-60: 
-61: ## Documentation
-62: 
-63: - [Introduction](./introduction.md) - Project vision and detailed feature specification
-64: - [Encryption Implementation Guide](./encryption.md) - Zero-knowledge encryption architecture
-65: - [Research](./thoughts/research/) - Technical research and planning documents
-66: 
-67: ## Development Status
-68: 
-69: Phase: Planning/Documentation
-70: 
-71: ### Completed
-72: - Project vision and requirements
-73: - Security architecture design
-74: - Encryption implementation guide
-75: - Git repository initialization
-76: - **Rust framework selection: Axum**
-77: - **Mobile/Web framework selection: React Native + React**
-78: - **State management selection: Redux Toolkit 2.x**
-79: 
-80: ### Next Steps
-81: - Authentication system design (JWT with recovery phrases)
-82: - Database schema design
-83: - Create proof-of-concept with Axum
-84: - Implement basic CRUD API
-85: - Build mobile apps with health sensor integration
-86: - Build web companion app
-87: - Add encryption layer
-88: - Implement sharing functionality
-89: 
-90: ## Open Source
-91: 
-92: Normogen is open-source. Both server and client code will be publicly available.
-93: 
-94: Note: This project is currently in the planning phase. No implementation code has been written yet.
-```
+# 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.x
+- **Runtime**: Tokio 1.x
+- **Middleware**: Tower, Tower-HTTP
+- **Database**: MongoDB (with zero-knowledge encryption)
+- **Language**: Rust
+- **Authentication**: JWT (PBKDF2 password hashing)
+
+### Mobile (iOS + Android)
+- **Framework**: React Native 0.73+
+- **Language**: TypeScript
+- **State Management**: Redux Toolkit 2.x
+- **Data Fetching**: RTK Query 2.x
+- **Health Sensors**: react-native-health, react-native-google-fit
+- **Encryption**: react-native-quick-crypto
+
+### Web
+- **Framework**: React 18+
+- **Language**: TypeScript
+- **State Management**: Redux Toolkit 2.x
+- **Data Fetching**: RTK Query 2.x
+- **Charts**: Recharts
+
+### Deployment
+- Docker on Linux
+
+## Platform Strategy
+
+**Primary: Mobile Apps** - Daily health tracking, sensor integration, QR scanning, push notifications
+
+**Secondary: Web Browser** - Extensive reporting, visualization, profile management
+
+## Key Features
+
+- Zero-knowledge encryption
+- Multi-person profiles
+- Family structure management
+- Secure sharing with expiring links
+- Mobile apps with health sensor integration
+- Web interface for complex visualizations
+- JWT-based authentication with token rotation
+
+## Security Model
+
+- Client-side encryption: Data encrypted before leaving 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 with token rotation and revocation
+- PBKDF2 password hashing (100,000 iterations)
+
+## 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](./thoughts/STATUS.md) - Development progress tracking

 ## Monorepo Structure

@ -112,6 +84,163 @@ normogen/

 Each platform has its own `src/` directory to keep codebases separate while sharing common code through the `shared/` directory.

+## Development Status
+
+**Current Phase: Phase 2 - Backend Development**
+
+### Completed
+
+#### Phase 1 - Planning
+- ✅ Project vision and requirements
+- ✅ Security architecture design
+- ✅ Encryption implementation guide
+- ✅ Git repository initialization
+
+#### Phase 2 - Backend (In Progress)
+- ✅ **Phase 2.1** - Backend Project Initialization
+  - Rust project setup with Axum
+  - Docker configuration
+  - Docker Compose setup
+  - Kubernetes manifests
+- ✅ **Phase 2.2** - MongoDB Connection & Models
+  - MongoDB connection pooling
+  - User model (email, password_hash, family_id, token_version)
+  - RefreshToken model (token_hash, user_id, expires_at)
+  - Family, Profile, HealthData models
+  - Medication, LabResult, Appointment models
+- ✅ **Phase 2.3** - JWT Authentication
+  - JWT access tokens (15 min expiry)
+  - JWT refresh tokens (30 day expiry)
+  - Token rotation (old tokens revoked on refresh)
+  - Token revocation (logout)
+  - PBKDF2 password hashing (100K iterations)
+  - Auth endpoints: register, login, refresh, logout
+  - Protected routes with JWT middleware
+  - Health check endpoints
+
+### In Progress
+
+#### Phase 2 - Backend
+- 🚧 **Phase 2.4** - User Management Enhancement
+  - Password recovery (zero-knowledge phrases)
+  - Email verification flow
+  - Enhanced profile management
+  - Account settings endpoints
+
+#### Future Phases
+- **Phase 2.5** - Access Control
+  - Permission-based middleware
+  - Token version enforcement
+  - Family access control
+  
+- **Phase 2.6** - Security Hardening
+  - Rate limiting
+  - Account lockout policies
+  - Security audit logging
+
+- **Phase 3** - Core API Development
+- **Phase 4** - Encryption Layer
+- **Phase 5** - Mobile App Development
+- **Phase 6** - Web App Development
+
+## Backend Quick Start
+
+### Prerequisites
+
+- Rust 1.70+
+- MongoDB 4.4+
+- Docker (optional, for containerized deployment)
+
+### Local Development
+
+```bash
+# Clone repository
+git clone <forgejo-url> normogen
+cd normogen/backend
+
+# Copy environment file
+cp .env.example .env
+
+# Edit .env with your configuration
+# Required variables:
+#   MONGODB_URI=mongodb://localhost:27017
+#   DATABASE_NAME=normogen
+#   JWT_SECRET=<your-secret-key-minimum-32-characters>
+
+# Install dependencies
+cargo build
+
+# Run the server
+cargo run
+
+# Server will start on http://127.0.0.1:8000
+```
+
+### Docker Development
+
+```bash
+# Using Docker Compose (dev mode)
+cd backend
+docker compose -f docker-compose.dev.yml up -d
+
+# Check status
+curl http://localhost:8000/health
+
+# View logs
+docker compose logs -f backend
+```
+
+### Testing
+
+```bash
+# Run unit tests
+cargo test
+
+# Run integration tests (requires MongoDB)
+cargo test --test auth_tests
+
+# Manual testing with provided script
+./thoughts/test_auth.sh
+```
+
+## Backend API Endpoints
+
+### Public Endpoints (No Authentication)
+```
+POST /api/auth/register - User registration
+POST /api/auth/login    - User login
+POST /api/auth/refresh  - Token refresh (rotates tokens)
+POST /api/auth/logout   - Logout (revokes token)
+GET  /health            - Health check
+GET  /ready             - Readiness check
+```
+
+### Protected Endpoints (JWT Required)
+```
+GET /api/users/me - Get user profile
+```
+
+## Environment Configuration
+
+### Backend Environment Variables
+
+```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=8000
+```
+
+See `backend/.env.example` for a complete template.
+
 ## Repository Management

 - **Git Hosting**: Forgejo (self-hosted)
@ -121,7 +250,7 @@ Each platform has its own `src/` directory to keep codebases separate while shar

 ## Deployment

-### Backend Deployment
+### Backend Deployment (Production)

 ```bash
 # Clone repository
@ -129,11 +258,10 @@ git clone <forgejo-url> normogen
 cd normogen/backend

 # Setup configuration
-cp config/.env.example config/.env
-# Edit config/.env
+cp .env.example .env
+# Edit .env with production values

-# Build and run
-docker compose build
+# Build and run with Docker Compose
 docker compose up -d

 # Check status
@ -147,3 +275,15 @@ curl http://localhost:6000/health
 **Ports**:
 - Backend API: `6000` (host) → `8000` (container)
 - MongoDB: `27017` (standard port)
+
+## Open Source
+
+Normogen is open-source. Both server and client code will be publicly available.
+
+## Contributing
+
+See [thoughts/STATUS.md](./thoughts/STATUS.md) for current development progress and next steps.
+
+## License
+
+[To be determined]