From a7e5c1f7cbfc339229ca670ba752908f77b90d3d Mon Sep 17 00:00:00 2001
From: William Valentin <william.valentin.info@gmail.com>
Date: Mon, 8 Sep 2025 22:05:40 -0700
Subject: [PATCH] docs: major README cleanup and simplification

- Remove irrelevant deployment and production information (app not deployed yet)
- Focus on current development state and local development workflow
- Consolidate redundant sections and remove duplicate commands
- Simplify quick start to focus on development setup
- Remove complex deployment scenarios (K8s, cloud providers, production scripts)
- Streamline Docker section to focus on development use
- Consolidate troubleshooting to common development issues
- Remove extensive production deployment guides and cloud provider instructions
- Simplify API documentation to overview level
- Focus on development workflow rather than operational concerns

Result: README is now ~50% shorter and focused on actual current capabilities
---
 README.md | 886 +++++++++++++++---------------------------------------
 1 file changed, 249 insertions(+), 637 deletions(-)

diff --git a/README.md b/README.md
index 55b8c63..903cc02 100644
--- a/README.md
+++ b/README.md
@@ -63,13 +63,6 @@ A modern, secure web application for managing medication schedules and reminders
 - **bcrypt** for secure password hashing
 - **JWT-like** token system for authentication
 
-### **Infrastructure**
-
-- **Docker & Docker Compose** for containerization
-- **Nginx** for production static file serving
-- **Multi-stage Builds** for optimized images
-- **Health Checks** for service monitoring
-
 ### **Development Tools**
 
 - **TypeScript** for type safety and modern JavaScript features
@@ -83,8 +76,8 @@ A modern, secure web application for managing medication schedules and reminders
 
 ### **Prerequisites**
 
