Files

William Valentin dec8c7b42e docs: add docker compose quickstart

2025-09-23 11:32:48 -07:00

17 KiB

Raw Permalink Blame History

💊 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

Check the documentation
Review the troubleshooting guide
Open an issue on GitHub

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and ensure all tests pass
Run quality checks: bun run lint:fix && bun run type-check
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
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.

17 KiB Raw Permalink Blame History Unescape Escape

💊 RxMinder

✨ Features

🔐 Authentication & Security

💊 Medication Management

⏰ Reminder System

📊 Analytics & Insights

🧪 Run Profiles

🎨 User Experience

🏗️ Architecture

Frontend Stack

Backend Services

Development Tools

🚀 Quick Start

Prerequisites

1. Clone and Setup

2. Install Dependencies

3. Configure Environment

4. Start Development

5. Access the Application

🔧 Development

Available Commands

Makefile Commands

Configuration Management

Environment Configuration

OAuth Redirects & Token Persistence

Database Strategy

🐳 Docker Development

Docker Compose Quickstart

Manual Build and Run

Docker Configuration

📝 Code Quality

Pre-commit Hooks

🧪 Testing

Test Structure

Running Tests

📁 Project Structure

🔐 Security Features

Authentication

Data Protection

Development Security

🎯 API Overview

Authentication

Medication Management

Reminder System

📚 Documentation

Complete Documentation Index

🏗️ Architecture & Design

🚀 Setup & Configuration

💻 Development

🔧 Implementation

🔍 Troubleshooting

Common Issues

Development Server Won't Start

Mock Database Issues

Build Failures

Getting Help

🤝 Contributing

Development Guidelines

📄 License

🙏 Acknowledgments

17 KiB

Raw Permalink Blame History