ai-flow-dev 2.7.0 → 2.8.0

package/templates/fullstack/specs/configuration.template.md

@@ -1,354 +1,354 @@
-# Configuration Specifications
-
-> Environment variables and configuration management for {{PROJECT_NAME}} (Full Stack)
+# Configuration Specifications
+
+> Environment variables and configuration management for {{PROJECT_NAME}} (Full Stack)
 ---
-## 🎯 Configuration Strategy
-
-**Approach:** {{CONFIGURATION_APPROACH}}
-
-**Key Principles:**
-1. **Separation of Concerns** - Backend vs Frontend config
-2. **Security First** - Never expose secrets to client
-3. **Type Safety** - Validate and type all config
-4. **Environment Parity** - Consistent config across environments
+## 🎯 Configuration Strategy
+
+**Approach:** {{CONFIGURATION_APPROACH}}
+
+**Key Principles:**
+1. **Separation of Concerns** - Backend vs Frontend config
+2. **Security First** - Never expose secrets to client
+3. **Type Safety** - Validate and type all config
+4. **Environment Parity** - Consistent config across environments
 ---
-## 📁 Configuration Files Structure
-
-```
-{{PROJECT_NAME}}/
-├── backend/
-│   ├── .env.local              # Local overrides (gitignored)
-│   ├── .env.development        # Development defaults
-│   ├── .env.production          # Production defaults
-│   └── .env.example            # Template for new developers
-├── frontend/
-│   ├── .env.local              # Local overrides (gitignored)
-│   ├── .env.development        # Development defaults
-│   ├── .env.production          # Production defaults
-│   ├── .env.example            # Template for new developers
-│   └── src/
-│       └── config/
-│           ├── index.ts        # Configuration loader
-│           ├── schema.ts       # Validation schema
-│           └── constants.ts    # Static constants
-```
+## 📁 Configuration Files Structure
+
+```
+{{PROJECT_NAME}}/
+├── backend/
+│   ├── .env.local              # Local overrides (gitignored)
+│   ├── .env.development        # Development defaults
+│   ├── .env.production          # Production defaults
+│   └── .env.example            # Template for new developers
+├── frontend/
+│   ├── .env.local              # Local overrides (gitignored)
+│   ├── .env.development        # Development defaults
+│   ├── .env.production          # Production defaults
+│   ├── .env.example            # Template for new developers
+│   └── src/
+│       └── config/
+│           ├── index.ts        # Configuration loader
+│           ├── schema.ts       # Validation schema
+│           └── constants.ts    # Static constants
+```
 ---
