.env.example

# ═════════════════════════════════════════════════════════════════════════════
# TeachLink Backend - Environment Variables Configuration
# ═════════════════════════════════════════════════════════════════════════════
#
# This file is a template for environment variables. Copy to .env and configure
# for your deployment.
#
# IMPORTANT SECURITY NOTES:
#   ⚠️  NEVER commit the .env file to version control
#   ⚠️  Use AWS Secrets Manager or HashiCorp Vault in production
#   ⚠️  Change all default/placeholder values
#   ⚠️  Use strong, random values for secrets (min 32 characters)
#
# For detailed documentation on each variable, see: ENV_VARS_DOCUMENTATION.md
# For validation: npm run validate:env
# ═════════════════════════════════════════════════════════════════════════════

# ─────────────────────────────────────────────────────────────────────────────
# 1. CORE APPLICATION
# ─────────────────────────────────────────────────────────────────────────────

# Environment: development | production | staging | test
NODE_ENV=development

# Application port (1-65535)
PORT=3000

# Public application URL (used for links, redirects, emails)
APP_URL=http://localhost:3000

# Service name for logging/monitoring
SERVICE_NAME=teachlink-backend

# OpenTelemetry Jaeger tracing configuration
JAEGER_AGENT_HOST=localhost
JAEGER_AGENT_PORT=6831

# Graceful shutdown timeout in milliseconds (default: 30000 = 30s)
SHUTDOWN_TIMEOUT_MS=30000

# Enable cluster mode for multi-worker deployment (true|false)
CLUSTER_MODE=false

# Number of worker processes (when CLUSTER_MODE=true)
CLUSTER_WORKERS=4

# ─────────────────────────────────────────────────────────────────────────────
# 2. DATABASE CONFIGURATION (PostgreSQL)
# ─────────────────────────────────────────────────────────────────────────────
# REQUIRED: Primary database connection

# Primary database host [REQUIRED]
DATABASE_HOST=localhost

# Primary database port [REQUIRED]
DATABASE_PORT=5432

# PostgreSQL username [REQUIRED]
DATABASE_USER=postgres

# PostgreSQL password [REQUIRED]
DATABASE_PASSWORD=postgres

# Database name [REQUIRED]
DATABASE_NAME=teachlink

# Connection pool configuration
DATABASE_POOL_MAX=30        # Max connections (default: 30, high traffic: 50-100)
DATABASE_POOL_MIN=5         # Min pre-allocated connections (default: 5)
DATABASE_POOL_ACQUIRE_TIMEOUT_MS=10000     # Timeout to get connection (default: 10000ms)
DATABASE_POOL_IDLE_TIMEOUT_MS=30000        # Close idle connections after (default: 30000ms)
DATABASE_POOL_LEAK_THRESHOLD_MS=60000      # Warn if connection held longer (default: 60000ms)

# Read replicas (optional)
DATABASE_REPLICA_HOSTS=replica-1.local,replica-2.local,replica-3.local
DATABASE_REPLICA_PORT=5432
DATABASE_REPLICA_USER=
DATABASE_REPLICA_PASSWORD=
DATABASE_REPLICA_NAME=

# Database shutdown configuration
DB_DRAIN_TIMEOUT_MS=15000   # Grace period before force-close (default: 15000ms)
DB_FORCE_CLOSE_TIMEOUT_MS=5000  # Hard timeout (default: 5000ms)
DB_WAIT_FOR_QUERIES=true    # Wait for active queries to complete

# ─────────────────────────────────────────────────────────────────────────────
# 3. AUTHENTICATION & SECURITY
# ─────────────────────────────────────────────────────────────────────────────
# REQUIRED: JWT secrets and encryption

# ── JWT Signing ─────────────────────────────────────────────────────────────
# Choose ONE of the following signing methods:
#
# Option A: HS256 (symmetric) — set JWT_SECRET
#   JWT_SECRET=your-super-secret-jwt-key-change-this-in-production-min-10-chars
#
# Option B: RS256 (asymmetric) — set JWT_PRIVATE_KEY + JWT_PUBLIC_KEY
#   JWT_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----
#   JWT_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----
#
# PEM values can be provided inline or as file paths to .pem files.

# HS256 signing secret [REQUIRED if JWT_PRIVATE_KEY is not set, min 32 chars recommended]
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production-min-10-chars

# RS256 PEM private key (inline content or file path). Overrides JWT_SECRET when set.
JWT_PRIVATE_KEY=

