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.

✨ 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

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

• Bun (for development)
• Docker (optional, for containerized development)
• Git

1. Clone and Setup

git clone <repository-url>
cd meds

2. Install Dependencies

bun install

3. Configure Environment

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

# Edit .env with your settings (optional - has smart defaults)
nano .env

4. Start Development

# Start development server
bun run dev

# Or use Makefile
make dev

5. Access the Application

• Frontend: http://localhost:5173
• CouchDB Admin (if using production database): http://localhost:5984/_utils

🔧 Development

Available Commands

# Development
bun run dev          # Start development server
bun run build        # Build for production
bun run preview      # Preview production build

# Code Quality
bun run format       # Format code with Prettier
bun run lint         # Lint code with ESLint
bun run lint:fix     # Fix linting issues
bun run type-check   # TypeScript type checking

# Testing
```bash
bun run test         # Run unit tests
bun run test:watch   # Run tests in watch mode

Makefile Commands

For convenience, you can use the included Makefile:

# Show all available commands
make help

# Development
make dev             # Start development server
make build           # Build application
make install         # Install dependencies
make clean           # Clean build artifacts

# Testing
make test            # Run unit tests
make test-watch      # Run tests in watch mode

# Docker
make docker-build    # Build Docker image
make docker-run      # Build and run container
make docker-clean    # Clean Docker resources

# Project info
make info            # Show project information

Configuration Management

The app uses a unified configuration system with smart defaults. You can view and understand the current configuration:

# View current configuration
bun run config              # Show current unified config
bun run config:env          # Show as environment variables
bun run config:help         # Show configuration help

# Or use the script directly
bun show-config.js          # Same as bun run config

Environment Configuration

The app uses a unified configuration system with smart defaults:

# Essential environment variables (optional - has defaults)
APP_NAME=RxMinder
NODE_ENV=development
VITE_COUCHDB_URL=http://localhost:5984
VITE_COUCHDB_USER=admin
VITE_COUCHDB_PASSWORD=secure-password

# Optional features
VITE_MAILGUN_API_KEY=your-mailgun-key
VITE_MAILGUN_DOMAIN=your-domain.com
VITE_GOOGLE_CLIENT_ID=your-google-client-id
VITE_GITHUB_CLIENT_ID=your-github-client-id

OAuth Redirects & Token Persistence

• OAuth Redirect URI

  • The redirect URI is derived from the unified configuration’s APP_BASE_URL:
    • Redirect URI = ${APP_BASE_URL}/auth/callback
  • Defaults:
    • Development: APP_BASE_URL=http://localhost:5173 → http://localhost:5173/auth/callback
    • Test: APP_BASE_URL=http://localhost:3000 → http://localhost:3000/auth/callback
    • Production: respects your configured base URL (e.g., https://rxminder.com/auth/callback)
  • To change the redirect URI, set APP_BASE_URL accordingly.

• Token Persistence (Email Verification & Password Reset)

  • Production (CouchDB configured): tokens are stored server-side in CouchDB (auth_tokens database) for secure, multi-device flows.
  • Development/Test or when CouchDB isn’t configured: tokens fall back to localStorage for demo purposes.
  • This hybrid approach enables secure flows in production while keeping local development simple.

Database Strategy

The application automatically selects the appropriate database strategy:

• Development: Mock database (instant responses, no setup required)
• Testing: Mock database (isolated test data)
• Production: CouchDB (persistent storage when configured)

🐳 Docker Development

Build and Run

# Build Docker image
make docker-build

# Build and run container
make docker-run

# Access at: http://localhost:8080

Docker Configuration

The Docker setup includes:

• Multi-stage build for optimized images
• Caddy for serving the built application
• Health checks for monitoring
• Environment variable support

📝 Code Quality

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

Pre-commit Hooks

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

# Manual quality checks
bun run format       # Format code
bun run lint:fix     # Fix linting issues
bun run type-check   # TypeScript validation

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

🧪 Testing

Test Structure

• Unit Tests: Jest-based tests for services and utilities
• Component Tests: React component testing
• Integration Tests: Service integration validation
• Integration Tests: Service validation and API testing

Running Tests

# Run unit tests
bun run test

# Run with coverage
bun run test:coverage

# Run integration tests
bun run test:services

📁 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
├── 🚀 index.tsx                    # React application entry
├── 🎯 App.tsx                      # Main React component
├── 📋 types.ts                     # Global type definitions
├── 🔒 .env.example                 # Environment template
│
├── 📁 components/                  # React components (by feature)
│   ├── 🔐 auth/                   # Authentication components
│   ├── 💊 medication/             # Medication management
│   ├── 📋 modals/                 # Modal dialogs
│   └── 🎨 ui/                     # Reusable UI components
│
├── 📁 services/                    # Business logic & APIs
│   ├── 🗄️ database/               # Database abstraction layer
│   ├── 📧 logging/                 # Centralized logging
│   └── 🔐 auth/                   # Authentication services
│
├── 📁 config/                      # Configuration management
│   └── ⚙️ unified.config.ts        # Centralized configuration
│
├── 📁 contexts/                    # React context providers
├── 📁 hooks/                       # Custom React hooks
├── 📁 utils/                       # Utility functions
├── 📁 types/                       # TypeScript definitions
│
├── 📁 tests/                       # Testing infrastructure
│   ├── 📁 e2e/                    # End-to-end tests
│   ├── 📁 integration/            # Integration tests
│   └── 📁 manual/                 # Manual testing scripts
│
├── 📁 docs/                        # Project documentation
│   ├── 📁 architecture/           # Design documentation
│   ├── 📁 development/            # Development guides
│   ├── 📁 setup/                  # Configuration guides
│   └── 📁 implementation/         # Current status
│
└── 📁 scripts/                     # Development scripts
    ├── 🔧 setup.sh                # Development setup
    ├── 🎨 process-html.sh         # Template processing
    └── 🧹 setup-pre-commit.sh     # Git hooks setup

🔐 Security Features

Authentication

• Secure password hashing with bcrypt
• JWT-based session management
• Email verification system
• OAuth provider integration (Google, GitHub)

Data Protection

• User data isolation by user ID
• Input validation and sanitization
• Environment-based credential management
• No hardcoded secrets in source code

Development Security

• Pre-commit hooks scan for secrets
• Environment variable validation
• Secure configuration templates
• Security-focused linting rules

🎯 API Overview

The application provides a comprehensive API for medication management:

Authentication

• User registration and login
• Email verification
• Password reset functionality
• OAuth integration

Medication Management

• CRUD operations for medications
• Dosage and frequency tracking
• Medication history
• User-specific data isolation

Reminder System

• Custom reminder creation
• Dose tracking (taken/missed)
• Adherence statistics
• Progress monitoring

For detailed API documentation, see docs/development/API.md.

📚 Documentation

Complete Documentation Index

For comprehensive documentation, visit docs/README.md which includes:

🏗️ Architecture & Design

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

🚀 Setup & Configuration

• Complete Configuration Guide - Full setup guide
• Environment Variables - Configuration options
• App Name Configuration - Branding customization

💻 Development

• API Documentation - REST API endpoints
• Database Service - Database layer documentation
• Code Quality - Quality standards & tools
• Application Security - Security practices
• Pre-commit Hooks - Git hook configuration

🔧 Implementation

• Implementation Summary - Current features and status

🔍 Troubleshooting

Common Issues

Development Server Won't Start

# Clear dependencies and reinstall
rm -rf node_modules bun.lockb
bun install

# Check for TypeScript errors
bun run type-check

Mock Database Issues

# Restart development server
bun run dev

# Check configuration
make info

Build Failures

# Clear build artifacts
make clean

# Rebuild
make build

Getting Help

1. Check the documentation
2. Review the troubleshooting guide
3. Open an issue on GitHub

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and ensure all tests pass
4. Run quality checks: bun run lint:fix && bun run type-check
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open a Pull Request

Development Guidelines

• Follow the existing code style and patterns
• Add tests for new functionality
• Update documentation as needed
• Ensure all quality checks pass

See CONTRIBUTING.md for detailed contribution guidelines.

📄 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
• Bun Team for the fast JavaScript runtime
• Vite Team for the amazing build tool

---

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

For support, please open an issue on GitHub or contact the development team.