env.example

# Cost Katana Backend Environment Variables

# ===================================
# Core Application Settings
# ===================================
NODE_ENV=development
PORT=8000
FRONTEND_URL=http://localhost:3000

# ===================================
# Database Configuration
# ===================================
MONGODB_URI=mongodb://localhost:27017/cost-katana

# ===================================
# Authentication & Security
# ===================================
JWT_SECRET=your-super-secret-jwt-key-change-this
JWT_EXPIRES_IN=7d
JWT_REFRESH_SECRET=your-refresh-secret-key-change-this
JWT_REFRESH_EXPIRES_IN=30d
ENCRYPTION_KEY=your-encryption-key-change-this

# ===================================
# OAuth Authentication (Google & GitHub)
# ===================================
# Google OAuth credentials for user authentication
# Get yours at: https://console.cloud.google.com/apis/credentials
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_CALLBACK_URL=http://localhost:8000/api/auth/oauth/google/callback

# GitHub OAuth credentials for user authentication (separate from integration)
# Get yours at: https://github.com/settings/developers
GITHUB_OAUTH_CLIENT_ID=your-github-oauth-client-id
GITHUB_OAUTH_CLIENT_SECRET=your-github-oauth-client-secret
GITHUB_OAUTH_CALLBACK_URL=http://localhost:8000/api/github/callback

# ===================================
# AWS Configuration
# ===================================
AWS_ACCESS_KEY_ID=your-aws-access-key
AWS_SECRET_ACCESS_KEY=your-aws-secret-key
AWS_REGION=us-east-1

# Required for AWS Internal Access Control (operator MFA, dual approval)
# Min 32 chars. Add to ECS task definition / Secrets Manager for production
INTERNAL_MFA_ENCRYPTION_KEY=your-32-char-minimum-secure-encryption-key
AWS_BEDROCK_REGION=us-east-1

# AWS Bedrock Settings
AWS_BEDROCK_MODEL_ID=anthropic.claude-3-haiku-20240307-v1:0
AWS_BEDROCK_MAX_TOKENS=4096
AWS_BEDROCK_TEMPERATURE=0.7

# AWS Bedrock Template-Specific Settings
AWS_BEDROCK_TEMPLATE_MODEL_ID=amazon.nova-micro-v1:0

# Visual Compliance Settings
VISUAL_COMPLIANCE_DEFAULT_MODEL=amazon.nova-pro-v1:0
CLAUDE_SONNET_MODEL_ID=us.anthropic.claude-3-5-sonnet-20241022-v2:0

# AWS S3 Settings
AWS_S3_BUCKET=cost-katana-uploads
AWS_S3_REGION=us-east-1

# ===================================
# Native AI Provider SDKs (USER PROVIDED)
# ===================================
# ⚠️ IMPORTANT: These API keys must be provided by YOU (the user)
# CostKATANA does not include or provide these API keys
# Without these keys, OpenAI and Gemini models will NOT be available

# OpenAI API Key (for direct OpenAI model access)
# Get yours at: https://platform.openai.com/api-keys
# Without this: GPT-4, GPT-3.5, and other OpenAI models will not work
OPENAI_API_KEY=your-openai-api-key
OPENAI_ORG_ID=your-openai-org-id

# Anthropic
ANTHROPIC_API_KEY=your-anthropic-api-key

# Google AI API Key (for direct Gemini model access)
# Get yours at: https://makersuite.google.com/app/apikey
# Without this: Gemini 2.5 Pro, Gemini Flash, and other Google models will not work
GEMINI_API_KEY=your-google-ai-api-key

# ===================================
# External Services
# ===================================
# Google Search API (for web search capabilities)
GOOGLE_SEARCH_API_KEY=your-google-custom-search-api-key
GOOGLE_SEARCH_ENGINE_ID=your-programmable-search-engine-id