# RS256 PEM public key (inline content or file path). Required when JWT_PRIVATE_KEY is set.
JWT_PUBLIC_KEY=

# Multiple JWT secrets for key rotation (comma-separated, first is current)
JWT_SECRETS=

# JWT secret version (when using JWT_SECRETS)
JWT_SECRET_CURRENT_VERSION=

# JWT token expiration time
JWT_EXPIRES_IN=15m

# Refresh token secret [REQUIRED, min 32 chars recommended]
JWT_REFRESH_SECRET=your-super-secret-refresh-key-change-this-in-production

# Refresh token expiration time
# IMPORTANT: JWT_REFRESH_EXPIRES_IN should be <= AUTH_SESSION_TTL_SECONDS.
# A startup warning will be logged if the session TTL is shorter than this value.
JWT_REFRESH_EXPIRES_IN=7d

# Encryption secret [REQUIRED, min 32 characters]
ENCRYPTION_SECRET=your-super-secret-32-char-encryption-key-change-this

# Encryption salt for scrypt KDF [REQUIRED, randomly generated, store separately from secret]
# Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
ENCRYPTION_SALT=your-random-hex-salt-change-this-in-production

# Bcrypt password hashing rounds (4-15, default: 10, production: 12)
BCRYPT_ROUNDS=10

# Auth0 configuration (optional)
AUTH0_AUDIENCE=
AUTH0_ISSUER_URL=

# ─────────────────────────────────────────────────────────────────────────────
# 4. REDIS (Caching & Job Queue)
# ─────────────────────────────────────────────────────────────────────────────
# REQUIRED: Redis connection

# Redis host [REQUIRED]
REDIS_HOST=localhost

# Redis port [REQUIRED]
REDIS_PORT=6379

# Full Redis URL (alternative to REDIS_HOST/PORT)
# Format: redis://[user:password@]host:port[/db]
REDIS_URL=

# Separate Redis URL for Bull job queue (uses different DB)
QUEUE_REDIS_URL=

# ─────────────────────────────────────────────────────────────────────────────
# 5. EMAIL & SMTP
# ─────────────────────────────────────────────────────────────────────────────
# REQUIRED: SMTP configuration for email delivery

# SMTP server host [REQUIRED]
# Examples: smtp.mailtrap.io (dev), smtp.sendgrid.net (prod), localhost (local)
SMTP_HOST=smtp.mailtrap.io

# SMTP port [REQUIRED]
# Common: 25 (unencrypted), 587 (STARTTLS), 465 (SSL/implicit TLS)
SMTP_PORT=587

# Use SSL/TLS for SMTP connection (true|false)
SMTP_SECURE=false

# SMTP username [REQUIRED]
SMTP_USER=your_smtp_user

# SMTP password [REQUIRED]
SMTP_PASS=your_smtp_password

# Default from email address [REQUIRED, valid email format]
EMAIL_FROM=noreply@teachlink.io

# Display name for from address
EMAIL_FROM_NAME=TeachLink

# SendGrid API key [REQUIRED]
SENDGRID_API_KEY=your_sendgrid_api_key

# SendGrid health check endpoint
SENDGRID_HEALTH_URL=https://api.sendgrid.com/v3/health

# ─────────────────────────────────────────────────────────────────────────────
# 6. STRIPE PAYMENT PROCESSING
# ─────────────────────────────────────────────────────────────────────────────
# REQUIRED: Stripe configuration (if ENABLE_PAYMENTS=true)

# Stripe secret key [REQUIRED if payments enabled]
# Dev: sk_test_..., Prod: sk_live_...
STRIPE_SECRET_KEY=your_stripe_secret_key

# Stripe webhook signing secret [REQUIRED if payments enabled]
STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret

# Stripe health check endpoint
STRIPE_HEALTH_URL=https://api.stripe.com/v1/balance

# ─────────────────────────────────────────────────────────────────────────────
# 7. AWS CONFIGURATION
# ─────────────────────────────────────────────────────────────────────────────
# REQUIRED: AWS credentials and configuration

# AWS access key ID [REQUIRED]
# Note: Use IAM role in production instead of keys
AWS_ACCESS_KEY_ID=your_aws_access_key

# AWS secret access key [REQUIRED]
AWS_SECRET_ACCESS_KEY=your_aws_secret_key

# AWS region (default: us-east-1)
AWS_REGION=us-east-1

# S3 bucket for file storage [REQUIRED]
AWS_S3_BUCKET=your-s3-bucket-name

# Alternative S3 bucket name
AWS_S3_BUCKET_NAME=

