Add comprehensive environment configuration with validation for backend server

.gitignore

@@ -52,6 +52,10 @@ node_modules/
 .env.production
 .env.test
 
+# Don't ignore example environment files
+!.env.example
+!backend/.env.example
+
 # API Keys and Authentication
 *.key
 *.pem

README.md

@@ -319,6 +319,21 @@ npm start
 npm run monitoring:start
 ```
 
+#### Backend Server Configuration
+
+For detailed backend environment configuration, including API keys, rate limiting, database settings, and security options, see:
+
+📄 **[Backend Configuration Guide](backend/docs/CONFIGURATION.md)**
+
+Quick backend setup:
+```bash
+cd backend
+cp .env.example .env
+# Edit .env with your configuration
+npm install
+npm start
+```
+
 ### Your First Production Agent Swarm
 ```typescript
 // production-deployment.ts

backend/.env.example

@@ -1,14 +1,290 @@
-# Gemini Flow Backend Environment Variables
+# =============================================================================
+# Gemini Flow Backend Environment Configuration
+# =============================================================================
+# Copy this file to .env and customize for your environment
+# 
+# Security Notice:
+# - Never commit .env files to version control
+# - Use strong, randomly generated keys for production
+# - Rotate API keys periodically
+# - Store production secrets in secure vaults (AWS Secrets Manager, HashiCorp Vault)
+# =============================================================================
 
-# Google Gemini API Key (required)
+# =============================================================================
+# REQUIRED IN PRODUCTION
+# =============================================================================
+
+# Node environment (development, production, test)
+# Affects error reporting, logging verbosity, and security settings
+NODE_ENV=development
+
+# Google Gemini API Key (REQUIRED)
 # Get your API key from: https://makersuite.google.com/app/apikey
+# Alternative names: GOOGLE_AI_API_KEY (both are checked)
+# Security: Use different keys for dev/staging/prod environments
 GEMINI_API_KEY=your_gemini_api_key_here
 
-# Alternative API key name (optional)
-GOOGLE_AI_API_KEY=your_google_ai_api_key_here
+# API Key for authentication (REQUIRED in production)
+# Generate with: openssl rand -hex 32
+# Minimum 32 characters recommended for security
+# Used for authenticating backend API requests
+API_KEY=your-secure-random-key-minimum-32-characters-recommended-64
 
-# Server Configuration
+# =============================================================================
+# SERVER CONFIGURATION
+# =============================================================================
+
+# Port for backend HTTP server
+# Default: 3001
+# Production: Use reverse proxy (nginx) to expose on standard ports
 PORT=3001
 
