# 🎯 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:**
```typescript
// 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:**
```typescript
// 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
```bash
# .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
```html
${APP_NAME}
```
**Processed to:**
```html
MyCustomApp
```
#### Configuration Template
```typescript
// 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
```bash
# .env (development)
VITE_APP_NAME=RxMinder-Dev
VITE_COUCHDB_URL=http://localhost:5984
DEBUG_MODE=true
ENABLE_EMAIL_VERIFICATION=false
```
#### Production Environment
```bash
# .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
```typescript
// 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
```bash
# Copy template
cp .env.example .env
# Customize for your environment
nano .env
# Process templates
bun run predev
```
### 2. Development
```bash
# 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
```bash
# 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.