496 lines
14 KiB
Markdown
496 lines
14 KiB
Markdown
# 💊 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](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.
|