# Mixpanel Analytics
MIXPANEL_TOKEN=your-mixpanel-token
MIXPANEL_API_SECRET=your-mixpanel-api-secret
MIXPANEL_DEBUG=false
ENABLE_GROUP_ANALYTICS=true
MIXPANEL_BATCH_SIZE=50
MIXPANEL_FLUSH_INTERVAL=10000

# LangSmith
LANGCHAIN_TRACING_V2=true
LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
LANGCHAIN_API_KEY=your-langsmith-api-key
LANGCHAIN_PROJECT=cost-katana

# ===================================
# Email Configuration
# ===================================
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-specific-password
EMAIL_FROM=Cost Katana <noreply@costkatana.com>

# ===================================
# Redis Configuration
# ===================================
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# ===================================
# Logging Configuration
# ===================================
# Enable/disable request logging middleware
ENABLE_REQUEST_LOGGING=true

# Log level: OFF, ERROR, WARN, INFO, DEBUG, VERBOSE
LOG_LEVEL=INFO
LOG_FILE_PATH=./logs

# ===================================
# Rate Limiting
# ===================================
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

# ===================================
# CORS Configuration
# ===================================
# Comma-separated allowed origins, or * for reflect-any-origin (see app.config.ts).
# Production: include https://app.costkatana.com (or set FRONTEND_URL below — it is merged into the allowlist).
CORS_ORIGIN=*

#
# If POST /api/optimizations returns 504, the load balancer may be timing out before the API responds.
# AWS ALB default idle timeout is 60s; raise it to 120–300s for long Cortex/optimization requests.

# ===================================
# Sentry Error Tracking & Performance Monitoring
# ===================================
# Sentry DSN for error tracking (optional)
SENTRY_DSN=your-sentry-dsn-here

# Sentry environment (development, staging, production)
SENTRY_ENVIRONMENT=development

# Sentry release version (auto-populated from package.json)
SENTRY_RELEASE=

# Error sampling rate (0.0 to 1.0, 1.0 = 100% of errors)
SENTRY_SAMPLE_RATE=1.0

# Performance tracing sample rate (0.0 to 1.0, lower for production)
SENTRY_TRACES_SAMPLE_RATE=0.1

# Profiling sample rate (0.0 to 1.0, lower for production)
SENTRY_PROFILES_SAMPLE_RATE=0.1

# Enable Sentry debug mode (logs Sentry internal operations)
SENTRY_DEBUG=false

# Server name for identifying instances
SENTRY_SERVER_NAME=cost-katana-backend

# Enable/disable performance monitoring
SENTRY_ENABLE_PERFORMANCE_MONITORING=true

# Enable/disable profiling
SENTRY_ENABLE_PROFILING=true

# Enable/disable error filtering
SENTRY_ENABLE_ERROR_FILTERING=true

# ===================================
# OpenTelemetry Configuration
# ===================================
# Service identification
OTEL_SERVICE_NAME=cost-katana-api

# OTLP Endpoints - Mode A: Direct to vendor
# Set to empty to disable OTLP export (recommended for development)
OTLP_HTTP_TRACES_URL=
OTLP_HTTP_METRICS_URL=

# Alternative: Use localhost collector if you have one running
# OTLP_HTTP_TRACES_URL=http://localhost:4318/v1/traces
# OTLP_HTTP_METRICS_URL=http://localhost:4318/v1/metrics

# Authentication headers for vendor (e.g., {"Authorization":"Bearer YOUR_TOKEN"})
# Must be valid JSON format
OTEL_EXPORTER_OTLP_HEADERS=

# TLS Certificate (optional, base64 encoded certificate content for secure connections)
OTEL_EXPORTER_OTLP_CERTIFICATE=

# Security settings for OTLP exporter
OTEL_EXPORTER_OTLP_INSECURE=true

# Privacy Settings
CK_CAPTURE_MODEL_TEXT=false

# Regional telemetry routing (auto, us, eu, ap)
CK_TELEMETRY_REGION=auto

# Optional: Enable/disable telemetry completely
TELEMETRY_ENABLED=true

# Optional: Collector watchdog for auto-restart (production)
ENABLE_COLLECTOR_WATCHDOG=false
COLLECTOR_WATCHDOG_INTERVAL=60000