# Secondary S3 bucket (for backups/replicas)
AWS_S3_BUCKET_SECONDARY=

# KMS key for S3 encryption (optional, ARN or alias)
AWS_KMS_KEY_ID=

# CloudFront distribution ID (for CDN cache invalidation)
AWS_CLOUDFRONT_DISTRIBUTION_ID=

# SQS queue URL for notifications (optional)
AWS_SQS_NOTIFICATION_QUEUE_URL=https://sqs.us-east-1.amazonaws.com/your-account-id/teachlink-notifications-dev

# SNS topic ARN for notifications (optional)
AWS_SNS_NOTIFICATION_TOPIC_ARN=arn:aws:sns:us-east-1:your-account-id:teachlink-notifications-dev

# AWS health check endpoint
AWS_HEALTH_URL=https://sts.amazonaws.com

# ─────────────────────────────────────────────────────────────────────────────
# 8. SESSION MANAGEMENT
# ─────────────────────────────────────────────────────────────────────────────
# REQUIRED: Session configuration

# Session encryption secret [REQUIRED, min 32 chars recommended]
SESSION_SECRET=your-session-secret-min-10-chars

# Session cookie name
SESSION_COOKIE_NAME=teachlink.sid

# Redis key prefix for sessions
SESSION_PREFIX=sess:

# Session time-to-live in seconds (default: 604800 = 7 days)
# NOTE: The session service reads AUTH_SESSION_TTL_SECONDS. Both should be set identically.
# IMPORTANT: This value should be >= the JWT refresh token lifetime (JWT_REFRESH_EXPIRES_IN).
# If the session TTL is shorter than the refresh token lifetime, sessions may expire while
# refresh tokens are still valid, causing authentication state inconsistencies.
# A startup warning will be logged if this misalignment is detected.
SESSION_TTL_SECONDS=604800

# Auth session TTL (used by SessionService, should match SESSION_TTL_SECONDS)
AUTH_SESSION_TTL_SECONDS=604800

# Browser cookie max age in milliseconds (should match SESSION_TTL_SECONDS)
SESSION_COOKIE_MAX_AGE_MS=604800000

# Distributed lock timeout for session updates
SESSION_LOCK_TTL_MS=5000

# Max retries for acquiring session lock
SESSION_LOCK_MAX_RETRIES=5

# Delay between lock retry attempts (milliseconds)
SESSION_LOCK_RETRY_DELAY_MS=120

# Require sticky sessions in load balancing (true|false)
# Set to false only with distributed session store
STICKY_SESSIONS_REQUIRED=true

# Trust proxy headers (X-Forwarded-*) - enable behind reverse proxy
TRUST_PROXY=true

# ─────────────────────────────────────────────────────────────────────────────
# 9. MONITORING & OBSERVABILITY
# ─────────────────────────────────────────────────────────────────────────────

# Elasticsearch endpoint for log aggregation (optional, logs to stdout if unset)
ELASTICSEARCH_NODE=http://localhost:9200

# Elasticsearch authentication (basic auth, optional)
ELASTICSEARCH_USERNAME=
ELASTICSEARCH_PASSWORD=

# Elasticsearch API key (preferred over basic auth for cloud)
ELASTICSEARCH_API_KEY=

# CA fingerprint for self-signed TLS certificates
ELASTICSEARCH_CA_FINGERPRINT=

# Elasticsearch request timeout
ELASTICSEARCH_REQUEST_TIMEOUT=30000

# Max retries for Elasticsearch requests
ELASTICSEARCH_MAX_RETRIES=3

# Kibana URL for log dashboard links
KIBANA_URL=http://localhost:5601

# ─────────────────────────────────────────────────────────────────────────────
# 10. METRICS & PROMETHEUS
# ─────────────────────────────────────────────────────────────────────────────

# Enable Prometheus metrics endpoint (/metrics)
METRICS_ENABLED=true

# Path for metrics endpoint
METRICS_PATH=/metrics

# Optional bearer token for /metrics access (leave blank for internal networks)
METRICS_AUTH_TOKEN=

# ─────────────────────────────────────────────────────────────────────────────
# 11. ALERTS & NOTIFICATIONS
# ─────────────────────────────────────────────────────────────────────────────

# Email addresses for alert notifications (comma-separated)
ALERT_EMAIL_RECIPIENTS=ops@teachlink.io,oncall@teachlink.io

# Slack webhook URL for alert notifications
ALERT_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK

