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

### **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](https://bun.sh) (for development)
- [Docker](https://docker.com) (optional, for containerized development)
- [Git](https://git-scm.com)

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

```bash
git clone <repository-url>
cd meds
```

### **2. Install Dependencies**

```bash
bun install
```

### **3. Configure Environment**

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

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

### **4. Start Development**

```bash
# 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**

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

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

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

```bash
# 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**

```bash
# 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
- **Nginx** 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`](docs/development/CODE_QUALITY.md) for detailed documentation.

### **Pre-commit Hooks**

```bash
# 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**

```bash
# 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`](docs/development/API.md).

## 📚 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) - Configuration philosophy

#### 🚀 Setup & Configuration

- [Complete Configuration Guide](docs/setup/COMPLETE_TEMPLATE_CONFIGURATION.md) - Full setup guide
- [Environment Variables](docs/setup/ENVIRONMENT_VARIABLES.md) - Configuration options
- [App Name Configuration](docs/setup/APP_NAME_CONFIGURATION.md) - Branding customization

#### 💻 Development

- [API Documentation](docs/development/API.md) - REST API endpoints
- [Database Service](docs/development/DATABASE.md) - Database layer documentation
- [Code Quality](docs/development/CODE_QUALITY.md) - Quality standards & tools
- [Application Security](docs/development/APPLICATION_SECURITY.md) - Security practices
- [Pre-commit Hooks](docs/development/PRE_COMMIT_HOOKS.md) - Git hook configuration

#### 🔧 Implementation

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

## 🔍 Troubleshooting

### **Common Issues**

#### **Development Server Won't Start**

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

# Check for TypeScript errors
bun run type-check
```

#### **Mock Database Issues**

```bash
# Restart development server
bun run dev

# Check configuration
make info
```

#### **Build Failures**

```bash
# Clear build artifacts
make clean

# Rebuild
make build
```

### **Getting Help**

1. Check the [documentation](docs/README.md)
2. Review the [troubleshooting guide](docs/development/CODE_QUALITY.md)
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](CONTRIBUTING.md) for detailed contribution guidelines.

## 📄 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
- **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.