rxminder/README.md

# 💊 RxMinder

A modern, secure web application for managing medication schedules and reminders. Built with React, TypeScript, CouchDB, and Docker for reliable medication tracking and adherence monitoring.

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![TypeScript](https://img.shields.io/badge/typescript-5.8.2-blue.svg)
![React](https://img.shields.io/badge/react-19.1.1-blue.svg)
![Docker](https://img.shields.io/badge/docker-ready-blue.svg)

## ✨ Features

### 🔐 **Authentication & Security**

- **Email/Password Authentication** with secure password hashing (bcrypt)
- **OAuth Integration** (Google, GitHub) for social login
- **Email Verification** for account activation
- **Password Reset** functionality with secure tokens
- **Admin Interface** for user management
- **Role-based Access Control** (User, Admin)

### 💊 **Medication Management**

- **Add/Edit/Delete Medications** with dosage and frequency
- **Flexible Scheduling** (Daily, Twice/Three times daily, Custom intervals)
- **Visual Medication Cards** with custom icons
- **Medication History** tracking

### ⏰ **Reminder System**

- **Smart Scheduling** based on medication frequency
- **Dose Tracking** (Taken, Missed, Upcoming)
- **Custom Reminders** with personalized messages
- **Adherence Statistics** and progress monitoring

### 📊 **Analytics & Insights**

- **Daily Adherence Statistics** with visual charts
- **Medication-specific Analytics** (taken vs missed doses)
- **Progress Tracking** over time
- **Export Capabilities** for healthcare providers

### 🎨 **User Experience**

- **Responsive Design** for mobile and desktop
- **Dark/Light Theme** support
- **Intuitive Interface** with modern design
- **Onboarding Flow** for new users
- **Avatar Customization** with image upload

## 🏗️ Architecture

### **Frontend Stack**

- **React 19** with TypeScript
- **Vite** for fast development and building
- **Modern CSS** with responsive design
- **Component-based Architecture**

### **Backend Services**

- **CouchDB** for document-based data storage
- **Mailgun** for email delivery (verification, password reset)
- **bcrypt** for secure password hashing
- **JWT-like** token system for authentication

### **Infrastructure**

- **Docker & Docker Compose** for containerization
- **Nginx** for production static file serving
- **Multi-stage Builds** for optimized images
- **Health Checks** for service monitoring

### **Development Tools**

- **TypeScript** for type safety and modern JavaScript features
- **ESLint** for code quality and consistent style
- **Prettier** for automated code formatting
- **Pre-commit hooks** for automated quality checks
- **Bun** for fast package management and development
- **Environment-based Configuration** for flexible deployments

## 🚀 Quick Start

### **Prerequisites**

- [Docker](https://docker.com) and Docker Compose
- [Bun](https://bun.sh) (for local development)
- [Git](https://git-scm.com)

### **1. Clone and Setup**

```bash
git clone <repository-url>
cd meds
./setup.sh

# Validate configuration (optional)
./validate-env.sh
```

### **2. Configure Environment**

```bash
# Copy the template and customize
cp .env.example .env

# Edit .env with your credentials
nano .env
```

### **3. Deploy**

```bash
# Quick deployment
./deploy.sh

# Or manual Docker Compose
docker compose up -d
```

### **4. Access the Application**

- **Frontend**: <http://localhost:8080>
- **CouchDB Admin**: <http://localhost:5984/\_utils>
- **Default Admin**: `admin@localhost` / `change-this-secure-password`

## 🔧 Development

### **Local Development**

```bash
# Install dependencies
bun install

# Start development server
bun run dev

# Run with custom database
VITE_COUCHDB_URL=http://localhost:5984 bun run dev
```

### **Makefile Commands**

## ⚙️ Configuration

This app uses a **unified configuration system** as the single source of truth. All settings come from `config/unified.config.ts` with smart defaults for each environment.

### **Check Current Configuration**

```bash
# View current unified configuration
bun run config

# See all available environment variables
bun run config:help

# Export current config as environment variables
bun run config:env
```

### **Environment Variables**

Only set environment variables when you need to override the smart defaults:

```bash
# Essential for production
NODE_ENV=production
VITE_COUCHDB_URL=http://your-couchdb:5984
VITE_COUCHDB_USER=admin
VITE_COUCHDB_PASSWORD=secure-password
JWT_SECRET=your-secure-jwt-secret

# Optional customizations
APP_NAME="My Custom App"
APP_BASE_URL=https://myapp.com
VITE_MAILGUN_API_KEY=your-key
VITE_GOOGLE_CLIENT_ID=your-google-id
```

### **How It Works**

1. **Smart Defaults**: Each environment (dev/staging/prod) has sensible defaults
2. **Environment Overrides**: Set only the variables you need to customize
3. **Type Safety**: All configuration is type-checked throughout the app
4. **Single Source**: No more scattered `.env` files or hardcoded values

## 🚀 Quick Start Deployment

For immediate testing and development:

```bash
# Start local development server
make dev

# Or deploy locally with Docker (includes database)
make deploy-local
# Access at: http://localhost:8080
# Stop with: make stop-local
```

## 📖 Available Commands

For convenience, you can use the included Makefile which wraps all package.json scripts with organized categories:

```bash
# Show all available commands
make help

# Quick development commands
make start          # Start development server
make build          # Build for development
make build-prod     # Build for production (requires configuration)
make test           # Run unit tests

# Local deployment (recommended for testing)
make deploy-local   # Deploy locally with Docker (http://localhost:8080)
make stop-local     # Stop local Docker deployment

# Testing commands
make test-all       # Run all tests (unit + integration + e2e)
make test-e2e       # Run end-to-end tests
make test-coverage  # Run tests with coverage

# Code quality
make lint           # Run all linting checks
make pre-commit     # Run pre-commit checks
make full-check     # Run complete code quality check

# Production deployment
make deploy-prod-quick      # Deploy to production with auto-generated secrets
make deploy-prod-configured # Deploy to production with pre-configured secrets
make deploy-local          # Deploy locally with Docker for testing

# Kubernetes deployment (requires cluster setup)
make deploy-dev     # Deploy to development environment (needs namespace)
make deploy-prod    # Deploy to production environment (needs namespace)
make undeploy-dev   # Remove development deployment
make undeploy-prod  # Remove production deployment
make validate-k8s   # Validate Kubernetes configurations

# Docker operations
make docker-build   # Build Docker images
make docker-setup   # Setup Docker buildx

# Quick combinations
make build-and-test # Build and test
make quick-deploy   # Build and deploy to K8s
make reset          # Clean and reinstall
```

All Makefile targets are organized into logical categories (Development, Testing, Code Quality, Kubernetes, Docker, etc.) and provide colored output for better visibility.

### **Code Quality**

This project includes comprehensive code quality tools and pre-commit hooks. See [`docs/development/CODE_QUALITY.md`](docs/development/CODE_QUALITY.md) for detailed documentation.

```bash
# Format code
bun run format

# Check formatting
bun run format:check

# Lint code
bun run lint

# Fix lint issues
bun run lint:fix

# Type checking
bun run type-check

# Run pre-commit checks
bun run pre-commit

# Setup pre-commit hooks (one-time)
./scripts/setup-pre-commit.sh
```

**Automatic Quality Checks**: Pre-commit hooks automatically format code, run linting, type checking, and security scans on every commit.

### **Testing**

```bash
# Run tests
bun run test

# Run specific test file
bun run test auth.integration.test.ts
```

## 🔐 Security & Configuration

### **Environment Variables**

#### **Required Variables**

```bash
# CouchDB Configuration
COUCHDB_USER=admin
COUCHDB_PASSWORD=your-secure-password
VITE_COUCHDB_URL=http://localhost:5984
VITE_COUCHDB_USER=admin
VITE_COUCHDB_PASSWORD=your-secure-password
```

#### **Optional Variables**

```bash
# Mailgun (for email features)
MAILGUN_API_KEY=your-mailgun-api-key
MAILGUN_DOMAIN=your-domain.com
MAILGUN_FROM_EMAIL=noreply@your-domain.com

# Production Settings
NODE_ENV=production
```

### **Security Best Practices**

1. **🔒 Never commit `.env` files** - Already in `.gitignore`
2. **🛡️ Use strong passwords** - Minimum 8 characters with mixed case, numbers, symbols
3. **🔄 Rotate credentials regularly** - Especially in production
4. **📧 Verify email configuration** - Test Mailgun setup before production
5. **🔍 Monitor logs** - Check Docker logs for security events
6. **🚪 Limit access** - Use firewall rules for production deployments

### **Credential Management Methods**

#### **Development**

```bash
# Method 1: .env file (recommended for local dev)
cp .env.example .env
# Edit with your values

# Method 2: Shell environment
export COUCHDB_PASSWORD="secure-password"
export MAILGUN_API_KEY="key-123..."
```

#### **Production**

```bash
# Method 1: Secure deployment script
./deploy.sh production

# Method 2: CI/CD with environment variables
# Set in GitHub Actions, GitLab CI, etc.

# Method 3: External secrets management
# AWS Secrets Manager, Azure Key Vault, etc.
```

#### **Docker Deployment**

```bash
# Using .env file
docker compose --env-file .env.production up -d

# Using environment variables
COUCHDB_PASSWORD="secure-password" docker compose up -d
```

## 📁 Project Structure

```
meds/
├── 📄 README.md                    # This documentation
├──  package.json                 # Dependencies and scripts
├── ⚙️ vite.config.ts               # Build configuration
├── 📝 tsconfig.json                # TypeScript configuration
├── 🎨 index.html                   # Entry point
├── 🚀 deploy.sh                    # Secure deployment script
├── 🔧 setup.sh                     # Development setup script
├── 🌱 seed-production.js           # Database seeding
├── 🧪 test-production.js           # Production testing
├── 🔒 .env.example                 # Environment template
│
├── 📁 docker/                      # Container configuration
│   ├── 🐳 Dockerfile              # Multi-stage Docker build
│   ├── 🐳 docker-compose.yaml     # Service orchestration
│   ├── 🌐 nginx.conf              # Production web server config
│   └── 🚫 .dockerignore           # Docker ignore patterns
│
├── 📁 components/                  # React components
│   ├── 🔐 AuthPage.tsx            # Login/register interface
│   ├── 👑 AdminInterface.tsx      # Admin user management
│   ├── 💊 AddMedicationModal.tsx  # Medication creation
│   ├── ⏰ ReminderCard.tsx        # Reminder display
│   ├── 📊 StatsModal.tsx          # Analytics dashboard
│   └── ...                        # Other UI components
│
├── 📁 services/                    # Business logic & APIs
│   ├── 🗄️ database/               # Unified database service
│   │   ├── DatabaseService.ts     # Main service with strategy pattern
│   │   ├── MockDatabaseStrategy.ts # In-memory implementation
│   │   └── ProductionDatabaseStrategy.ts # CouchDB implementation
│   ├── 📧 mailgun.service.ts      # Email delivery
│   ├── 📧 mailgun.config.ts       # Email configuration
│   ├── 🌱 database.seeder.ts      # Data seeding
│   └── 📁 auth/                   # Authentication services
│       ├── 🔐 auth.service.ts     # Core auth logic
│       ├── ✉️ emailVerification.service.ts
│       └── 📁 __tests__/          # Test suites
│
├── 📁 contexts/                    # React context providers
│   └── 👤 UserContext.tsx         # User state management
│
├── 📁 hooks/                       # Custom React hooks
│   ├── 💾 useLocalStorage.ts      # Persistent storage
│   ├── ⚙️ useSettings.ts          # User preferences
│   └── 🎨 useTheme.ts             # Theme management
│
└── 📁 utils/                       # Utility functions
    └── ⏰ schedule.ts              # Reminder scheduling
```

## 🎯 API Reference

### **Authentication Endpoints**

#### **Register User**

```typescript
authService.register(email: string, password: string, username?: string)
// Returns: { user: User, verificationToken: EmailVerificationToken }
```

#### **Login User**

```typescript
authService.login({ email: string, password: string });
// Returns: { user: User, accessToken: string, refreshToken: string }
```

#### **OAuth Login**

```typescript
authService.loginWithOAuth(provider: 'google' | 'github', userData: OAuthUserData)
// Returns: { user: User, accessToken: string, refreshToken: string }
```

#### **Change Password**

```typescript
authService.changePassword(userId: string, currentPassword: string, newPassword: string)
// Returns: { success: boolean, message: string }
```

### **Database Operations**

#### **User Management**

```typescript
dbService.saveUser(user: User): Promise<User>
dbService.findUserByEmail(email: string): Promise<User | null>
dbService.updateUser(userId: string, updates: Partial<User>): Promise<User>
dbService.deleteUser(userId: string): Promise<void>
```

#### **Medication Management**

```typescript
dbService.saveMedication(medication: Medication): Promise<Medication>
dbService.getMedications(userId: string): Promise<Medication[]>
dbService.updateMedication(medicationId: string, updates: Partial<Medication>): Promise<Medication>
dbService.deleteMedication(medicationId: string): Promise<void>
```

#### **Reminder & Dose Tracking**

```typescript
dbService.saveReminder(reminder: CustomReminder): Promise<CustomReminder>
dbService.getReminders(userId: string): Promise<CustomReminder[]>
dbService.saveTakenDose(dose: TakenDose): Promise<void>
dbService.getTakenDoses(userId: string, date?: string): Promise<TakenDoses>
```

## 🐳 Docker Reference

### **Build Images**

```bash
# Build all services
docker compose build

# Build specific service
docker compose build frontend

# Build with no cache
docker compose build --no-cache
```

### **Manage Services**

```bash
# Start all services
docker compose up -d

# Start specific service
docker compose up -d couchdb

# Stop all services
docker compose down

# View logs
docker compose logs
docker compose logs frontend
```

### **Database Management**

```bash
# Access CouchDB container
docker compose exec couchdb bash

# Backup database
docker compose exec couchdb curl -X GET http://admin:password@localhost:5984/users/_all_docs?include_docs=true

# Restore database
# Use CouchDB Fauxton interface or curl commands
```

## 🧪 Testing & Quality Assurance

### **Development Testing**

```bash
# Run all unit tests
bun run test

# Run tests in watch mode
bun run test:watch

# Run with coverage
bun run test:coverage

# Run integration tests
bun run test:integration

# Run E2E tests with Playwright
bun run test:e2e

# Run E2E tests in UI mode
bun run test:e2e:ui

# Debug E2E tests
bun run test:e2e:debug

# Run all tests (unit + integration + e2e)
bun run test:all
```

### **Testing Structure**

- **Unit Tests**: Jest-based tests for individual functions and components
- **Integration Tests**: Production environment validation and service testing
- **E2E Tests**: Playwright-based full user journey testing across browsers
- **Manual Tests**: Browser console debugging scripts

See [tests/README.md](tests/README.md) for detailed testing documentation.

### **Test Production Environment**

```bash
# Run comprehensive production tests
bun test-production.js

# Manual testing checklist
./deploy.sh                    # Deploy environment
# Visit http://localhost:8080
# Test user registration/login
# Test admin interface
# Test medication management
# Test password change
# Verify data persistence
```

### **Performance Testing**

```bash
# Check service health
docker compose ps
curl -f http://localhost:5984/_up
curl -f http://localhost:8080

# Monitor resource usage
docker stats
```

### **Security Testing**

```bash
# Check for vulnerable dependencies
bun audit

# Validate environment configuration
./deploy.sh --dry-run

# Test authentication flows
# - Registration with weak passwords
# - Login with wrong credentials
# - Access admin without proper role
```

## 🚀 Deployment Guide

### **Development Deployment**

```bash
# Quick local setup
./setup.sh
```

### **Production Deployment**

```bash
# Secure production deployment
./deploy.sh production
```

### **Cloud Deployment**

#### **AWS EC2**

```bash
# 1. Launch EC2 instance with Docker
# 2. Clone repository
git clone <repo-url>
cd meds

# 3. Configure environment
cp .env.example .env
# Edit .env with production values

# 4. Deploy
./deploy.sh production
```

#### **Google Cloud Run**

```bash
# Build and push image
gcloud builds submit --tag gcr.io/PROJECT-ID/meds-app

# Deploy with environment variables
gcloud run deploy meds-app \
  --image gcr.io/PROJECT-ID/meds-app \
  --set-env-vars COUCHDB_URL=your-couchdb-url \
  --set-env-vars MAILGUN_API_KEY=your-key
```

#### **Kubernetes (Template-Based)**

For configuration details:

```bash
# Check current unified configuration
bun run config

# See all environment variable options
bun run config:help

# Quick setup
cp .env.example .env
# Edit .env with your values (optional - smart defaults provided)
```

## 🔍 Troubleshooting

### **Common Issues**

#### **Environment Variables Not Loading**

```bash
# Check .env file exists and is properly formatted
cat .env

# Verify Docker Compose uses env file
docker compose config
```

#### **CouchDB Connection Issues**

```bash
# Check CouchDB health
curl -u admin:password http://localhost:5984/_up

# Verify credentials
docker compose logs couchdb

# Reset database
docker compose down
docker volume rm meds_couchdb-data
docker compose up -d
```

#### **Frontend Build Failures**

```bash
# Clear node modules and reinstall
rm -rf node_modules bun.lockb
bun install

# Check for TypeScript errors
bun run type-check

# Build with verbose output
bun run build --verbose
```

#### **Email Not Sending**

```bash
# Verify Mailgun configuration
echo $MAILGUN_API_KEY
echo $MAILGUN_DOMAIN

# Check Mailgun service logs
docker compose logs frontend | grep -i mailgun

# Test Mailgun API directly
curl -s --user 'api:YOUR_API_KEY' \
  https://api.mailgun.net/v3/YOUR_DOMAIN/messages \
  -F from='test@YOUR_DOMAIN' \
  -F to='you@example.com' \
  -F subject='Test' \
  -F text='Testing'
```

### **Performance Issues**

```bash
# Check resource usage
docker stats

# Optimize Docker images
docker system prune -a

# Monitor application performance
docker compose logs --tail=100 frontend
```

### **Debug Mode**

```bash
# Run with debug logging
DEBUG=* docker compose up

# Access container for debugging
docker compose exec frontend sh
docker compose exec couchdb bash
```

## 📚 Documentation

### **Complete Documentation Index**

For comprehensive documentation, visit **[`docs/README.md`](docs/README.md)** which includes:

#### 🏗️ Architecture & Design

- [Project Structure](docs/architecture/PROJECT_STRUCTURE.md) - Codebase organization
- [Template Approach](docs/architecture/TEMPLATE_APPROACH.md) - Design philosophy

#### 🚀 Setup & Configuration

- [Complete Template Configuration](docs/setup/COMPLETE_TEMPLATE_CONFIGURATION.md) - Full setup guide
- [Setup Complete](docs/setup/SETUP_COMPLETE.md) - Post-setup verification

#### 💻 Development

- [API Documentation](docs/development/API.md) - REST API endpoints
- [Code Quality](docs/development/CODE_QUALITY.md) - Quality standards & tools
- [Application Security](docs/development/APPLICATION_SECURITY.md) - App security practices

#### 🔧 Implementation

- [Implementation Summary](docs/implementation/IMPLEMENTATION_SUMMARY.md) - Current features and status

## 📚 Additional Resources

### **Documentation**

- [CouchDB Documentation](https://docs.couchdb.org/)
- [Mailgun API Reference](https://documentation.mailgun.com/)
- [Docker Compose Reference](https://docs.docker.com/compose/)
- [React Documentation](https://react.dev/)

### **Development Tools**

- [Bun Documentation](https://bun.sh/docs)
- [Vite Documentation](https://vitejs.dev/)
- [TypeScript Handbook](https://www.typescriptlang.org/docs/)

### **Security Resources**

- [OWASP Security Guidelines](https://owasp.org/)
- [Docker Security Best Practices](https://docs.docker.com/engine/security/)
- [CouchDB Security](https://docs.couchdb.org/en/stable/intro/security.html)

## 🤝 Contributing

1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
3. **Commit changes**: `git commit -m 'Add amazing feature'`
4. **Push to branch**: `git push origin feature/amazing-feature`
5. **Open a Pull Request**

### **Development Workflow**

```bash
# Setup development environment
./setup.sh

# Make changes and test
bun run dev
bun run lint
bun run type-check

# Test in production environment
./deploy.sh
bun test-production.js

# Submit pull request
```

## 📚 Documentation

### **Project Documentation**

- **[Code Quality Guide](docs/development/CODE_QUALITY.md)** - Code formatting, linting, and pre-commit hooks setup
- **[Security Guide](docs/development/APPLICATION_SECURITY.md)** - Security best practices and configuration
- **[API Documentation](docs/development/API.md)** - Complete API reference
- **[Contributing Guide](CONTRIBUTING.md)** - Development guidelines and contribution process
- **[License](LICENSE)** - MIT license and third-party attributions
- **[Changelog](CHANGELOG.md)** - Version history and release notes

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **CouchDB Team** for the robust database system
- **Mailgun** for reliable email delivery
- **React Team** for the excellent frontend framework
- **Docker Team** for containerization technology
- **Bun Team** for the fast JavaScript runtime

---

**Built with ❤️ for better medication adherence and health outcomes.**

For support, please open an issue on GitHub or contact the development team.<2E> Documentation