rxminder/config

Unified Configuration System

This directory contains the unified configuration system for the RxMinder application. The unified config provides a single source of truth for all application settings across different environments and deployment targets.

Overview

The unified configuration system replaces the previous scattered approach of multiple .env files and environment-specific configurations with a centralized, type-safe, and environment-aware system.

Key Benefits

• 🎯 Single Source of Truth: All configuration in one place
• 🔒 Type Safety: Full TypeScript support with interfaces
• 🌍 Environment Aware: Automatic environment-specific overrides
• 🚀 Auto-Generation: Generates all necessary config files automatically
• 🔄 Easy Migration: Smooth transition from old config system
• 📝 Self-Documenting: Clear structure with validation

File Structure

config/
├── README.md                    # This documentation
├── unified.config.ts           # Main unified configuration
├── app.config.ts              # Legacy config (deprecated)
└── generated/                 # Auto-generated configs
    ├── development.config.ts
    ├── staging.config.ts
    └── production.config.ts

Quick Start

1. Using the Unified Config

import { unifiedConfig, isProduction, featureFlags } from './config/unified.config';

// Access configuration
const dbUrl = unifiedConfig.database.url;
const appName = unifiedConfig.app.name;

// Use convenience exports
if (isProduction()) {
  // Production-specific logic
}

if (featureFlags.enableOAuth) {
  // OAuth-enabled logic
}

2. Environment Variables

The system reads from environment variables with fallbacks to sensible defaults:

# Required variables
APP_NAME=RxMinder
NODE_ENV=production
VITE_COUCHDB_URL=http://couchdb:5984

# Optional variables with defaults
APP_VERSION=1.0.0
DEBUG_MODE=false
ENABLE_OAUTH=true

3. Generating Config Files

Generate configuration files for all environments:

# Generate for all environments
make generate-config

# Generate for specific environment
make generate-config-prod

# Validate configuration
make validate-config

# Debug current config
make config-debug

Configuration Structure

Application Settings

app: {
  name: string; // Application name
  version: string; // Version number
  environment: Environment; // Current environment
  baseUrl: string; // Base application URL
  port: number; // Server port
}

Database Configuration

database: {
  url: string; // Database connection URL
  username: string; // Database username
  password: string; // Database password
  name: string; // Database name
  useMock: boolean; // Use mock database for testing
  connectionTimeout: number;
  retryAttempts: number;
}

Kubernetes Configuration

kubernetes: {
  namespace: string; // K8s namespace
  ingressHost: string; // Ingress hostname
  replicas: {
    frontend: number; // Frontend replica count
    database: number; // Database replica count
  }
  resources: {
    frontend: ResourceLimits;
    database: ResourceLimits;
  }
}

Feature Flags

features: {
  enableEmailVerification: boolean;
  enableOAuth: boolean;
  enableAdminInterface: boolean;
  enableMonitoring: boolean;
  debugMode: boolean;
}

Environment Overrides

The system supports environment-specific overrides:

Development

• Debug mode enabled
• Lower resource limits
• Console logging for emails
• Hot reload enabled

Staging

• Monitoring enabled
• Production-like settings
• Staging URLs
• Moderate resource limits

Production

• Security features enabled
• Higher resource limits
• Performance optimizations
• Monitoring and metrics enabled

Environment Variables Reference

Core Application