-## 🔐 Backend Environment Variables
-
-### Required Variables
-
-{{#EACH BACKEND_REQUIRED_VAR}}
-#### `{{VAR_NAME}}`
-
-**Description:** {{VAR_DESCRIPTION}}
-
-**Type:** {{VAR_TYPE}}
-
-**Example:** `{{VAR_EXAMPLE}}`
-
-{{#IF VAR_VALIDATION}}**Validation:** {{VAR_VALIDATION}}{{/IF}}
-
-{{/EACH}}
-
-### Optional Variables
-
-{{#EACH BACKEND_OPTIONAL_VAR}}
-#### `{{VAR_NAME}}`
-
-**Description:** {{VAR_DESCRIPTION}}
-
-**Type:** {{VAR_TYPE}}
-
-**Default:** `{{VAR_DEFAULT}}`
-
-**Example:** `{{VAR_EXAMPLE}}`
-
-{{/EACH}}
+## 🔐 Backend Environment Variables
+
+### Required Variables
+
+{{#EACH BACKEND_REQUIRED_VAR}}
+#### `{{VAR_NAME}}`
+
+**Description:** {{VAR_DESCRIPTION}}
+
+**Type:** {{VAR_TYPE}}
+
+**Example:** `{{VAR_EXAMPLE}}`
+
+{{#IF VAR_VALIDATION}}**Validation:** {{VAR_VALIDATION}}{{/IF}}
+
+{{/EACH}}
+
+### Optional Variables
+
+{{#EACH BACKEND_OPTIONAL_VAR}}
+#### `{{VAR_NAME}}`
+
+**Description:** {{VAR_DESCRIPTION}}
+
+**Type:** {{VAR_TYPE}}
+
+**Default:** `{{VAR_DEFAULT}}`
+
+**Example:** `{{VAR_EXAMPLE}}`
+
+{{/EACH}}
 ---
-## 🎨 Frontend Environment Variables
-
-### Required Variables
-
-**Format:** `VITE_[CATEGORY]_[NAME]` (or your build tool's prefix)
-
-{{#EACH FRONTEND_REQUIRED_VAR}}
-#### `{{VAR_NAME}}`
-
-**Description:** {{VAR_DESCRIPTION}}
-
-**Type:** {{VAR_TYPE}}
-
-**Example:** `{{VAR_EXAMPLE}}`
-
-{{#IF VAR_VALIDATION}}**Validation:** {{VAR_VALIDATION}}{{/IF}}
-
-{{/EACH}}
-
-### Optional Variables
-
-{{#EACH FRONTEND_OPTIONAL_VAR}}
-#### `{{VAR_NAME}}`
-
-**Description:** {{VAR_DESCRIPTION}}
-
-**Type:** {{VAR_TYPE}}
-
-**Default:** `{{VAR_DEFAULT}}`
-
-**Example:** `{{VAR_EXAMPLE}}`
-
-{{/EACH}}
-
-### Variable Naming Convention (Frontend)
-
-**Format:** `VITE_[CATEGORY]_[NAME]`
-
-**Categories:**
-- `VITE_APP_*` - Application metadata
-- `VITE_API_*` - API endpoints (points to backend)
-- `VITE_AUTH_*` - Authentication config
-- `VITE_FEATURE_*` - Feature flags
-- `VITE_ANALYTICS_*` - Analytics services
-
-**Important:** Only variables prefixed with `VITE_` (or your build tool's prefix) are exposed to the client.
+## 🎨 Frontend Environment Variables
+
+### Required Variables
+
+**Format:** `VITE_[CATEGORY]_[NAME]` (or your build tool's prefix)
+
+{{#EACH FRONTEND_REQUIRED_VAR}}
+#### `{{VAR_NAME}}`
+
+**Description:** {{VAR_DESCRIPTION}}
+
+**Type:** {{VAR_TYPE}}
+
+**Example:** `{{VAR_EXAMPLE}}`
+
+{{#IF VAR_VALIDATION}}**Validation:** {{VAR_VALIDATION}}{{/IF}}
+
+{{/EACH}}
+
+### Optional Variables
+
+{{#EACH FRONTEND_OPTIONAL_VAR}}
+#### `{{VAR_NAME}}`
+
+**Description:** {{VAR_DESCRIPTION}}
+
+**Type:** {{VAR_TYPE}}
+
+**Default:** `{{VAR_DEFAULT}}`
+
+**Example:** `{{VAR_EXAMPLE}}`
+
+{{/EACH}}
+
+### Variable Naming Convention (Frontend)
+
+**Format:** `VITE_[CATEGORY]_[NAME]`
+
+**Categories:**
+- `VITE_APP_*` - Application metadata
+- `VITE_API_*` - API endpoints (points to backend)
+- `VITE_AUTH_*` - Authentication config
+- `VITE_FEATURE_*` - Feature flags
+- `VITE_ANALYTICS_*` - Analytics services
+
+**Important:** Only variables prefixed with `VITE_` (or your build tool's prefix) are exposed to the client.
 ---
-## 🌍 Configuration by Environment
-
-### Development
-
-**Backend (.env.development):**
-```bash
-{{BACKEND_DEV_ENV_CONFIG}}
-```
-
-**Frontend (.env.development):**
-```bash
-{{FRONTEND_DEV_ENV_CONFIG}}
-```
-
-### Staging
-
-**Backend (.env.staging):**
-```bash
-{{BACKEND_STAGING_ENV_CONFIG}}
-```
-
-**Frontend (.env.staging):**
-```bash
-{{FRONTEND_STAGING_ENV_CONFIG}}
-```
-
-### Production
-
-**Backend (.env.production):**
-```bash
-{{BACKEND_PRODUCTION_ENV_CONFIG}}
-```
-
-**Frontend (.env.production):**
-```bash
-{{FRONTEND_PRODUCTION_ENV_CONFIG}}
-```
+## 🌍 Configuration by Environment
+
+### Development
+
+**Backend (.env.development):**
+```bash
+{{BACKEND_DEV_ENV_CONFIG}}
+```
+
+**Frontend (.env.development):**
+```bash
+{{FRONTEND_DEV_ENV_CONFIG}}
+```
+
+### Staging
+
+**Backend (.env.staging):**
+```bash
+{{BACKEND_STAGING_ENV_CONFIG}}
+```
+
+**Frontend (.env.staging):**
+```bash
+{{FRONTEND_STAGING_ENV_CONFIG}}
+```
+
+### Production
+
+**Backend (.env.production):**
+```bash
+{{BACKEND_PRODUCTION_ENV_CONFIG}}
+```
+
+**Frontend (.env.production):**
+```bash
+{{FRONTEND_PRODUCTION_ENV_CONFIG}}
+```
 ---
-## 🔌 External Services
-
-### Backend Services
-
-{{#EACH BACKEND_EXTERNAL_SERVICE}}
-### {{SERVICE_NAME}}
-
-**Purpose:** {{SERVICE_PURPOSE}}
-
-**Configuration:**
-```bash
-{{SERVICE_ENV_VARS}}
-```
-
-**Documentation:** {{SERVICE_DOCS_URL}}
-
-{{#IF SERVICE_FALLBACK}}**Fallback:** {{SERVICE_FALLBACK}}{{/IF}}
-
-{{/EACH}}
-
-### Frontend Services
-
-{{#EACH FRONTEND_EXTERNAL_SERVICE}}
-### {{SERVICE_NAME}}
-
-**Purpose:** {{SERVICE_PURPOSE}}
-
-**Configuration:**
-```bash
-{{SERVICE_ENV_VARS}}
-```
-
-**Documentation:** {{SERVICE_DOCS_URL}}
-
-{{#IF SERVICE_FALLBACK}}**Fallback:** {{SERVICE_FALLBACK}}{{/IF}}
-
-{{/EACH}}
+## 🔌 External Services
+
+### Backend Services
+
+{{#EACH BACKEND_EXTERNAL_SERVICE}}
+### {{SERVICE_NAME}}
+
+**Purpose:** {{SERVICE_PURPOSE}}
+
+**Configuration:**
+```bash
+{{SERVICE_ENV_VARS}}
+```
+
+**Documentation:** {{SERVICE_DOCS_URL}}
+
+{{#IF SERVICE_FALLBACK}}**Fallback:** {{SERVICE_FALLBACK}}{{/IF}}
+
+{{/EACH}}
+
+### Frontend Services
+
+{{#EACH FRONTEND_EXTERNAL_SERVICE}}
+### {{SERVICE_NAME}}
+
+**Purpose:** {{SERVICE_PURPOSE}}
+
+**Configuration:**
+```bash
+{{SERVICE_ENV_VARS}}
+```
+
+**Documentation:** {{SERVICE_DOCS_URL}}
+
+{{#IF SERVICE_FALLBACK}}**Fallback:** {{SERVICE_FALLBACK}}{{/IF}}
+
+{{/EACH}}
 ---
-## 💾 Database Configuration (Backend)
-
-```bash
-{{DATABASE_CONFIG}}
-```
-
-**Connection Pool:**
-- Min: {{DB_POOL_MIN}}
-- Max: {{DB_POOL_MAX}}
-- Idle Timeout: {{DB_IDLE_TIMEOUT}}ms
+## 💾 Database Configuration (Backend)
+
+```bash
+{{DATABASE_CONFIG}}
+```
+
+**Connection Pool:**
+- Min: {{DB_POOL_MIN}}
+- Max: {{DB_POOL_MAX}}
+- Idle Timeout: {{DB_IDLE_TIMEOUT}}ms
 ---
-## 🔐 Secrets Management
-
-### Backend Secrets
-
-**Never commit these variables:**
-
-{{#EACH BACKEND_SECRET_VAR}}
-- `{{VAR_NAME}}` - {{VAR_PURPOSE}}
-{{/EACH}}
-
-**Storage:** {{BACKEND_SECRETS_STORAGE}}
-
-### Frontend Secrets
-
-**Important:** Frontend should NEVER contain secrets. Only public keys and non-sensitive configuration.
-
-**Allowed:**
-- Public API keys (e.g., Google Maps API key)
-- Public service IDs
-- Feature flags
-- Analytics IDs
-
-**Never:**
-- Database credentials
-- API secret keys
-- Authentication secrets
-- Private keys
+## 🔐 Secrets Management
+
+### Backend Secrets
+
+**Never commit these variables:**
+
+{{#EACH BACKEND_SECRET_VAR}}
+- `{{VAR_NAME}}` - {{VAR_PURPOSE}}
+{{/EACH}}
+
+**Storage:** {{BACKEND_SECRETS_STORAGE}}
+
+### Frontend Secrets
+
+**Important:** Frontend should NEVER contain secrets. Only public keys and non-sensitive configuration.
+
+**Allowed:**
+- Public API keys (e.g., Google Maps API key)
+- Public service IDs
+- Feature flags
+- Analytics IDs
+
+**Never:**
+- Database credentials
+- API secret keys
+- Authentication secrets
+- Private keys
 ---
-## 🚩 Feature Flags
-
-### Backend Feature Flags
-
-{{#IF BACKEND_FEATURE_FLAGS}}
-{{#EACH BACKEND_FEATURE_FLAG}}
-### `{{FLAG_NAME}}`
-
-**Description:** {{FLAG_DESCRIPTION}}
-
-**Default:** {{FLAG_DEFAULT}}
-
-**Environments:** {{FLAG_ENVIRONMENTS}}
-
-{{/EACH}}
-
-{{ELSE}}
-Backend feature flags not implemented yet.
-
-{{/IF}}
-
-### Frontend Feature Flags
-
-{{#IF FRONTEND_FEATURE_FLAGS}}
-{{#EACH FRONTEND_FEATURE_FLAG}}
-### `{{FLAG_NAME}}`
-
-**Description:** {{FLAG_DESCRIPTION}}
-
-**Default:** {{FLAG_DEFAULT}}
-
-**Environments:** {{FLAG_ENVIRONMENTS}}
-
-{{/EACH}}
-
-{{ELSE}}
-Frontend feature flags not implemented yet.
-
-{{/IF}}
+## 🚩 Feature Flags
+
+### Backend Feature Flags
+
+{{#IF BACKEND_FEATURE_FLAGS}}
+{{#EACH BACKEND_FEATURE_FLAG}}
+### `{{FLAG_NAME}}`
+
+**Description:** {{FLAG_DESCRIPTION}}
+
+**Default:** {{FLAG_DEFAULT}}
+
+**Environments:** {{FLAG_ENVIRONMENTS}}
+
+{{/EACH}}
+
+{{ELSE}}
+Backend feature flags not implemented yet.
+
+{{/IF}}
+
+### Frontend Feature Flags
+
+{{#IF FRONTEND_FEATURE_FLAGS}}
+{{#EACH FRONTEND_FEATURE_FLAG}}
+### `{{FLAG_NAME}}`
+
+**Description:** {{FLAG_DESCRIPTION}}
+
+**Default:** {{FLAG_DEFAULT}}
+
+**Environments:** {{FLAG_ENVIRONMENTS}}
+
+{{/EACH}}
+
+{{ELSE}}
+Frontend feature flags not implemented yet.
+
+{{/IF}}
 ---
-## 🔒 Security Best Practices
-
-### Backend
-
-- ✅ Store all secrets in environment variables
-- ✅ Use secrets manager for production (AWS Secrets Manager, Azure Key Vault, etc.)
-- ✅ Never log secrets or sensitive data
-- ✅ Rotate secrets regularly
-- ✅ Use different secrets per environment
-
-### Frontend
-
-- ✅ Never expose secrets to client code
-- ✅ Only use public keys and non-sensitive config
-- ✅ Sanitize error messages (don't expose config in production)
-- ✅ Validate all environment variables
-- ✅ Use Content Security Policy headers
-
-### Example: API Key Management
-
-```bash
-# ❌ WRONG - Secret key in frontend
-VITE_STRIPE_SECRET_KEY=sk_live_...
-
-# ✅ CORRECT - Public key in frontend, secret in backend
-# Frontend
-VITE_STRIPE_PUBLISHABLE_KEY=pk_live_...
-
-# Backend
-STRIPE_SECRET_KEY=sk_live_...
-```
+## 🔒 Security Best Practices
+
+### Backend
+
+- ✅ Store all secrets in environment variables
+- ✅ Use secrets manager for production (AWS Secrets Manager, Azure Key Vault, etc.)
+- ✅ Never log secrets or sensitive data
+- ✅ Rotate secrets regularly
+- ✅ Use different secrets per environment
+
+### Frontend
+
+- ✅ Never expose secrets to client code
+- ✅ Only use public keys and non-sensitive config
+- ✅ Sanitize error messages (don't expose config in production)
+- ✅ Validate all environment variables
+- ✅ Use Content Security Policy headers
+
+### Example: API Key Management
+
+```bash
+# ❌ WRONG - Secret key in frontend
+VITE_STRIPE_SECRET_KEY=sk_live_...
+
+# ✅ CORRECT - Public key in frontend, secret in backend
+# Frontend
+VITE_STRIPE_PUBLISHABLE_KEY=pk_live_...
+
+# Backend
+STRIPE_SECRET_KEY=sk_live_...
+```
 ---
-## 🧪 Testing Configuration
-
-### Backend Test Environment
-
-```bash
-# .env.test
-NODE_ENV=test
-DATABASE_URL=postgresql://test:test@localhost:5432/test_db
-LOG_LEVEL=silent
-```
-
-### Frontend Test Environment
-
-```typescript
-// vitest.config.ts
-export default defineConfig({
-  test: {
-    env: {
-      VITE_API_BASE_URL: 'http://localhost:3001/api',
-      VITE_APP_ENV: 'test',
-    },
-  },
-});
-```
+## 🧪 Testing Configuration
+
+### Backend Test Environment
+
+```bash
+# .env.test
+NODE_ENV=test
+DATABASE_URL=postgresql://test:test@localhost:5432/test_db
+LOG_LEVEL=silent
+```
+
+### Frontend Test Environment
+
+```typescript
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    env: {
+      VITE_API_BASE_URL: 'http://localhost:3001/api',
+      VITE_APP_ENV: 'test',
+    },
+  },
+});
+```
 ---
-## 📊 Configuration Monitoring
-
-### Backend
-
-- Log configuration on startup (development only)
-- Monitor secret rotation
-- Track configuration changes
-
-### Frontend
-
-- Log config on startup (development only)
-- Monitor API endpoint availability
-- Track feature flag usage
+## 📊 Configuration Monitoring
+
+### Backend
+
+- Log configuration on startup (development only)
+- Monitor secret rotation
+- Track configuration changes
+
+### Frontend
+
+- Log config on startup (development only)
+- Monitor API endpoint availability
+- Track feature flag usage
 ---
-## 🔗 Related Documents
-
-- [AI Instructions](../ai-instructions.md) - Configuration rules
-- [Security Specification](security.md) - Security requirements
-- [Deployment Guide](../docs/operations.md) - Environment setup
+## 🔗 Related Documents
+
+- [AI Instructions](../ai-instructions.md) - Configuration rules
+- [Security Specification](security.md) - Security requirements
+- [Deployment Guide](../docs/operations.md) - Environment setup
 ---
-**Document Version:** 1.0
-
-**Last Updated:** {{GENERATION_DATE}}
-
-**Generated by:** AI Flow v1.3.0
-
-
-
+**Document Version:** 1.0
+
+**Last Updated:** {{GENERATION_DATE}}
+
+**Generated by:** AI Flow v1.3.0
+
+
+