# General Slack webhook URL
SLACK_WEBHOOK_URL=your_webhook_url_here

# PagerDuty integration key (optional)
PAGERDUTY_INTEGRATION_KEY=

# ─────────────────────────────────────────────────────────────────────────────
# 12. CORS & APPLICATION CONFIGURATION
# ─────────────────────────────────────────────────────────────────────────────

# Allowed origins for CORS requests (comma-separated)
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:4000

# Request body size limit (with unit: b, kb, mb, gb)
REQUEST_BODY_LIMIT=1mb

# Max file upload size (in bytes, default: 10MB)
FILE_UPLOAD_MAX_BYTES=10485760

# Max WebSocket message payload size (in bytes, default: 65536 = 64KB)
# Applies to both Socket.IO transport level and application-level validation
WS_MAX_PAYLOAD_BYTES=65536

# HTTP request timeout (milliseconds)
REQUEST_TIMEOUT=30000

# Database query timeout (milliseconds)
DATABASE_TIMEOUT=

# ─────────────────────────────────────────────────────────────────────────────
# 13. GRAPHQL CONFIGURATION (if ENABLE_GRAPHQL=true)
# ─────────────────────────────────────────────────────────────────────────────

# Max GraphQL query depth
GRAPHQL_MAX_DEPTH=10

# Max GraphQL query complexity
GRAPHQL_MAX_COMPLEXITY=1000

# Complexity multiplier for list fields
GRAPHQL_LIST_MULTIPLIER=10

# ─────────────────────────────────────────────────────────────────────────────
# 14. RATE LIMITING
# ─────────────────────────────────────────────────────────────────────────────

# Rate limit window in seconds (default: 60)
THROTTLE_TTL=60

# Max requests per THROTTLE_TTL window (default: 10)
THROTTLE_LIMIT=10

# ─────────────────────────────────────────────────────────────────────────────
# 15. INTERNATIONALIZATION (i18n/LOCALIZATION)
# ─────────────────────────────────────────────────────────────────────────────

# Default language locale
I18N_DEFAULT_LOCALE=en

# Supported locales (comma-separated)
I18N_SUPPORTED_LOCALES=en

# Cache TTL for translation strings (seconds)
I18N_CACHE_TTL_SECONDS=300

# ─────────────────────────────────────────────────────────────────────────────
# 16. SECRETS MANAGEMENT
# ─────────────────────────────────────────────────────────────────────────────

# Secrets provider: env | aws | vault
SECRET_PROVIDER=env

# Cache TTL for secrets retrieved from manager (milliseconds)
SECRET_CACHE_TTL_MS=300000

# Secrets to rotate (comma-separated names)
SECRETS_TO_ROTATE=JWT_SECRET,DATABASE_PASSWORD,STRIPE_SECRET_KEY

# HashiCorp Vault configuration (when SECRET_PROVIDER=vault)
VAULT_ADDR=https://vault.example.com:8200
VAULT_TOKEN=your-vault-token
VAULT_SECRET_PATH=secret/data

# ─────────────────────────────────────────────────────────────────────────────
# 17. ADVANCED DATABASE CONFIGURATION
# ─────────────────────────────────────────────────────────────────────────────

# Enable automatic index optimization
INDEX_OPT_ENABLED=false

# Run index optimization in dry-run mode (no changes)
INDEX_OPT_DRY_RUN=true

# Auto-create missing indexes
INDEX_OPT_AUTO_CREATE=false

# Auto-drop unused indexes
INDEX_OPT_AUTO_DROP_STALE=false

# Threshold for sequential scans to trigger optimization
INDEX_OPT_SEQ_SCAN_THRESHOLD=1000

# Slow query threshold (milliseconds)
INDEX_OPT_SLOW_QUERY_MS=200

# Database schema for optimization
INDEX_OPT_SCHEMA=public

# ─────────────────────────────────────────────────────────────────────────────
# 18. DATABASE SHARDING (#602)
# ─────────────────────────────────────────────────────────────────────────────
# Set SHARD_COUNT=0 (default) for single database mode
# Set SHARD_COUNT>0 to enable multi-shard routing

# Number of database shards (0 = single shard/fallback mode)
SHARD_COUNT=0

# Rebalance thresholds when utilization high/low (percentage)
SHARD_REBALANCE_HIGH_WATERMARK=80
SHARD_REBALANCE_LOW_WATERMARK=20

# Records per batch during shard rebalancing
SHARD_REBALANCE_BATCH_SIZE=500

