Skip to content

ADR-001: Break Monolithic loader.py

Date: 2024-12-18
Status: Accepted
Deciders: Duckalog Architecture Team

Context

The configuration system had evolved into a monolithic architecture with a single loader.py file containing 1,670 lines of code. This violated the Single Responsibility Principle and created several problems:

  • Maintenance burden: Difficult to locate and fix bugs in such a large file
  • Testing challenges: Hard to test individual components in isolation
  • Circular dependencies: Tight coupling between different concerns
  • Developer experience: Steep learning curve for new contributors

Decision

Break down the monolithic loader.py into focused, single-responsibility modules:

  • api.py: Public API orchestration layer
  • loading/: File and remote loading adapters
  • resolution/: Environment and import resolution
  • security/: Path validation and security boundaries

Consequences

Positive

  • Improved maintainability: Each module has a clear, focused responsibility
  • Better testability: Components can be tested in isolation with dependency injection
  • Enhanced extensibility: New implementations can be plugged in through abstract interfaces
  • Clearer dependencies: Dependency injection creates explicit, manageable relationships

Negative

  • Increased complexity: More modules to understand and coordinate
  • Migration effort: Existing code needed updates to work with new architecture
  • Learning curve: Developers need to understand the new modular structure

Neutral

  • No breaking changes: All existing APIs continue to work unchanged
  • Performance: Request-scoped caching provides significant performance improvements

Implementation

The refactoring was implemented in phases: 1. Create new modular structure alongside existing code 2. Migrate functionality incrementally with backward compatibility 3. Add deprecation warnings for old patterns 4. Plan for eventual legacy code removal in major version release

References