# ===================================
# Telemetry Cleanup & Optimization
# ===================================
# Auto-delete telemetry data older than X days
TELEMETRY_TTL_DAYS=7

# Retention policies (in days)
TELEMETRY_ERROR_RETENTION_DAYS=30              # Keep errors longer
TELEMETRY_SUCCESS_RETENTION_DAYS=7             # Keep successful requests
TELEMETRY_VECTOR_RETENTION_DAYS=3              # Keep vector embeddings

# Sampling rate for successful requests (0.0 to 1.0)
# 0.1 = 10% of successful requests are stored, 0.5 = 50%, 1.0 = 100%
TELEMETRY_SAMPLE_RATE=0.1

# Enable/disable vector embeddings (consumes significant space)
ENABLE_TELEMETRY_VECTORIZATION=false

# ===================================
# External Telemetry Polling
# ===================================
# Enable polling user's telemetry endpoints
ENABLE_TELEMETRY_POLLING=true

# How often to poll user endpoints (in minutes)
TELEMETRY_SYNC_INTERVAL_MINUTES=5

# Maximum number of traces to fetch per endpoint per poll
MAX_TRACES_PER_POLL=100

# ===================================
# GitHub Integration
# ===================================
# GitHub App credentials for auto-integration feature
GITHUB_APP_ID=
GITHUB_APP_PRIVATE_KEY=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_WEBHOOK_SECRET=
GITHUB_CALLBACK_URL=

# ===================================
# Linear Integration
# ===================================
# Linear OAuth credentials for integration feature
LINEAR_CLIENT_ID=your-linear-client-id
LINEAR_CLIENT_SECRET=your-linear-client-secret
LINEAR_CALLBACK_URL=http://localhost:8000/api/integrations/linear/callback
BACKEND_URL=http://localhost:8000

# ===================================
# JIRA Integration
# ===================================
# JIRA OAuth credentials for integration feature
JIRA_CLIENT_ID=your-jira-client-id
JIRA_CLIENT_SECRET=your-jira-client-secret
JIRA_CALLBACK_URL=http://localhost:8000/api/integrations/jira/callback

# ===================================
# Vercel Integration
# ===================================
# Vercel OAuth credentials for deployment management
# Get yours at: https://vercel.com/account/tokens (OAuth Apps section)
VERCEL_CLIENT_ID=your-vercel-client-id
VERCEL_CLIENT_SECRET=your-vercel-client-secret
VERCEL_CALLBACK_URL=http://localhost:8000/api/vercel/callback
VERCEL_WEBHOOK_SECRET=your-vercel-webhook-secret
# Webhook secret for verifying webhook signatures (optional but recommended)
# Get this from your Vercel OAuth app settings

# Slack OAuth (for token refresh in integrations)
# Get your credentials from: https://api.slack.com/apps
SLACK_CLIENT_ID=your-slack-client-id
SLACK_CLIENT_SECRET=your-slack-client-secret
# Required for OAuth token refresh functionality

# Discord OAuth (for token refresh in integrations)
# Get your credentials from: https://discord.com/developers/applications
DISCORD_CLIENT_ID=your-discord-client-id
DISCORD_CLIENT_SECRET=your-discord-client-secret
# Required for OAuth token refresh functionality

# ===================================
# Payment Gateway Configuration
# ===================================
# Stripe Payment Gateway
# Get your keys from: https://dashboard.stripe.com/apikeys
STRIPE_SECRET_KEY=sk_test_your-stripe-secret-key
STRIPE_WEBHOOK_SECRET=whsec_your-stripe-webhook-secret
# For production, use: sk_live_... and whsec_... from webhook settings
# Webhook secret is obtained from Stripe Dashboard > Developers > Webhooks > Add endpoint

