2bda21dc2a
- Document the useful show-config.js script and related npm scripts - Add section explaining bun run config, config:env, config:help commands - These commands help developers understand the unified configuration system - Script is functional and well-integrated, so keeping it and making it more discoverable
483 lines
14 KiB
Markdown
483 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
|
|
bun run test # Run unit tests
|
|
bun run test:watch # Run tests in watch mode
|
|
bun run test:e2e # Run end-to-end tests
|
|
```
|
|
|
|
### **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
|
|
```
|
|
|
|
### **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
|
|
- **E2E Tests**: Playwright-based full user journey testing
|
|
|
|
### **Running Tests**
|
|
|
|
```bash
|
|
# Run unit tests
|
|
bun run test
|
|
|
|
# Run with coverage
|
|
bun run test:coverage
|
|
|
|
# Run E2E tests
|
|
bun run test:e2e
|
|
|
|
# Run E2E tests in UI mode
|
|
bun run test:e2e:ui
|
|
```
|
|
|
|
## 📁 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.
|