Files

William Valentin f51bdeb284 docs: refocus architecture docs on current development state

- Update TEMPLATE_APPROACH.md from Kubernetes deployment to development configuration
- Update PROJECT_STRUCTURE.md to reflect current development structure
- Remove references to non-existent deployment artifacts
- Focus on environment-based configuration and template processing
- Document actual current features rather than future deployment scenarios

2025-09-08 21:37:46 -07:00

7.4 KiB

Raw Blame History

🎯 Template-Based Configuration Approach

Overview

RxMinder uses a template-based configuration approach with environment variables to provide flexible, secure, and maintainable configuration management across different environments.

🆚 Configuration Philosophy

❌ Before (Hardcoded Values)

Old approach with hardcoded configuration:

// Hardcoded configuration
const config = {
  appName: 'RxMinder',
  baseUrl: 'http://localhost:5173',
  dbUrl: 'http://localhost:5984',
  adminPassword: 'admin123', // ❌ Security risk
};

Problems:

😣 No environment flexibility
🔧 Configuration changes require code changes
📝 Hard to customize for different deployments
🔒 Security risks with hardcoded credentials

✅ After (Template-Based)

New approach uses environment variables with templates:

// Environment-based configuration
const config = {
  appName: process.env.VITE_APP_NAME || 'RxMinder',
  baseUrl: process.env.VITE_BASE_URL || 'http://localhost:5173',
  dbUrl: process.env.VITE_COUCHDB_URL || 'http://localhost:5984',
  adminPassword: process.env.VITE_COUCHDB_PASSWORD, // ✅ Secure
};

Benefits:

✅ Environment-specific configuration
✅ No hardcoded secrets in code
✅ Easy customization via .env files
✅ Template processing for HTML and other assets
✅ Type-safe configuration with validation

🚀 How It Works

1. Environment Configuration

# .env.example (template for all environments)
VITE_APP_NAME=RxMinder
VITE_BASE_URL=http://localhost:5173
VITE_COUCHDB_URL=http://localhost:5984
VITE_COUCHDB_USER=admin
VITE_COUCHDB_PASSWORD=secure-password-123

# Email configuration (optional)
VITE_MAILGUN_API_KEY=your-mailgun-api-key
VITE_MAILGUN_DOMAIN=your-domain.com

# OAuth configuration (optional)
VITE_GOOGLE_CLIENT_ID=your-google-client-id
VITE_GITHUB_CLIENT_ID=your-github-client-id

# Feature flags
ENABLE_EMAIL_VERIFICATION=true
ENABLE_OAUTH=true
DEBUG_MODE=false

2. Template Processing

HTML Template Processing

<!-- index.html.template -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>${APP_NAME}</title>
    <meta name="description" content="${APP_NAME} - Medication Reminder App" />
  </head>
</html>

Processed to:

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>MyCustomApp</title>
    <meta name="description" content="MyCustomApp - Medication Reminder App" />
  </head>
</html>

Configuration Template

// config/unified.config.ts (centralized configuration)
export const unifiedConfig = {
  app: {
    name: import.meta.env.VITE_APP_NAME || 'RxMinder',
    environment: import.meta.env.NODE_ENV || 'development',
    baseUrl: import.meta.env.VITE_BASE_URL || 'http://localhost:5173',
    version: import.meta.env.VITE_APP_VERSION || '0.0.0',
  },
  database: {
    url: import.meta.env.VITE_COUCHDB_URL || 'http://localhost:5984',
    username: import.meta.env.VITE_COUCHDB_USER || 'admin',
    password: import.meta.env.VITE_COUCHDB_PASSWORD || '',
  },
  features: {
    emailVerification: import.meta.env.ENABLE_EMAIL_VERIFICATION === 'true',
    oauth: import.meta.env.ENABLE_OAUTH === 'true',
    debug: import.meta.env.DEBUG_MODE === 'true',
  },
};

3. Development vs Production

Development Environment

# .env (development)
VITE_APP_NAME=RxMinder-Dev
VITE_COUCHDB_URL=http://localhost:5984
DEBUG_MODE=true
ENABLE_EMAIL_VERIFICATION=false

Production Environment

# .env.production
VITE_APP_NAME=MedicationTracker
VITE_COUCHDB_URL=https://your-couchdb.com
ENABLE_EMAIL_VERIFICATION=true
ENABLE_OAUTH=true
DEBUG_MODE=false

🔧 Template Files in Project

1. HTML Templates

index.html.template - Main HTML entry point with variable substitution
index.html - Generated file (processed by scripts/process-html.sh)

2. Configuration Templates

.env.example - Template for environment configuration
config/unified.config.ts - Centralized configuration with validation

3. Processing Scripts

scripts/process-html.sh - HTML template processing
package.json - Scripts for template processing (predev, prebuild)

🛡️ Security Benefits

Environment Separation

Development: Uses mock data and relaxed security
Production: Requires all security features and real credentials
Clear boundaries between environments

Credential Management

No secrets in code - All sensitive data in environment variables
Environment-specific secrets - Different credentials per environment
Template validation - Ensures required variables are set

Configuration Validation

// Automatic validation in unified.config.ts
if (!unifiedConfig.database.password && unifiedConfig.app.environment === 'production') {
  throw new Error('Database password is required in production');
}

📝 Development Workflow

1. Initial Setup

# Copy template
cp .env.example .env

# Customize for your environment
nano .env

# Process templates
bun run predev

2. Development

# Start with template processing
bun run dev  # Automatically runs predev

# Templates are processed automatically
# HTML title updates based on APP_NAME
# Configuration updates based on environment variables

3. Building

# Production build with template processing
bun run build  # Automatically runs prebuild

# Templates processed for production
# Environment variables baked into build

🎯 Benefits

For Developers

Aspect	Before	After
Setup	Manual file editing	Copy `.env.example`
Customization	Code changes	Environment variables
Testing	Hardcoded test data	Environment-based mocking
Debugging	Console hunting	Centralized debug flags

For Operations

Aspect	Before	After
Deployment	Manual configuration	Environment-based
Security	Hardcoded secrets	External configuration
Monitoring	Scattered settings	Centralized config
Scaling	Per-instance setup	Template replication

🔍 Best Practices

Environment Variable Naming

Use VITE_ prefix for client-side variables
Use descriptive names (VITE_COUCHDB_PASSWORD vs PASSWORD)
Group related variables (VITE_MAILGUN_API_KEY, VITE_MAILGUN_DOMAIN)

Template Organization

Keep templates close to generated files
Use clear naming conventions (.template suffix)
Document all template variables

Validation Strategy

Validate required variables at startup
Provide clear error messages for missing configuration
Use TypeScript for compile-time validation

🚀 Result

The template-based approach makes RxMinder configuration:

More flexible - Easy customization for different environments
More secure - No hardcoded secrets in source code
More maintainable - Centralized configuration management
More scalable - Template-driven deployment processes

This approach follows modern application configuration best practices and provides a solid foundation for development, testing, and future deployment needs.

7.4 KiB Raw Blame History