rxminder/config/README.md

# 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

```typescript
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:

```bash
# 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:

```bash
# 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

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

### Database Configuration

```typescript
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

```typescript
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

```typescript
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

```bash
# 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

```bash
# Migrate from old config system
bun scripts/migrate-to-unified-config.ts

# Migration with backup
bun scripts/migrate-to-unified-config.ts --backup

# Preview migration changes
bun scripts/migrate-to-unified-config.ts --dry-run
```

## Migration from Old System

If you're migrating from the old configuration system:

### 1. Backup Current Configuration

```bash
bun scripts/migrate-to-unified-config.ts --backup
```

### 2. Run Migration

```bash
bun scripts/migrate-to-unified-config.ts
```

### 3. Generate New Config Files

```bash
make generate-config
```

### 4. Test Application

```bash
make dev
```

### 5. Deploy

```bash
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._