Merge: New implementation into main

.env.example

@@ -1,11 +1,213 @@
-# Neo4j Configuration
-NEO4J_URI=bolt://localhost:7687
+# ============================================
+# Panama Papers Neo4j Project - Environment Configuration
+# ============================================
+# This is a template file. Copy this to .env and fill in actual values.
+# DO NOT commit .env to git (only commit .env.example)
+#
+# Usage:
+#   1. Copy this file: cp .env.example .env
+#   2. Update values in .env with your actual credentials
+#   3. Restart services: docker-compose restart
+# ============================================
+
+# ============================================
+# Neo4j Database Configuration
+# ============================================
+# Neo4j connection URI using Bolt protocol
+# Format: bolt://host:port or bolt+s://host:port (for SSL)
+# Default: bolt://neo4j:7687 (for Docker) or bolt://localhost:7687 (for local)
+NEO4J_URI=bolt://neo4j:7687
+
+# Neo4j database username
+# Default username is 'neo4j'
 NEO4J_USER=neo4j
-NEO4J_PASSWORD=password
 
-# API Configuration
-API_HOST=0.0.0.0
-API_PORT=8000
+# Neo4j database password
+# IMPORTANT: Change this from default for production!
+# Default password on first install is 'neo4j' but must be changed
+NEO4J_PASSWORD=changeme123
+
+# Neo4j database name (optional, defaults to 'neo4j')
+# Only needed if using multiple databases (Enterprise feature)
+# NEO4J_DATABASE=neo4j
+
+# ============================================
+# FastAPI Application Configuration
+# ============================================
+# Host address for FastAPI server
+# 0.0.0.0 allows external connections (required for Docker)
+# Use 127.0.0.1 for localhost-only access
+FASTAPI_HOST=0.0.0.0
+
+# Port for FastAPI server
+# Default: 8000
+FASTAPI_PORT=8000
+
+# Enable auto-reload on code changes
+# Set to 'true' for development, 'false' for production
+# Auto-reload watches for file changes and restarts the server
+FASTAPI_RELOAD=false
+
+# API base path (if behind reverse proxy)
+# Example: /api/v1
+# API_BASE_PATH=/
+
+# CORS allowed origins (comma-separated)
+# Example: http://localhost:3000,https://yourdomain.com
+# Use * to allow all origins (not recommended for production)
+# CORS_ORIGINS=*
+
+# ============================================
+# Database Initialization & Seeding
+# ============================================
+# Automatically seed database on startup
+# Set to 'true' to load initial data, 'false' to skip
+# Note: Seeding will only run if database is empty
+SEED_DATABASE=true
+
+# Path to Panama Papers data file
+# Supports CSV, JSON, or Parquet formats
+# Can be absolute path or relative to project root
+DATA_SOURCE_PATH=./data/panama-papers.csv
+
+# Alternative data sources (uncomment to use)
+# DATA_SOURCE_PATH=./data/panama-papers.json
+# DATA_SOURCE_PATH=./data/panama-papers.parquet
+# DATA_SOURCE_PATH=https://example.com/panama-papers-data.csv
+
+# Batch size for data import (number of records per transaction)
+# Larger batches are faster but use more memory
+# Recommended: 1000-10000 depending on available memory
+IMPORT_BATCH_SIZE=5000
+
+# Clear existing data before seeding
+# WARNING: Set to 'true' will DELETE all existing data!
+CLEAR_DATABASE_BEFORE_SEED=false
+
+# ============================================
+# Logging Configuration
+# ============================================
+# Logging level for application
+# Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
+# DEBUG: Most verbose, shows all details
+# INFO: Standard logging, recommended for production
+# WARNING: Only warnings and errors
+# ERROR: Only errors and critical issues
+# CRITICAL: Only critical failures
+LOG_LEVEL=INFO
+
+# Enable debug mode
+# Shows detailed error messages and stack traces
+# Set to 'false' in production for security
+DEBUG=false
+
+# Log format
+# Options: json, text
+# json: Structured logging (better for log aggregation)
+# text: Human-readable format (better for development)
+LOG_FORMAT=text
+
+# Log file path (optional)
+# Leave empty to log only to console
+# Example: ./logs/app.log
+# LOG_FILE_PATH=
+
+# ============================================
+# Performance & Optimization
+# ============================================
+# Maximum number of database connections in pool
+# Increase for high-traffic applications
+NEO4J_MAX_CONNECTION_POOL_SIZE=50
+
+# Connection timeout in seconds
+NEO4J_CONNECTION_TIMEOUT=30
+
+# Query timeout in seconds (0 = no timeout)
+# Prevents long-running queries from blocking resources
+NEO4J_QUERY_TIMEOUT=300
+
+# Enable query result caching
+# Caches frequently-used query results for faster responses
+ENABLE_QUERY_CACHE=true
+
+# Cache TTL in seconds (time-to-live)
+CACHE_TTL=3600
+
+# ============================================
+# Security Configuration
+# ============================================
+# Secret key for JWT tokens (if using authentication)
+# Generate with: openssl rand -hex 32
+# IMPORTANT: Keep this secret and change in production!
+# SECRET_KEY=your-secret-key-here-change-in-production
+
+# JWT token expiration time in minutes
+# TOKEN_EXPIRE_MINUTES=30
+
+# Enable HTTPS only (for production)
+# FORCE_HTTPS=false
+
+# API rate limiting (requests per minute)
+# RATE_LIMIT_PER_MINUTE=60
+
+# ============================================
+# Optional Features
+# ============================================
+# Enable API documentation endpoints
+# Set to 'false' to disable /docs and /redoc in production
+ENABLE_DOCS=true
+
+# Enable metrics and monitoring endpoint
+# Exposes /metrics endpoint for Prometheus
+ENABLE_METRICS=false
+
+# Enable GraphQL API (in addition to REST)
+# ENABLE_GRAPHQL=false
+
+# ============================================
+# Development & Testing
+# ============================================
+# Environment mode
+# Options: development, staging, production
+ENVIRONMENT=production
+
+# Enable profiling for performance analysis
+# ENABLE_PROFILING=false
+
+# Test database URI (for running tests)
+# TEST_NEO4J_URI=bolt://localhost:7687
+# TEST_NEO4J_USER=neo4j
+# TEST_NEO4J_PASSWORD=testpassword
+
+# ============================================
+# Docker-Specific Configuration
+# ============================================
+# These are automatically set by docker-compose
+# Only modify if running outside Docker
+
+# Neo4j container memory limits
+# NEO4J_HEAP_INITIAL_SIZE=512m
+# NEO4J_HEAP_MAX_SIZE=2G
+# NEO4J_PAGECACHE_SIZE=1G
+
+# ============================================
+# External Services (Optional)
+# ============================================
+# Redis for caching (if enabled)
+# REDIS_URI=redis://localhost:6379/0
+
+# Elasticsearch for full-text search (if enabled)
+# ELASTICSEARCH_URI=http://localhost:9200
+
+# Sentry for error tracking (if enabled)
+# SENTRY_DSN=https://your-sentry-dsn
 
-# Environment
-ENVIRONMENT=development
+# ============================================
+# IMPORTANT NOTES
+# ============================================
+# 1. Always change default passwords in production
+# 2. Never commit .env to version control
+# 3. Use strong passwords and secret keys
+# 4. Keep this file updated when adding new variables
+# 5. Document any custom variables added to your project
+# ============================================