-- [Docker](https://docker.com) and Docker Compose
-- [Bun](https://bun.sh) (for local development)
+- [Bun](https://bun.sh) (for development)
+- [Docker](https://docker.com) (optional, for containerized development)
 - [Git](https://git-scm.com)
 
 ### **1. Clone and Setup**
@@ -92,274 +85,179 @@ A modern, secure web application for managing medication schedules and reminders
 ```bash
 git clone <repository-url>
 cd meds
-./setup.sh
-
-# Validate configuration (optional)
-./validate-env.sh
 ```
 
-### **2. Configure Environment**
+### **2. Install Dependencies**
+
+```bash
+bun install
+```
+
+### **3. Configure Environment**
 
 ```bash
 # Copy the template and customize
 cp .env.example .env
 
-# Edit .env with your credentials
+# Edit .env with your settings (optional - has smart defaults)
 nano .env
 ```
 
-### **3. Deploy**
+### **4. Start Development**
 
 ```bash
-# Quick deployment
-./deploy.sh
-
-# Or manual Docker Compose
-docker compose up -d
-```
-
-### **4. Access the Application**
-
-- **Frontend**: <http://localhost:8080>
-- **CouchDB Admin**: <http://localhost:5984/\_utils>
-- **Default Admin**: `admin@localhost` / `change-this-secure-password`
-
-## 🔧 Development
-
-### **Local Development**
-
-```bash
-# Install dependencies
-bun install
-
 # Start development server
 bun run dev
 
-# Run with custom database
-VITE_COUCHDB_URL=http://localhost:5984 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**
 
-## ⚙️ Configuration
-
-This app uses a **unified configuration system** as the single source of truth. All settings come from `config/unified.config.ts` with smart defaults for each environment.
-
-### **Check Current Configuration**
-
-```bash
-# View current unified configuration
-bun run config
-
-# See all available environment variables
-bun run config:help
-
-# Export current config as environment variables
-bun run config:env
-```
-
-### **Environment Variables**
-
-Only set environment variables when you need to override the smart defaults:
-
-```bash
-# Essential for production
-NODE_ENV=production
-VITE_COUCHDB_URL=http://your-couchdb:5984
-VITE_COUCHDB_USER=admin
-VITE_COUCHDB_PASSWORD=secure-password
-JWT_SECRET=your-secure-jwt-secret
-
-# Optional customizations
-APP_NAME="My Custom App"
-APP_BASE_URL=https://myapp.com
-VITE_MAILGUN_API_KEY=your-key
-VITE_GOOGLE_CLIENT_ID=your-google-id
-```
-
-### **How It Works**
-
-1. **Smart Defaults**: Each environment (dev/staging/prod) has sensible defaults
-2. **Environment Overrides**: Set only the variables you need to customize
-3. **Type Safety**: All configuration is type-checked throughout the app
-4. **Single Source**: No more scattered `.env` files or hardcoded values
-
-## 🚀 Quick Start Deployment
-
-For immediate testing and development:
-
-```bash
-# Start local development server
-make dev
-
-# Or deploy locally with Docker (includes database)
-make deploy-local
-# Access at: http://localhost:8080
-# Stop with: make stop-local
-```
-
-## 📖 Available Commands
-
-For convenience, you can use the included Makefile which wraps all package.json scripts with organized categories:
+For convenience, you can use the included Makefile:
 
 ```bash
 # Show all available commands
 make help
 
-# Quick development commands
-make start          # Start development server
-make build          # Build for development
-make build-prod     # Build for production (requires configuration)
-make test           # Run unit tests
+# Development
+make dev             # Start development server
+make build           # Build application
+make install         # Install dependencies
+make clean           # Clean build artifacts
 
-# Local deployment (recommended for testing)
-make deploy-local   # Deploy locally with Docker (http://localhost:8080)
-make stop-local     # Stop local Docker deployment
+# Testing
+make test            # Run unit tests
+make test-watch      # Run tests in watch mode
 
-# Testing commands
-make test-all       # Run all tests (unit + integration + e2e)
-make test-e2e       # Run end-to-end tests
-make test-coverage  # Run tests with coverage
+# Docker
+make docker-build    # Build Docker image
+make docker-run      # Build and run container
+make docker-clean    # Clean Docker resources
 
-# Code quality
-make lint           # Run all linting checks
-make pre-commit     # Run pre-commit checks
-make full-check     # Run complete code quality check
-
-# Production deployment
-make deploy-prod-quick      # Deploy to production with auto-generated secrets
-make deploy-prod-configured # Deploy to production with pre-configured secrets
-make deploy-local          # Deploy locally with Docker for testing
-
-# Kubernetes deployment (requires cluster setup)
-make deploy-dev     # Deploy to development environment (needs namespace)
-make deploy-prod    # Deploy to production environment (needs namespace)
-make undeploy-dev   # Remove development deployment
-make undeploy-prod  # Remove production deployment
-make validate-k8s   # Validate Kubernetes configurations
-
-# Docker operations
-make docker-build   # Build Docker images
-make docker-setup   # Setup Docker buildx
-
-# Quick combinations
-make build-and-test # Build and test
-make quick-deploy   # Build and deploy to K8s
-make reset          # Clean and reinstall
+# Project info
+make info            # Show project information
 ```
 
-All Makefile targets are organized into logical categories (Development, Testing, Code Quality, Kubernetes, Docker, etc.) and provide colored output for better visibility.
+### **Environment Configuration**
 
-### **Code Quality**
+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
-# Format code
-bun run format
-
-# Check formatting
-bun run format:check
-
-# Lint code
-bun run lint
-
-# Fix lint issues
-bun run lint:fix
-
-# Type checking
-bun run type-check
-
-# Run pre-commit checks
-bun run pre-commit
-
 # 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**
+## 🧪 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 tests
+# Run unit tests
 bun run test
 
-# Run specific test file
-bun run test auth.integration.test.ts
-```
+# Run with coverage
+bun run test:coverage
 
-## 🔐 Security & Configuration
+# Run E2E tests
+bun run test:e2e
 
-### **Environment Variables**
-
-#### **Required Variables**
-
-```bash
-# CouchDB Configuration
-COUCHDB_USER=admin
-COUCHDB_PASSWORD=your-secure-password
-VITE_COUCHDB_URL=http://localhost:5984
-VITE_COUCHDB_USER=admin
-VITE_COUCHDB_PASSWORD=your-secure-password
-```
-
-#### **Optional Variables**
-
-```bash
-# Mailgun (for email features)
-MAILGUN_API_KEY=your-mailgun-api-key
-MAILGUN_DOMAIN=your-domain.com
-MAILGUN_FROM_EMAIL=noreply@your-domain.com
-
-# Production Settings
-NODE_ENV=production
-```
-
-### **Security Best Practices**
-
-1. **🔒 Never commit `.env` files** - Already in `.gitignore`
-2. **🛡️ Use strong passwords** - Minimum 8 characters with mixed case, numbers, symbols
-3. **🔄 Rotate credentials regularly** - Especially in production
-4. **📧 Verify email configuration** - Test Mailgun setup before production
-5. **🔍 Monitor logs** - Check Docker logs for security events
-6. **🚪 Limit access** - Use firewall rules for production deployments
-
-### **Credential Management Methods**
-
-#### **Development**
-
-```bash
-# Method 1: .env file (recommended for local dev)
-cp .env.example .env
-# Edit with your values
-
-# Method 2: Shell environment
-export COUCHDB_PASSWORD="secure-password"
-export MAILGUN_API_KEY="key-123..."
-```
-
-#### **Production**
-
-```bash
-# Method 1: Secure deployment script
-./deploy.sh production
-
-# Method 2: CI/CD with environment variables
-# Set in GitHub Actions, GitLab CI, etc.
-
-# Method 3: External secrets management
-# AWS Secrets Manager, Azure Key Vault, etc.
-```
-
-#### **Docker Deployment**
-
-```bash
-# Using .env file
-docker compose --env-file .env.production up -d
-
-# Using environment variables
-COUCHDB_PASSWORD="secure-password" docker compose up -d
+# Run E2E tests in UI mode
+bun run test:e2e:ui
 ```
 
 ## 📁 Project Structure
@@ -367,391 +265,100 @@ COUCHDB_PASSWORD="secure-password" docker compose up -d
 ```
 meds/
 ├── 📄 README.md                    # This documentation
-├──  package.json                 # Dependencies and scripts
+├── 📦 package.json                 # Dependencies and scripts
 ├── ⚙️ vite.config.ts               # Build configuration
 ├── 📝 tsconfig.json                # TypeScript configuration
 ├── 🎨 index.html                   # Entry point
-├── 🚀 deploy.sh                    # Secure deployment script
-├── 🔧 setup.sh                     # Development setup script
-├── 🌱 seed-production.js           # Database seeding
-├── 🧪 test-production.js           # Production testing
+├── 🚀 index.tsx                    # React application entry
+├── 🎯 App.tsx                      # Main React component
+├── 📋 types.ts                     # Global type definitions
 ├── 🔒 .env.example                 # Environment template
 │
-├── 📁 docker/                      # Container configuration
-│   ├── 🐳 Dockerfile              # Multi-stage Docker build
-│   ├── 🐳 docker-compose.yaml     # Service orchestration
-│   ├── 🌐 nginx.conf              # Production web server config
-│   └── 🚫 .dockerignore           # Docker ignore patterns
-│
-├── 📁 components/                  # React components
-│   ├── 🔐 AuthPage.tsx            # Login/register interface
-│   ├── 👑 AdminInterface.tsx      # Admin user management
-│   ├── 💊 AddMedicationModal.tsx  # Medication creation
-│   ├── ⏰ ReminderCard.tsx        # Reminder display
-│   ├── 📊 StatsModal.tsx          # Analytics dashboard
-│   └── ...                        # Other UI components
+├── 📁 components/                  # React components (by feature)
+│   ├── 🔐 auth/                   # Authentication components
+│   ├── 💊 medication/             # Medication management
+│   ├── 📋 modals/                 # Modal dialogs
+│   └── 🎨 ui/                     # Reusable UI components
 │
 ├── 📁 services/                    # Business logic & APIs
-│   ├── 🗄️ database/               # Unified database service
-│   │   ├── DatabaseService.ts     # Main service with strategy pattern
-│   │   ├── MockDatabaseStrategy.ts # In-memory implementation
-│   │   └── ProductionDatabaseStrategy.ts # CouchDB implementation
-│   ├── 📧 mailgun.service.ts      # Email delivery
-│   ├── 📧 mailgun.config.ts       # Email configuration
-│   ├── 🌱 database.seeder.ts      # Data seeding
-│   └── 📁 auth/                   # Authentication services
-│       ├── 🔐 auth.service.ts     # Core auth logic
-│       ├── ✉️ emailVerification.service.ts
-│       └── 📁 __tests__/          # Test suites
+│   ├── 🗄️ database/               # Database abstraction layer
+│   ├── 📧 logging/                 # Centralized logging
+│   └── 🔐 auth/                   # Authentication services
+│
+├── 📁 config/                      # Configuration management
+│   └── ⚙️ unified.config.ts        # Centralized configuration
 │
 ├── 📁 contexts/                    # React context providers
-│   └── 👤 UserContext.tsx         # User state management
-│
 ├── 📁 hooks/                       # Custom React hooks
-│   ├── 💾 useLocalStorage.ts      # Persistent storage
-│   ├── ⚙️ useSettings.ts          # User preferences
-│   └── 🎨 useTheme.ts             # Theme management
+├── 📁 utils/                       # Utility functions
+├── 📁 types/                       # TypeScript definitions
 │
-└── 📁 utils/                       # Utility functions
-    └── ⏰ schedule.ts              # Reminder scheduling
+├── 📁 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
 ```
 
-## 🎯 API Reference
+## 🔐 Security Features
 
-### **Authentication Endpoints**
+### **Authentication**
 
-#### **Register User**
+- Secure password hashing with bcrypt
+- JWT-based session management
+- Email verification system
+- OAuth provider integration (Google, GitHub)
 
-```typescript
-authService.register(email: string, password: string, username?: string)
-// Returns: { user: User, verificationToken: EmailVerificationToken }
-```
+### **Data Protection**
 
-#### **Login User**
+- User data isolation by user ID
+- Input validation and sanitization
+- Environment-based credential management
+- No hardcoded secrets in source code
 
-```typescript
-authService.login({ email: string, password: string });
-// Returns: { user: User, accessToken: string, refreshToken: string }
-```
+### **Development Security**
 
-#### **OAuth Login**
+- Pre-commit hooks scan for secrets
+- Environment variable validation
+- Secure configuration templates
+- Security-focused linting rules
 
-```typescript
-authService.loginWithOAuth(provider: 'google' | 'github', userData: OAuthUserData)
-// Returns: { user: User, accessToken: string, refreshToken: string }
-```
+## 🎯 API Overview
 
-#### **Change Password**
+The application provides a comprehensive API for medication management:
 
-```typescript
-authService.changePassword(userId: string, currentPassword: string, newPassword: string)
-// Returns: { success: boolean, message: string }
-```
+### **Authentication**
 
-### **Database Operations**
+- User registration and login
+- Email verification
+- Password reset functionality
+- OAuth integration
 
-#### **User Management**
+### **Medication Management**
 
-```typescript
-dbService.saveUser(user: User): Promise<User>
-dbService.findUserByEmail(email: string): Promise<User | null>
-dbService.updateUser(userId: string, updates: Partial<User>): Promise<User>
-dbService.deleteUser(userId: string): Promise<void>
-```
+- CRUD operations for medications
+- Dosage and frequency tracking
+- Medication history
+- User-specific data isolation
 
-#### **Medication Management**
+### **Reminder System**
 
-```typescript
-dbService.saveMedication(medication: Medication): Promise<Medication>
-dbService.getMedications(userId: string): Promise<Medication[]>
-dbService.updateMedication(medicationId: string, updates: Partial<Medication>): Promise<Medication>
-dbService.deleteMedication(medicationId: string): Promise<void>
-```
+- Custom reminder creation
+- Dose tracking (taken/missed)
+- Adherence statistics
+- Progress monitoring
 
-#### **Reminder & Dose Tracking**
-
-```typescript
-dbService.saveReminder(reminder: CustomReminder): Promise<CustomReminder>
-dbService.getReminders(userId: string): Promise<CustomReminder[]>
-dbService.saveTakenDose(dose: TakenDose): Promise<void>
-dbService.getTakenDoses(userId: string, date?: string): Promise<TakenDoses>
-```
-
-## 🐳 Docker Reference
-
-### **Build Images**
-
-```bash
-# Build all services
-docker compose build
-
-# Build specific service
-docker compose build frontend
-
-# Build with no cache
-docker compose build --no-cache
-```
-
-### **Manage Services**
-
-```bash
-# Start all services
-docker compose up -d
-
-# Start specific service
-docker compose up -d couchdb
-
-# Stop all services
-docker compose down
-
-# View logs
-docker compose logs
-docker compose logs frontend
-```
-
-### **Database Management**
-
-```bash
-# Access CouchDB container
-docker compose exec couchdb bash
-
-# Backup database
-docker compose exec couchdb curl -X GET http://admin:password@localhost:5984/users/_all_docs?include_docs=true
-
-# Restore database
-# Use CouchDB Fauxton interface or curl commands
-```
-
-## 🧪 Testing & Quality Assurance
-
-### **Development Testing**
-
-```bash
-# Run all unit tests
-bun run test
-
-# Run tests in watch mode
-bun run test:watch
-
-# Run with coverage
-bun run test:coverage
-
-# Run integration tests
-bun run test:integration
-
-# Run E2E tests with Playwright
-bun run test:e2e
-
-# Run E2E tests in UI mode
-bun run test:e2e:ui
-
-# Debug E2E tests
-bun run test:e2e:debug
-
-# Run all tests (unit + integration + e2e)
-bun run test:all
-```
-
-### **Testing Structure**
-
-- **Unit Tests**: Jest-based tests for individual functions and components
-- **Integration Tests**: Production environment validation and service testing
-- **E2E Tests**: Playwright-based full user journey testing across browsers
-- **Manual Tests**: Browser console debugging scripts
-
-See [tests/README.md](tests/README.md) for detailed testing documentation.
-
-### **Test Production Environment**
-
-```bash
-# Run comprehensive production tests
-bun test-production.js
-
-# Manual testing checklist
-./deploy.sh                    # Deploy environment
-# Visit http://localhost:8080
-# Test user registration/login
-# Test admin interface
-# Test medication management
-# Test password change
-# Verify data persistence
-```
-
-### **Performance Testing**
-
-```bash
-# Check service health
-docker compose ps
-curl -f http://localhost:5984/_up
-curl -f http://localhost:8080
-
-# Monitor resource usage
-docker stats
-```
-
-### **Security Testing**
-
-```bash
-# Check for vulnerable dependencies
-bun audit
-
-# Validate environment configuration
-./deploy.sh --dry-run
-
-# Test authentication flows
-# - Registration with weak passwords
-# - Login with wrong credentials
-# - Access admin without proper role
-```
-
-## 🚀 Deployment Guide
-
-### **Development Deployment**
-
-```bash
-# Quick local setup
-./setup.sh
-```
-
-### **Production Deployment**
-
-```bash
-# Secure production deployment
-./deploy.sh production
-```
-
-### **Cloud Deployment**
-
-#### **AWS EC2**
-
-```bash
-# 1. Launch EC2 instance with Docker
-# 2. Clone repository
-git clone <repo-url>
-cd meds
-
-# 3. Configure environment
-cp .env.example .env
-# Edit .env with production values
-
-# 4. Deploy
-./deploy.sh production
-```
-
-#### **Google Cloud Run**
-
-```bash
-# Build and push image
-gcloud builds submit --tag gcr.io/PROJECT-ID/meds-app
-
-# Deploy with environment variables
-gcloud run deploy meds-app \
-  --image gcr.io/PROJECT-ID/meds-app \
-  --set-env-vars COUCHDB_URL=your-couchdb-url \
-  --set-env-vars MAILGUN_API_KEY=your-key
-```
-
-#### **Kubernetes (Template-Based)**
-
-For configuration details:
-
-```bash
-# Check current unified configuration
-bun run config
-
-# See all environment variable options
-bun run config:help
-
-# Quick setup
-cp .env.example .env
-# Edit .env with your values (optional - smart defaults provided)
-```
-
-## 🔍 Troubleshooting
-
-### **Common Issues**
-
-#### **Environment Variables Not Loading**
-
-```bash
-# Check .env file exists and is properly formatted
-cat .env
-
-# Verify Docker Compose uses env file
-docker compose config
-```
-
-#### **CouchDB Connection Issues**
-
-```bash
-# Check CouchDB health
-curl -u admin:password http://localhost:5984/_up
-
-# Verify credentials
-docker compose logs couchdb
-
-# Reset database
-docker compose down
-docker volume rm meds_couchdb-data
-docker compose up -d
-```
-
-#### **Frontend Build Failures**
-
-```bash
-# Clear node modules and reinstall
-rm -rf node_modules bun.lockb
-bun install
-
-# Check for TypeScript errors
-bun run type-check
-
-# Build with verbose output
-bun run build --verbose
-```
-
-#### **Email Not Sending**
-
-```bash
-# Verify Mailgun configuration
-echo $MAILGUN_API_KEY
-echo $MAILGUN_DOMAIN
-
-# Check Mailgun service logs
-docker compose logs frontend | grep -i mailgun
-
-# Test Mailgun API directly
-curl -s --user 'api:YOUR_API_KEY' \
-  https://api.mailgun.net/v3/YOUR_DOMAIN/messages \
-  -F from='test@YOUR_DOMAIN' \
-  -F to='you@example.com' \
-  -F subject='Test' \
-  -F text='Testing'
-```
-
-### **Performance Issues**
-
-```bash
-# Check resource usage
-docker stats
-
-# Optimize Docker images
-docker system prune -a
-
-# Monitor application performance
-docker compose logs --tail=100 frontend
-```
-
-### **Debug Mode**
-
-```bash
-# Run with debug logging
-DEBUG=* docker compose up
-
-# Access container for debugging
-docker compose exec frontend sh
-docker compose exec couchdb bash
-```
+For detailed API documentation, see [`docs/development/API.md`](docs/development/API.md).
 
 ## 📚 Documentation
 
@@ -762,80 +369,85 @@ For comprehensive documentation, visit **[`docs/README.md`](docs/README.md)** wh
 #### 🏗️ Architecture & Design
 
 - [Project Structure](docs/architecture/PROJECT_STRUCTURE.md) - Codebase organization
-- [Template Approach](docs/architecture/TEMPLATE_APPROACH.md) - Design philosophy
+- [Template Approach](docs/architecture/TEMPLATE_APPROACH.md) - Configuration philosophy
 
 #### 🚀 Setup & Configuration
 
-- [Complete Template Configuration](docs/setup/COMPLETE_TEMPLATE_CONFIGURATION.md) - Full setup guide
-- [Setup Complete](docs/setup/SETUP_COMPLETE.md) - Post-setup verification
+- [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) - App security practices
+- [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
 
-## 📚 Additional Resources
+## 🔍 Troubleshooting
 
-### **Documentation**
+### **Common Issues**
 
-- [CouchDB Documentation](https://docs.couchdb.org/)
-- [Mailgun API Reference](https://documentation.mailgun.com/)
-- [Docker Compose Reference](https://docs.docker.com/compose/)
-- [React Documentation](https://react.dev/)
+#### **Development Server Won't Start**
 
-### **Development Tools**
+```bash
+# Clear dependencies and reinstall
+rm -rf node_modules bun.lockb
+bun install
 
-- [Bun Documentation](https://bun.sh/docs)
-- [Vite Documentation](https://vitejs.dev/)
-- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
+# Check for TypeScript errors
+bun run type-check
+```
 
-### **Security Resources**
+#### **Mock Database Issues**
 
-- [OWASP Security Guidelines](https://owasp.org/)
-- [Docker Security Best Practices](https://docs.docker.com/engine/security/)
-- [CouchDB Security](https://docs.couchdb.org/en/stable/intro/security.html)
+```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. **Commit changes**: `git commit -m 'Add amazing feature'`
-4. **Push to branch**: `git push origin feature/amazing-feature`
-5. **Open a Pull Request**
+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 Workflow**
+### **Development Guidelines**
 
-```bash
-# Setup development environment
-./setup.sh
+- Follow the existing code style and patterns
+- Add tests for new functionality
+- Update documentation as needed
+- Ensure all quality checks pass
 
-# Make changes and test
-bun run dev
-bun run lint
-bun run type-check
-
-# Test in production environment
-./deploy.sh
-bun test-production.js
-
-# Submit pull request
-```
-
-## 📚 Documentation
-
-### **Project Documentation**
-
-- **[Code Quality Guide](docs/development/CODE_QUALITY.md)** - Code formatting, linting, and pre-commit hooks setup
-- **[Security Guide](docs/development/APPLICATION_SECURITY.md)** - Security best practices and configuration
-- **[API Documentation](docs/development/API.md)** - Complete API reference
-- **[Contributing Guide](CONTRIBUTING.md)** - Development guidelines and contribution process
-- **[License](LICENSE)** - MIT license and third-party attributions
-- **[Changelog](CHANGELOG.md)** - Version history and release notes
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
 
 ## 📄 License
 
@@ -846,11 +458,11 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - **CouchDB Team** for the robust database system
 - **Mailgun** for reliable email delivery
 - **React Team** for the excellent frontend framework
-- **Docker Team** for containerization technology
 - **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.� Documentation
+For support, please open an issue on GitHub or contact the development team.