💊 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

🧪 Run Profiles

Profile	Purpose	How to run	Configuration
Development	Fast local iteration with hot reload and mock services	bun run dev	Copy .env.example to .env.local for local overrides. CouchDB can be mocked (VITE_COUCHDB_URL=mock) or pointed to a dev instance.
Testing	Unit and integration validation in CI/stage	bun run test · bun run test:watch · bun run test:coverage	Tests run against the mock database strategy by default. No extra environment variables required.
Production	Hardened build served via Docker/Reverse proxy	bun run build && bun run preview or docker compose up --build	Populate .env with production credentials (CouchDB, Mailgun, OAuth). Review docs/setup/ENVIRONMENT_VARIABLES.md for required keys.

ℹ️ Tip: .env.example enumerates every variable consumed by the app. For local development prefer .env.local (ignored by Git) to avoid accidentally committing secrets.

🎨 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

Docker Compose Quickstart

docker compose up --build

• Serves the production build at http://localhost:8080
• Spins up CouchDB at http://localhost:5984 using credentials from .env
• Applies CORS settings from couchdb-config/cors.ini (update the allowed origins for custom domains)

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