StarPunk/docs/decisions/ADR-052-configuration-system-architecture.md

ADR-052: Configuration System Architecture

Status

Accepted

Context

StarPunk v1.1.1 "Polish" introduces several configurable features to improve production readiness and user experience. Currently, configuration values are hardcoded throughout the application, making customization difficult. We need a consistent, simple approach to configuration management that:

1. Maintains backward compatibility
2. Provides sensible defaults
3. Follows Python best practices
4. Minimizes complexity
5. Supports environment-based configuration

Decision

We will implement a centralized configuration system using environment variables with fallback defaults, managed through a single configuration module.

Configuration Architecture

Environment Variables (highest priority)
    ↓
Configuration File (optional, .env)
    ↓
Default Values (in code)

Configuration Module Structure

Location: starpunk/config.py

Categories:

1. Search Configuration

   • SEARCH_ENABLED: bool (default: True)
   • SEARCH_TITLE_LENGTH: int (default: 100)
   • SEARCH_HIGHLIGHT_CLASS: str (default: "highlight")
   • SEARCH_MIN_SCORE: float (default: 0.0)

2. Performance Configuration

   • PERF_MONITORING_ENABLED: bool (default: False)
   • PERF_SLOW_QUERY_THRESHOLD: float (default: 1.0 seconds)
   • PERF_LOG_QUERIES: bool (default: False)
   • PERF_MEMORY_TRACKING: bool (default: False)

3. Database Configuration

   • DB_CONNECTION_POOL_SIZE: int (default: 5)
   • DB_CONNECTION_TIMEOUT: float (default: 10.0)
   • DB_WAL_MODE: bool (default: True)
   • DB_BUSY_TIMEOUT: int (default: 5000 ms)

4. Logging Configuration

   • LOG_LEVEL: str (default: "INFO")
   • LOG_FORMAT: str (default: structured JSON)
   • LOG_FILE_PATH: str (default: None)
   • LOG_ROTATION: bool (default: False)

5. Production Configuration

   • SESSION_TIMEOUT: int (default: 86400 seconds)
   • HEALTH_CHECK_DETAILED: bool (default: False)
   • ERROR_DETAILS_IN_RESPONSE: bool (default: False)

Implementation Pattern

# starpunk/config.py
import os
from typing import Any, Optional

class Config:
    """Centralized configuration management"""

    @staticmethod
    def get_bool(key: str, default: bool = False) -> bool:
        """Get boolean configuration value"""
        value = os.environ.get(key, "").lower()
        if value in ("true", "1", "yes", "on"):
            return True
        elif value in ("false", "0", "no", "off"):
            return False
        return default

    @staticmethod
    def get_int(key: str, default: int) -> int:
        """Get integer configuration value"""
        try:
            return int(os.environ.get(key, default))
        except (ValueError, TypeError):
            return default

    @staticmethod
    def get_float(key: str, default: float) -> float:
        """Get float configuration value"""
        try:
            return float(os.environ.get(key, default))
        except (ValueError, TypeError):
            return default

    @staticmethod
    def get_str(key: str, default: str = "") -> str:
        """Get string configuration value"""
        return os.environ.get(key, default)

# Configuration instances
SEARCH_ENABLED = Config.get_bool("STARPUNK_SEARCH_ENABLED", True)
SEARCH_TITLE_LENGTH = Config.get_int("STARPUNK_SEARCH_TITLE_LENGTH", 100)
# ... etc

Environment Variable Naming Convention

All StarPunk environment variables are prefixed with STARPUNK_ to avoid conflicts:

• STARPUNK_SEARCH_ENABLED
• STARPUNK_PERF_MONITORING_ENABLED
• STARPUNK_DB_CONNECTION_POOL_SIZE
• etc.

Rationale

Why Environment Variables?

1. Standard Practice: Follows 12-factor app methodology
2. Container Friendly: Works well with Docker/Kubernetes
3. No Dependencies: Built into Python stdlib
4. Security: Sensitive values not in code
5. Simple: No complex configuration parsing

Why Not Alternative Approaches?

YAML/TOML/INI Files:

• Adds parsing complexity
• Requires file management
• Not as container-friendly
• Additional dependency

Database Configuration:

• Circular dependency (need config to connect to DB)
• Makes deployment more complex
• Not suitable for bootstrap configuration

Python Config Files:

• Security risk if user-editable
• Import complexity
• Not standard practice

Why Centralized Module?

1. Single Source: All configuration in one place
2. Type Safety: Helper methods ensure correct types
3. Documentation: Self-documenting defaults
4. Testing: Easy to mock for tests
5. Validation: Can add validation logic centrally

Consequences

Positive

1. Backward Compatible: All existing deployments continue working with defaults
2. Production Ready: Ops teams can configure without code changes
3. Simple Implementation: ~100 lines of code
4. Testable: Easy to test different configurations
5. Documented: Configuration options clear in one file
6. Flexible: Can override any setting via environment

Negative

1. Environment Pollution: Many environment variables in production
2. No Validation: Invalid values fall back to defaults silently
3. No Hot Reload: Requires restart to apply changes
4. Limited Types: Only primitive types supported

Mitigations

1. Use .env files for local development
2. Add startup configuration validation
3. Log configuration values at startup (non-sensitive only)
4. Document all configuration options clearly

Alternatives Considered

1. Pydantic Settings

Pros: Type validation, .env support, modern Cons: New dependency, overengineered for our needs Decision: Too complex for v1.1.1 patch release

2. Click Configuration

Pros: Already using Click, integrated CLI options Cons: CLI args not suitable for all config, complex precedence Decision: Keep CLI and config separate

3. ConfigParser (INI files)

Pros: Python stdlib, familiar format Cons: File management complexity, not container-native Decision: Environment variables are simpler

4. No Configuration System

Pros: Simplest possible Cons: No production flexibility, poor UX Decision: v1.1.1 specifically targets production readiness

Implementation Notes

1. Configuration module loads at import time
2. Values are immutable after startup
3. Invalid values log warnings but use defaults
4. Sensitive values (tokens, keys) never logged
5. Configuration documented in deployment guide
6. Example .env.example file provided

Testing Strategy

1. Unit tests mock environment variables
2. Integration tests verify default behavior
3. Configuration validation tests
4. Performance impact tests (configuration overhead)

Migration Path

No migration required - all configuration has sensible defaults that match current behavior.

References

• The Twelve-Factor App - Config
• Python os.environ
• Docker Environment Variables

Document History

• 2025-11-25: Initial draft for v1.1.1 release planning