• APP_NAME - Application name (default: RxMinder)
• APP_VERSION - Version number (default: 1.0.0)
• APP_BASE_URL - Base URL (default: http://localhost:5173)
• NODE_ENV - Environment (development/staging/production/test)

Database

• VITE_COUCHDB_URL - CouchDB URL
• VITE_COUCHDB_USER - CouchDB username
• VITE_COUCHDB_PASSWORD - CouchDB password
• USE_MOCK_DB - Use mock database (default: false)

Container & Deployment

• CONTAINER_REGISTRY - Container registry URL
• CONTAINER_REPOSITORY - Repository name
• CONTAINER_TAG - Container tag
• INGRESS_HOST - Kubernetes ingress host
• STORAGE_CLASS - Kubernetes storage class
• STORAGE_SIZE - Storage size (default: 1Gi)

Email Configuration

• VITE_MAILGUN_API_KEY - Mailgun API key
• VITE_MAILGUN_DOMAIN - Mailgun domain
• VITE_MAILGUN_FROM_NAME - From name (default: RxMinder)
• VITE_MAILGUN_FROM_EMAIL - From email address

OAuth Configuration

• VITE_GOOGLE_CLIENT_ID - Google OAuth client ID
• VITE_GITHUB_CLIENT_ID - GitHub OAuth client ID

Feature Flags

• ENABLE_EMAIL_VERIFICATION - Enable email verification (default: true)
• ENABLE_OAUTH - Enable OAuth (default: true)
• ENABLE_ADMIN_INTERFACE - Enable admin interface (default: true)
• ENABLE_MONITORING - Enable monitoring (default: false)
• DEBUG_MODE - Enable debug mode (default: false)

Security & Performance

• JWT_SECRET - JWT signing secret
• LOG_LEVEL - Logging level (debug/info/warn/error)
• CACHE_TTL - Cache timeout in seconds
• REQUEST_TIMEOUT - Request timeout in milliseconds

Generated Files

The unified config system generates several files:

1. Environment Files

• .env.development - Development environment variables
• .env.staging - Staging environment variables
• .env.production - Production environment variables

2. Kubernetes Configuration

• k8s-kustomize/overlays/{env}/config.env - Kubernetes config for each environment
• k8s-kustomize/overlays/{env}/kustomization.yaml - Updated kustomization files

3. Docker Configuration

• docker/.env.{environment} - Docker-specific environment files

4. Vite Configuration

• .env.vite.{environment} - Vite-specific variables

5. TypeScript Exports

• config/generated/{environment}.config.ts - Type-safe config exports

Scripts

Generation Scripts

# Generate unified configuration
bun scripts/generate-unified-config.ts

# Generate for specific environment
bun scripts/generate-unified-config.ts production

# Generate for all environments
bun scripts/generate-unified-config.ts --all

# Dry run (preview changes)
bun scripts/generate-unified-config.ts --dry-run

# Verbose output
bun scripts/generate-unified-config.ts --verbose

Migration Scripts

# Generate configuration for all environments
bun scripts/generate-unified-config.ts --all

# Generate for specific environment
bun scripts/generate-unified-config.ts production

# Validate configuration
bun scripts/generate-unified-config.ts --dry-run

Migration from Old System

If you're migrating from the old configuration system:

1. Backup Current Configuration

bun scripts/generate-unified-config.ts production

2. Run Migration

bun scripts/generate-unified-config.ts --all

3. Generate New Config Files

make generate-config

4. Test Application

make dev

5. Deploy

make deploy-prod-quick

Best Practices

1. Environment Variables

• Use VITE_ prefix for frontend-accessible variables
• Keep sensitive data in environment variables, not in code
• Use meaningful defaults for non-sensitive configuration

2. Configuration Updates

• Always regenerate config files after changing unified config
• Test configuration changes in development first
• Use the validation features to catch issues early

3. Secrets Management

• Never commit secrets to version control
• Use environment variables for all sensitive data
• Consider using external secret management in production

4. Environment Consistency

• Keep environment-specific overrides minimal
• Document any environment-specific requirements
• Test deployments in staging before production

Troubleshooting

Configuration Not Loading

1. Check that NODE_ENV is set correctly
2. Verify environment variables are accessible
3. Run make config-debug to see current configuration
4. Check for TypeScript compilation errors

Missing Environment Variables

1. Check if variables are defined in .env file
2. Verify variable names match the expected format
3. Use make validate-config to identify missing required variables

Kubernetes Deployment Issues

1. Regenerate Kubernetes configs: make generate-config-prod
2. Check that namespace exists: kubectl get namespaces
3. Verify config maps: kubectl get configmaps -n {namespace}

Build/Runtime Errors

1. Ensure all VITE_ prefixed variables are available at build time
2. Check Vite configuration for proper variable injection
3. Verify TypeScript types are consistent

Development

Adding New Configuration

1. Update the UnifiedConfig interface in unified.config.ts
2. Add default values to defaultConfig
3. Add environment-specific overrides if needed
4. Update environment variable loading in loadFromEnvironment
5. Regenerate configuration files

Adding New Environment

1. Add environment to Environment type
2. Add environment-specific config to environmentConfigs
3. Update generation scripts to handle new environment
4. Create Kubernetes overlay directory structure

Security Considerations

• JWT secrets must be changed in production
• Database passwords should be strong and unique
• API keys should be rotated regularly
• Use HTTPS in production environments
• Enable security headers in production

Performance Considerations

• Cache timeouts should be appropriate for your use case
• Resource limits should match your infrastructure
• Monitor application performance in different environments
• Adjust replica counts based on load requirements

Support

For questions or issues with the unified configuration system:

1. Check this documentation first
2. Run diagnostic commands (make config-debug, make validate-config)
3. Review generated configuration files
4. Check application logs for configuration-related errors

---

This unified configuration system provides a robust, scalable, and maintainable approach to application configuration management.