💊 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

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
│   ├── 🗄️ couchdb.ts              # Mock database service
│   ├── 🗄️ couchdb.production.ts   # Real CouchDB service
│   ├── 🏭 couchdb.factory.ts      # Service factory
│   ├── 📧 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