Date: 2025-02-25

Status

Accepted

Context

Our ebook conversion system contains numerous hardcoded paths throughout the codebase, including:

• Build and output directories
• Content and asset directories
• External tool paths
• Format-specific output locations

This approach has led to several issues:

1. Lack of flexibility: Paths cannot be easily changed without code modifications
2. Environment inconsistency: Different environments (development, test, production) use the same paths
3. Duplication: The same paths are defined in multiple places
4. Maintenance burden: Path changes require updates in multiple files
5. Testing complexity: Tests need to override paths or work with fixed locations

As we prepare for the Elixir migration, we need a more maintainable approach to path management that will simplify the transition and improve the system's flexibility.

Decision

We will implement a centralized path configuration system with the following components:

1. Path Configuration Module: A dedicated BookProcessing::Configuration::Paths class to manage path definitions
2. Environment-specific Configuration: YAML files for different environments (development, test, production)
3. Default Paths: Sensible defaults for all required paths
4. Path Resolution: Support for both absolute and relative paths
5. Configuration Loading: Centralized configuration loading mechanism

The implementation will:

• Store all path definitions in environment-specific YAML files
• Provide a consistent API for accessing paths throughout the codebase
• Support path overrides for testing and special cases
• Handle path resolution relative to project root or other base paths
• Validate path configurations at startup

Consequences

Positive

1. Improved flexibility: Paths can be changed without code modifications
2. Environment support: Different environments can use appropriate paths
3. Reduced duplication: Paths defined in a single location
4. Easier maintenance: Path changes require updates in only one place
5. Simplified testing: Tests can easily override paths
6. Migration readiness: Clean separation of configuration from code will simplify Elixir migration

Negative

1. Migration effort: Existing code must be updated to use the new configuration system
2. Potential for confusion: Developers must learn to use the configuration system instead of hardcoding paths
3. Indirection: Additional layer between code and filesystem
4. Configuration management: Need to maintain multiple configuration files

Mitigation Strategies

1. Comprehensive documentation: Document the path configuration system thoroughly
2. Gradual migration: Update code incrementally to use the new system
3. Default fallbacks: Provide sensible defaults for all paths
4. Configuration validation: Validate configurations at startup to catch issues early
5. Path helpers: Create helper methods for common path operations

Implementation Plan

1. Create BookProcessing::Configuration::Paths class
2. Create environment-specific YAML configuration files
3. Update existing code to use the configuration system
4. Add validation for path configurations
5. Document the new approach

References

• Configuration management best practices
• Ruby configuration patterns
• Twelve-Factor App methodology (https://12factor.net/config)