-# CORS Origins (for development)
-CORS_ORIGINS=http://localhost:5173,http://localhost:3000
+# Host to bind to
+# 0.0.0.0 = all network interfaces (Docker, cloud deployments)
+# 127.0.0.1 = localhost only (local development)
+# Default: 0.0.0.0
+HOST=0.0.0.0
+
+# CORS allowed origins (comma-separated)
+# Development: Include local dev servers
+# Production: Restrict to your actual domain(s)
+# Default: http://localhost:5173,http://localhost:3000
+CORS_ORIGINS=http://localhost:5173,http://localhost:3000
+
+# Enable credentials in CORS (true/false)
+# Set to true if your frontend needs to send cookies or auth headers
+CORS_CREDENTIALS=true
+
+# =============================================================================
+# LOGGING CONFIGURATION
+# =============================================================================
+
+# Log level (debug, info, warn, error)
+# Development: debug or info
+# Production: warn or error
+# Default: info
+LOG_LEVEL=info
+
+# Enable pretty logging in development (true/false)
+# Pretty logs are easier to read but slower
+# Use false (JSON format) in production for log aggregation
+LOG_PRETTY=true
+
+# Structured logging format (json, pretty)
+# json = machine-readable for log aggregation (Datadog, ELK)
+# pretty = human-readable for development
+LOG_FORMAT=pretty
+
+# =============================================================================
+# RATE LIMITING
+# =============================================================================
+
+# Time window in milliseconds for rate limiting
+# 60000 = 1 minute
+# Default: 60000
+RATE_LIMIT_WINDOW_MS=60000
+
+# Maximum number of requests per window
+# Development: 100 (permissive for testing)
+# Production: 1000 or higher based on load
+# Default: 100
+RATE_LIMIT_MAX_REQUESTS=100
+
+# Rate limit storage (memory, redis)
+# memory = in-process (single server only)
+# redis = distributed (required for multi-server deployments)
+# Default: memory
+RATE_LIMIT_STORE=memory
+
+# =============================================================================
+# DATABASE CONFIGURATION
+# =============================================================================
+
+# Directory for database files
+# Relative paths resolve from project root
+# Absolute paths are recommended for production
+# Default: .data
+DATA_DIR=.data
+
+# Backup configuration
+# Backup interval in hours (0 to disable automatic backups)
+# Default: 24
+BACKUP_INTERVAL_HOURS=24
+
+# Maximum number of backups to retain
+# Older backups are automatically deleted
+# Default: 30
+MAX_BACKUPS=30
+
+# Database file path (SQLite)
+# Leave empty to use DATA_DIR/database.db
+# DB_PATH=/path/to/database.db
+
+# =============================================================================
+# WORKFLOW & STORE LIMITS
+# =============================================================================
+
+# Maximum number of nodes per workflow
+# Prevents resource exhaustion from overly complex workflows
+# Default: 1000
+MAX_NODES=1000
+
+# Maximum number of edges per workflow
+# Default: 5000
+MAX_EDGES=5000
+
+# Maximum workflow name length
+# Default: 200
+MAX_NAME_LENGTH=200
+
+# Maximum workflow description length
+# Default: 5000
+MAX_DESCRIPTION_LENGTH=5000
+
+# =============================================================================
+# REDIS CONFIGURATION (Optional - for distributed systems)
+# =============================================================================
+
+# Redis host for rate limiting and caching
+# Leave empty to use in-memory storage
+# Production: Use Redis for horizontal scaling
+# REDIS_HOST=localhost
+
+# Redis port
+# Default: 6379
+# REDIS_PORT=6379
+
+# Redis password (if authentication is enabled)
+# REDIS_PASSWORD=your-redis-password
+
+# Redis database number (0-15)
+# Use different databases for dev/staging/prod
+# REDIS_DB=0
+
+# Redis connection timeout (milliseconds)
+# REDIS_CONNECT_TIMEOUT=10000
+
+# =============================================================================
+# MULTIPLE API KEYS (Optional - advanced configuration)
+# =============================================================================
+
+# Support for multiple API keys with different scopes
+# Uncomment to enable multi-key authentication
+
+# Admin key (full access to all endpoints)
+# API_KEY_ADMIN=admin-key-with-full-access
+
+# TUI client key (terminal user interface)
+# API_KEY_TUI=tui-client-key
+
+# Browser client key (web frontend)
+# API_KEY_BROWSER=browser-client-key
+
+# Read-only key (monitoring and reporting)
+# API_KEY_READONLY=readonly-key-for-monitoring
+
+# =============================================================================
+# MONITORING & OBSERVABILITY (Optional)
+# =============================================================================
+
+# Enable Prometheus metrics endpoint
+# Exposes metrics at /metrics endpoint
+# METRICS_ENABLED=true
+
+# Metrics port (separate from main application port)
+# METRICS_PORT=9090
+
+# Enable health check endpoints
+# Provides /health and /ready endpoints
+# Default: true
+HEALTH_CHECK_ENABLED=true
+
+# Enable request logging
+# Logs all HTTP requests (useful for debugging)
+# Default: true
+REQUEST_LOGGING=true
+
+# =============================================================================
+# SECURITY HEADERS (Optional)
+# =============================================================================
+
+# Enable HTTPS redirect
+# Forces all HTTP requests to redirect to HTTPS
+# Only enable if behind a reverse proxy with SSL termination
+# FORCE_HTTPS=false
+
+# Enable security headers (Helmet.js)
+# Adds various security headers to responses
+# SECURITY_HEADERS=true
+
+# Content Security Policy
+# Restricts resource loading to prevent XSS attacks
+# CSP_DIRECTIVES=default-src 'self'; script-src 'self' 'unsafe-inline'
+
+# =============================================================================
+# DEVELOPMENT SETTINGS
+# =============================================================================
+
+# Enable debug mode (additional logging, error details in responses)
+# NEVER enable in production (exposes stack traces)
+# DEBUG=false
+
+# Disable authentication (DANGEROUS - development only)
+# Allows API access without API key validation
+# NEVER enable in production
+# DISABLE_AUTH=false
+
+# Enable hot reload
+# Automatically restart server on file changes
+# Development only
+# HOT_RELOAD=true
+
+# Mock external APIs (development/testing)
+# Replace real API calls with mock responses
+# MOCK_APIS=false
+
+# =============================================================================
+# EXAMPLE CONFIGURATIONS
+# =============================================================================
+
+# Development Example:
+# --------------------
+# NODE_ENV=development
+# GEMINI_API_KEY=your_dev_gemini_key
+# API_KEY=dev-key-for-local-testing
+# PORT=3001
+# HOST=127.0.0.1
+# LOG_LEVEL=debug
+# LOG_PRETTY=true
+# CORS_ORIGINS=http://localhost:5173,http://localhost:3000
+# DISABLE_AUTH=true
+# DEBUG=true
+
+# Production Example:
+# -------------------
+# NODE_ENV=production
+# GEMINI_API_KEY=your_production_gemini_key
+# API_KEY=$(openssl rand -hex 32)
+# PORT=3001
+# HOST=0.0.0.0
+# LOG_LEVEL=warn
+# LOG_FORMAT=json
+# RATE_LIMIT_MAX_REQUESTS=1000
+# RATE_LIMIT_STORE=redis
+# REDIS_HOST=redis.example.com
+# REDIS_PASSWORD=secure-redis-password
+# SECURITY_HEADERS=true
+# FORCE_HTTPS=true
+# METRICS_ENABLED=true
+
+# Docker Example:
+# ---------------
+# NODE_ENV=production
+# GEMINI_API_KEY=${DOCKER_SECRET_GEMINI_KEY}
+# API_KEY=${DOCKER_SECRET_API_KEY}
+# PORT=3001
+# HOST=0.0.0.0
+# DATA_DIR=/data
+# LOG_FORMAT=json
+# REDIS_HOST=redis
+# REDIS_PORT=6379