foxhunt/docs/CONFIGURATION_QUICK_REFERENCE.md

Configuration Quick Reference Guide

For Developers: Using Centralized Constants

Import the Module

use common::thresholds;

Available Constant Modules

Module	Purpose	Example Usage
thresholds::risk	Risk management thresholds	thresholds::risk::BREACH_CRITICAL_PCT
thresholds::var	VaR calculation constants	thresholds::var::Z_SCORE_P95
thresholds::performance	Performance limits	thresholds::performance::MAX_CRITICAL_PATH_LATENCY_NS
thresholds::cache	Cache TTL defaults	thresholds::cache::POSITION_CACHE_TTL
thresholds::database	Database defaults	thresholds::database::QUERY_TIMEOUT
thresholds::network	Network/gRPC defaults	thresholds::network::GRPC_REQUEST_TIMEOUT
thresholds::retry	Retry configuration	thresholds::retry::MAX_RETRY_ATTEMPTS
thresholds::monitoring	Health checks	thresholds::monitoring::HEALTH_CHECK_INTERVAL
thresholds::events	Event processing	thresholds::events::BATCH_TIMEOUT
thresholds::ml	ML model constants	thresholds::ml::MAX_GPU_BATCH_SIZE
thresholds::safety	Safety systems	thresholds::safety::PRODUCTION_SAFETY_CHECK_TIMEOUT
thresholds::time	Time conversions	thresholds::time::NANOS_PER_SECOND
thresholds::financial	Financial constants	thresholds::financial::PRICE_SCALE
thresholds::limits	Validation limits	thresholds::limits::MAX_SYMBOL_LENGTH
thresholds::hardware	Hardware alignment	thresholds::hardware::CACHE_LINE_SIZE

Common Patterns

Before: Magic Numbers

// ❌ DON'T DO THIS
if breach_percentage >= Decimal::from(120) {
    BreachSeverity::Critical
}

let cache_ttl = Duration::from_secs(60);  // What is this for?

After: Named Constants

// ✅ DO THIS
use common::thresholds;

if breach_percentage >= Decimal::from(thresholds::risk::BREACH_CRITICAL_PCT) {
    BreachSeverity::Critical
}

let cache_ttl = thresholds::cache::POSITION_CACHE_TTL;  // Self-documenting

For Operators: Environment Variables

Development Setup

# Copy the template
cp .env.development.example .env.development

# Edit with your values
vim .env.development

# Run services
ENVIRONMENT=development cargo run --bin trading_service

Production Deployment

# Copy the template
cp .env.production.example .env.production

# IMPORTANT: Replace all CHANGE_ME and ${SECRET} values
# Use proper secrets management (Vault, AWS Secrets Manager, etc.)

# Deploy with environment file
docker-compose --env-file .env.production up -d

Critical Environment Variables

Database (Required):

• DATABASE_URL - PostgreSQL connection string
• DB_MAX_CONNECTIONS - Connection pool size
• DB_QUERY_TIMEOUT_MS - Query timeout

Redis (Required):

• REDIS_URL - Redis connection string
• REDIS_MAX_CONNECTIONS - Connection pool size

Services (Required):

• TRADING_SERVICE_URL - Trading service endpoint
• BACKTESTING_SERVICE_URL - Backtesting service endpoint
• ML_TRAINING_SERVICE_URL - ML training service endpoint

API Keys (Required):

• DATABENTO_API_KEY - Market data provider
• BENZINGA_API_KEY - News data provider

Security (Required for Production):

• JWT_SECRET - JWT signing secret
• KILL_SWITCH_MASTER_TOKEN - Emergency kill switch token

Environment-Specific Defaults

Setting	Development	Production
Auto-recovery delay	60s	1800s (30 min)
Safety check timeout	50ms	5ms
Loss check interval	30s	5s
Position check interval	15s	2s
Cache default TTL	30s	10s
Database query timeout	2000ms	800ms
Logging level	debug	warn

For System Administrators: Configuration Tiers

Tier 1: Compile-Time Constants

Location: common/src/thresholds.rs
Update Method: Code change + redeploy
Use Case: Never-changing values (time conversions, hardware alignment)

Tier 2: Runtime Configuration (Future)

Location: Environment variables
Update Method: Change .env file + restart service
Use Case: Environment-specific settings (timeouts, cache TTLs)

Tier 3: Database Configuration (Future)

