goplt/docs/content/adr/0004-configuration-management.md

ADR-0004: Configuration Management Library

Status

Accepted

Context

The platform needs a configuration system that:

• Supports hierarchical configuration (defaults → files → env → secrets)
• Handles multiple formats (YAML, JSON, env vars)
• Provides type-safe access to configuration values
• Supports environment-specific overrides
• Can integrate with secret managers (future)

Options considered:

1. spf13/viper - Comprehensive configuration management
2. envconfig - Environment variable only
3. koanf - Lightweight configuration library
4. Standard library + manual parsing - No external dependency

Decision

Use spf13/viper (v1.18.0+) with spf13/cobra (v1.8.0+) for configuration management.

Rationale:

• Industry standard for Go configuration management
• Supports multiple sources (files, env vars, flags)
• Hierarchical configuration with precedence rules
• Easy integration with Cobra for CLI commands
• Well-documented and widely used
• Supports future secret manager integration

Consequences

Positive

• Flexible configuration loading from multiple sources
• Easy to add new configuration sources
• Type-safe access methods
• Environment variable support via automatic env binding

Negative

• Additional dependency
• Viper can be verbose for simple use cases
• Some learning curve for advanced features

Implementation Notes

• Install: go get github.com/spf13/viper@v1.18.0 and github.com/spf13/cobra@v1.8.0
• Create pkg/config/config.go interface to abstract Viper
• Implement internal/config/viper_config.go as concrete implementation
• Load order: default.yaml → development.yaml/production.yaml → env vars → secrets (future)
• Use typed getters (GetString, GetInt, GetBool) for type safety