# Razorpay Payment Gateway
# Get your keys from: https://dashboard.razorpay.com/app/keys
RAZORPAY_KEY_ID=your-razorpay-key-id
RAZORPAY_KEY_SECRET=your-razorpay-key-secret
RAZORPAY_WEBHOOK_SECRET=your-razorpay-webhook-secret
# Webhook secret is set in Razorpay Dashboard > Settings > Webhooks

# PayPal Payment Gateway
# Get your credentials from: https://developer.paypal.com/dashboard/applications
PAYPAL_CLIENT_ID=your-paypal-client-id
PAYPAL_CLIENT_SECRET=your-paypal-client-secret
PAYPAL_MODE=sandbox
# Options: 'sandbox' for testing, 'live' for production
PAYPAL_WEBHOOK_ID=your-paypal-webhook-id
# Webhook ID is obtained from PayPal Developer Dashboard > Webhooks
PAYPAL_RETURN_URL=http://localhost:3000/subscription/success
# Optional: Override default return URL after PayPal payment
PAYPAL_CANCEL_URL=http://localhost:3000/subscription/cancel
# Optional: Override default cancel URL for PayPal payment

# ===================================
# Database Backup Configuration
# ===================================
# Enable automatic database backups
ENABLE_DB_BACKUP=true

# Backup frequency in hours (default: 12)
BACKUP_INTERVAL_HOURS=12

# Local backup directory
BACKUP_LOCAL_PATH=./backups

# Backup retention days (local and S3)
BACKUP_RETENTION_DAYS=30

# S3 backup configuration
BACKUP_S3_BUCKET=cost-katana-backups
BACKUP_S3_REGION=us-east-1
BACKUP_S3_PREFIX=database-backups

# MongoDB dump options
MONGODB_DUMP_OPTIONS=--gzip --archive

# Backup compression (gzip, bzip2, or none)
BACKUP_COMPRESSION=gzip

# ===================================
# RAG Configuration
# ===================================
# Enable/disable RAG ingestion system
ENABLE_RAG_INGESTION=true

# Embedding model for vector generation
RAG_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0

# Chunking configuration
RAG_CHUNK_SIZE=1000
RAG_CHUNK_OVERLAP=200

# Sync interval in hours (how often to sync conversations/telemetry)
RAG_SYNC_INTERVAL_HOURS=6

# MongoDB Vector Search index name
MONGODB_VECTOR_INDEX_NAME=document_vector_index

# Ingestion Settings
INGEST_ON_STARTUP=false
INGEST_CONVERSATIONS=true
INGEST_TELEMETRY=true
MAX_DOCUMENT_SIZE_MB=10

# ===================================
# FAISS Vector Storage Configuration
# ===================================
# FAISS Configuration
FAISS_INDEX_PATH=./data/faiss
FAISS_MAX_LOADED_INDICES=100
FAISS_WRITE_BATCH_SIZE=50
FAISS_WRITE_BATCH_TIMEOUT_MS=5000

# Migration Feature Flags
ENABLE_FAISS_DUAL_WRITE=false
ENABLE_FAISS_SHADOW_READ=false
ENABLE_FAISS_PRIMARY=false

# Recovery Configuration
FAISS_AUTO_RECOVERY=true
FAISS_VALIDATION_INTERVAL_HOURS=24

# ===================================
# Performance Tuning
# ===================================
MAX_POOL_SIZE=10
CONNECTION_TIMEOUT=60000
REQUEST_TIMEOUT=30000

# ===================================
# Monitoring Endpoints (Optional)
# ===================================
# For Mode C: Individual Docker containers
TEMPO_ENDPOINT=http://localhost:3200
PROMETHEUS_ENDPOINT=http://localhost:9090
GRAFANA_ENDPOINT=http://localhost:3000

# ===================================
# Feature Flags
# ===================================
ENABLE_CACHING=true
ENABLE_RATE_LIMITING=true
ENABLE_TELEMETRY=true
ENABLE_SECURITY_MONITORING=true

# ===================================
# API Keys for Testing
# ===================================
TEST_API_KEY=test-api-key-for-development

# ===================================
# Development Settings
# ===================================
DEBUG=false
VERBOSE_LOGGING=false