Location: PostgreSQL runtime_thresholds table
Update Method: SQL UPDATE (hot-reload via NOTIFY/LISTEN)
Use Case: Operator-adjustable settings (breach thresholds, risk limits)

Quick Decision Tree

Does the value change between environments (dev/staging/prod)?
├─ Yes ─> Use Environment Variable (Tier 2)
└─ No ──┐
        │
        Does an operator need to adjust it at runtime?
        ├─ Yes ─> Use Database Config (Tier 3, future)
        └─ No ──┐
                │
                Is it a mathematical/hardware constant?
                ├─ Yes ─> Use Compile-Time Constant (Tier 1)
                └─ No ──> Use Environment Variable (Tier 2)

Examples by Use Case

Risk Management

use common::thresholds;

// Breach severity thresholds
if utilization >= thresholds::risk::BREACH_CRITICAL_PCT {
    return BreachSeverity::Critical;
}

// VaR calculation
let z_score = thresholds::var::Z_SCORE_P95;
let var = portfolio_volatility * z_score;

Caching

use common::thresholds;

// Position cache
redis_client.set_ex(
    key,
    value,
    thresholds::cache::REDIS_POSITION_LIMIT_TTL_SECS,
)?;

// In-memory cache
let cache = Cache::builder()
    .time_to_live(thresholds::cache::VAR_CACHE_TTL)
    .build();

Performance

use common::thresholds;

// Batch processing
for batch in data.chunks(thresholds::performance::DEFAULT_BATCH_SIZE) {
    process_batch(batch)?;
}

// SIMD alignment
#[repr(align(32))]  // thresholds::hardware::SIMD_ALIGNMENT
struct AlignedBuffer([f32; 8]);

Database Operations

use common::thresholds;

let pool = PgPoolOptions::new()
    .max_connections(thresholds::database::MAX_POOL_SIZE)
    .acquire_timeout(thresholds::database::ACQUIRE_TIMEOUT)
    .idle_timeout(thresholds::database::IDLE_TIMEOUT)
    .connect(&database_url)
    .await?;

Testing

Override Constants in Tests

#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_with_custom_timeout() {
        // For now, use constants as-is
        // In future: override via test config
        let timeout = thresholds::database::QUERY_TIMEOUT;
        assert!(timeout.as_millis() > 0);
    }
}

Integration Tests

#[tokio::test]
async fn test_production_timeouts() {
    std::env::set_var("ENVIRONMENT", "production");
    
    // Future: Load RuntimeConfig from env
    // For now: Use constants directly
    assert_eq!(
        thresholds::safety::PRODUCTION_SAFETY_CHECK_TIMEOUT,
        Duration::from_millis(5)
    );
}

Common Issues

Issue: Can't find constant

Solution: Check if it's in a sub-module:

// Wrong
use common::thresholds::POSITION_CACHE_TTL;

// Correct
use common::thresholds;
let ttl = thresholds::cache::POSITION_CACHE_TTL;

Issue: Need different value in tests

Solution: Use test fixtures or mock configs:

#[cfg(test)]
const TEST_TIMEOUT: Duration = Duration::from_secs(1);

#[cfg(not(test))]
const TEST_TIMEOUT: Duration = thresholds::database::QUERY_TIMEOUT;

Issue: Need runtime-configurable value

Solution: Use environment variable (now) or database config (future):

// Current approach
let timeout_ms = std::env::var("CUSTOM_TIMEOUT_MS")
    .ok()
    .and_then(|s| s.parse().ok())
    .unwrap_or(thresholds::database::QUERY_TIMEOUT.as_millis() as u64);

// Future approach (Wave 67+)
let timeout = runtime_config.get_timeout("custom_timeout");

Migration Checklist

When migrating code to use centralized constants:

• Replace hardcoded numeric literals with named constants
• Add use common::thresholds; to module imports
• Use appropriate constant module (risk, cache, performance, etc.)
• Update tests to use constants instead of magic numbers
• Document why a particular constant is used (if not obvious)
• Consider if value should be runtime-configurable

See Also

• Full Analysis: WAVE_66_AGENT_11_MAGIC_NUMBERS_ANALYSIS.md
• Deliverables: WAVE_66_AGENT_11_DELIVERABLES.md
• Source Code: common/src/thresholds.rs
• Environment Templates: .env.development.example, .env.production.example