# ─────────────────────────────────────────────────────────────────────────────
# 19. CIRCUIT BREAKER CONFIGURATION
# ─────────────────────────────────────────────────────────────────────────────

# Timeout for circuit breaker calls (milliseconds)
CIRCUIT_BREAKER_TIMEOUT_MS=3000

# Error % threshold to open circuit (1-100)
CIRCUIT_BREAKER_ERROR_THRESHOLD=50

# Time before attempting to reset opened circuit (milliseconds)
CIRCUIT_BREAKER_RESET_TIMEOUT_MS=30000

# Rolling window size for error tracking (milliseconds)
CIRCUIT_BREAKER_ROLLING_COUNT_TIMEOUT=60000

# Number of buckets in rolling window
CIRCUIT_BREAKER_ROLLING_COUNT_BUCKETS=10

# ─────────────────────────────────────────────────────────────────────────────
# 20. IDEMPOTENCY CONFIGURATION
# ─────────────────────────────────────────────────────────────────────────────

# Cache TTL for idempotency keys (seconds, default: 86400 = 24 hours)
IDEMPOTENCY_TTL_SECONDS=86400

# ─────────────────────────────────────────────────────────────────────────────
# 21. ANALYTICS
# ─────────────────────────────────────────────────────────────────────────────

# Segment write key (for analytics, optional)
SEGMENT_WRITE_KEY=

# Audit log retention period in days (default: 730 = 2 years)
AUDIT_LOG_RETENTION_DAYS=730

# Analytics event retention period in days (default: 365 = 1 year)
ANALYTICS_RETENTION_DAYS=365

# ─────────────────────────────────────────────────────────────────────────────
# 22. CDN CONFIGURATION
# ─────────────────────────────────────────────────────────────────────────────

# Enable CDN for static assets (true|false)
CDN_ENABLED=false

# CDN domain (required if CDN_ENABLED=true)
CDN_DOMAIN=

# Cache duration for immutable assets (seconds, default: 31536000 = 1 year)
CDN_IMMUTABLE_MAX_AGE=31536000

# Cache duration for HTML files (seconds, default: 300 = 5 minutes)
CDN_HTML_MAX_AGE=300

# Stale-While-Revalidate duration (seconds)
CDN_SWR=60

# ─────────────────────────────────────────────────────────────────────────────
# 23. FEATURE FLAGS - Module Loading Configuration
# ─────────────────────────────────────────────────────────────────────────────
# Set to 'false' to disable loading of specific modules at startup
# This reduces memory footprint and improves startup time
# Core features (recommended to keep enabled)

ENABLE_AUTH=true
ENABLE_SESSION_MANAGEMENT=true

# Payment & Commerce
ENABLE_PAYMENTS=true
ENABLE_STRIPE=true

# Analytics & Testing
ENABLE_AB_TESTING=false
ENABLE_DATA_WAREHOUSE=false

# Collaboration & Content
ENABLE_COLLABORATION=true
ENABLE_MEDIA_PROCESSING=true
ENABLE_MODERATION=true

# Data Management
ENABLE_BACKUP=true
ENABLE_SYNC=true
ENABLE_MIGRATIONS=true

# APIs & GraphQL
ENABLE_GRAPHQL=false
ENABLE_SEARCH=true

# Infrastructure
ENABLE_RATE_LIMITING=true
ENABLE_OBSERVABILITY=true
ENABLE_CACHING=true
ENABLE_SECURITY=true

# Features
ENABLE_FEATURE_FLAGS=true
ENABLE_NOTIFICATIONS=true
ENABLE_EMAIL_MARKETING=true
ENABLE_GAMIFICATION=true
ENABLE_ASSESSMENT=true
ENABLE_LEARNING_PATHS=true
ENABLE_ORCHESTRATION=true
ENABLE_TENANCY=true
ENABLE_CDN=true
ENABLE_LOCALIZATION=true

# Advanced (usually disabled)
ENABLE_MALWARE_SCANNING=false

# ═════════════════════════════════════════════════════════════════════════════
# NEXT STEPS
# ═════════════════════════════════════════════════════════════════════════════
#
# 1. Copy this file to .env:
#    $ cp .env.example .env
#
# 2. Update all placeholder values with your actual configuration
#
# 3. Validate environment variables:
#    $ npm run validate:env
#
# 4. For detailed documentation on each variable:
#    $ cat ENV_VARS_DOCUMENTATION.md
#
# 5. Start the application:
#    $ npm run start:dev
#
# ═════════════════════════════════════════════════════════════════════════════