💊 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.

✨ 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 and Docker Compose
• Bun (for local development)
• Git

1. Clone and Setup

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

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

2. Configure Environment

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

# Edit .env with your credentials
nano .env

3. Deploy

# 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

# Install dependencies
bun install

# Start development server
bun run dev

# Run with real CouchDB (Docker)
docker compose up -d couchdb
VITE_COUCHDB_URL=http://localhost:5984 bun run dev

Makefile Commands

🚀 Quick Start Deployment

For immediate testing and development:

# 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:

# 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 for detailed documentation.

# 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

# Run tests
bun run test

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

🔐 Security & Configuration

Environment Variables

Required Variables

# 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

# 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

# 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

# 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

# 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

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

Login User

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

OAuth Login

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

Change Password

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

Database Operations

User Management

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

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

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

# Build all services
docker compose build

# Build specific service
docker compose build frontend

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

Manage Services

# 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

# 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

# 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 for detailed testing documentation.

Test Production Environment

# 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

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

# Monitor resource usage
docker stats

Security Testing

# 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

# Quick local setup
./setup.sh

Production Deployment

# Secure production deployment
./deploy.sh production

Cloud Deployment

AWS EC2

# 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

# 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)

# 1. Copy and configure environment
cp .env.example .env
# Edit .env with your secure credentials

# 2. Deploy with templates (recommended)
./scripts/k8s-deploy-template.sh deploy

# Alternative: Manual deployment
# Create secrets manually
kubectl create secret generic meds-secrets \
  --from-literal=couchdb-password=secure-password \
  --from-literal=mailgun-api-key=your-key

# Apply manifests
kubectl apply -f k8s/

🔍 Troubleshooting

Common Issues

Environment Variables Not Loading

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

# Verify Docker Compose uses env file
docker compose config

CouchDB Connection Issues

# 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

# 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

# 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

# Check resource usage
docker stats

# Optimize Docker images
docker system prune -a

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

Debug Mode

# 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 which includes:

🏗️ Architecture & Design

• Project Structure - Codebase organization
• Template Approach - Design philosophy

🚀 Setup & Configuration

• Complete Template Configuration - Full setup guide
• Setup Complete - Post-setup verification

💻 Development

• API Documentation - REST API endpoints
• Code Quality - Quality standards & tools
• Application Security - App security practices

🚢 Deployment

• Deployment Guide - General deployment
• Docker Configuration - Docker setup
• Gitea Setup - CI/CD configuration

🔄 Migration Guides

• NodeJS Pre-commit Migration - Modern git hooks
• Buildx Migration - Docker improvements

📚 Additional Resources

Documentation

• CouchDB Documentation
• Mailgun API Reference
• Docker Compose Reference
• React Documentation

Development Tools

• Bun Documentation
• Vite Documentation
• TypeScript Handbook

Security Resources

• OWASP Security Guidelines
• Docker Security Best Practices
• CouchDB Security

🤝 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

# 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 - Code formatting, linting, and pre-commit hooks setup
• Security Guide - Security best practices and configuration
• Deployment Guide - Production deployment instructions
• API Documentation - Complete API reference
• Contributing Guide - Development guidelines and contribution process
• License - MIT license and third-party attributions
• Changelog - Version history and release notes

📄 License

This project is licensed under the MIT License - see the 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