foxhunt/docs/CONFIGURATION_QUICK_REFERENCE.md

# Configuration Quick Reference Guide

## For Developers: Using Centralized Constants

### Import the Module

```rust
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
```rust
// ❌ 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
```rust
// ✅ 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

```bash
# 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

```bash
# 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
```rust
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
```rust
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
```rust
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
```rust
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
```rust
#[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
```rust
#[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:
```rust
// 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:
```rust
#[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):
```rust
// 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`