Architecture Decision Records (ADRs)¶
This page provides an overview of all architectural decisions made for envresolve.
What are ADRs?¶
Architecture Decision Records document important architectural decisions along with their context and consequences. They help track the "why" behind design choices.
Current ADRs¶
ADR 0001: Variable Expansion with Regular Expressions¶
Status: Accepted Date: 2025-10-11
Decided to use regular expressions for variable expansion instead of manual string parsing.
ADR 0002: Custom Exception Hierarchy¶
Status: Accepted Date: 2025-10-11
Established a custom exception hierarchy with base exceptions for better error handling.
ADR 0003: Structured Exception Design¶
Status: Accepted Date: 2025-10-11
Defined structured exception design for variable expansion errors.
ADR 0004: Stateless Function-Based Variable Expansion¶
Status: Accepted Date: 2025-10-11
Chose a stateless function (expand_variables()) as the core API instead of a stateful class.
ADR 0005: String-Based API with Idempotent Resolution¶
Status: Accepted Date: 2025-10-12
Return str directly instead of data models, with idempotent resolution (safe to call multiple times).
ADR 0006: Nested Variable Expansion Implementation¶
Status: Accepted Date: 2025-10-13
Two-phase iterative algorithm: expand innermost ${...} first, then simple $VAR.
ADR 0007: Layer Separation (Services vs Application)¶
Status: Accepted Date: 2025-10-13
Separated pure business logic (services layer) from environment integration (application layer).
ADR 0008: Circular Reference Chain Tracking¶
Status: Accepted Date: 2025-10-13
Extended CircularReferenceError to include full reference chain (chain: list[str]) for better debugging.
ADR 0009: Manual Provider Registration Pattern¶
Status: Accepted Date: 2025-10-13
Users explicitly call register_azure_kv_provider() before resolving secrets.
ADR 0010: Iterative URI Resolution¶
Status: Accepted Date: 2025-10-13
Implemented iterative resolution with cycle detection to support URI-to-URI resolution chains.
ADR 0011: Conditional Doctest Skip¶
Status: Accepted Date: 2025-10-13
Pytest fixture-based conditional skipping for doctests requiring optional dependencies.
ADR 0012: Pytest Markers for Azure Dependencies¶
Status: Accepted Date: 2025-10-13
Introduced @pytest.mark.azure to isolate tests requiring optional Azure SDK dependencies.
ADR 0013: Class-Based API Design¶
Status: Accepted Date: 2025-10-14
Encapsulated resolution state in EnvResolver class with module-level facade for backward compatibility.
ADR 0014: Importlib Lazy Import¶
Status: Accepted Date: 2025-10-14
Used importlib.import_module for lazy loading of optional Azure SDK dependencies with rich error messages.
ADR 0015: Manage Azure Live Test Infrastructure with Terraform¶
Status: Accepted Date: 2025-10-15
Standardized live Azure Key Vault testing with Terraform-managed resources.
ADR 0016: TypeError-based Custom Exception for Mutually Exclusive Parameters¶
Status: Accepted Date: 2025-10-18
Created MutuallyExclusiveArgumentsError inheriting from both EnvResolveError and TypeError.
ADR 0017: Align load_env() Parameter with python-dotenv¶
Status: Accepted Date: 2025-10-20
Changed load_env() signature to match python-dotenv's load_dotenv() for zero-friction migration.
ADR 0018: Granular Error Handling for Variable Expansion and Secret Resolution¶
Status: Accepted Date: 2025-10-21
Split single stop_on_error flag into stop_on_expansion_error and stop_on_resolution_error.
ADR 0019: Do Not Implement Validation Helper Functions and Metadata Query Helpers¶
Status: Accepted Date: 2025-11-12
Decided not to implement validation helpers and metadata query helpers due to lack of concrete use cases.
ADR 0020: Add ignore_keys Parameter for Selective Variable Exclusion¶
Status: Accepted Date: 2025-11-13
Added ignore_keys parameter to selectively skip variable expansion for specified keys.
ADR 0021: Exception Wrapping for Variable Resolution Context¶
Status: Accepted Date: 2025-11-14
Wrap resolution errors with EnvironmentVariableResolutionError to provide context about which environment variable failed.
ADR 0022: Add ignore_patterns Parameter for Pattern-Based Variable Exclusion¶
Status: Accepted Date: 2025-11-15
Added ignore_patterns parameter to selectively skip variable expansion using pattern matching.
ADR 0023: Use fnmatch (Glob Patterns) for Pattern Matching Implementation¶
Status: Accepted Date: 2025-11-15
Use Python's fnmatch module for glob-style pattern matching in ignore_patterns.
ADR 0024: Core Design Principle of 'Fine-Grained Control'¶
Status: Accepted Date: 2025-11-17
Adopt "Fine-Grained Control" as a core design principle, prioritizing explicit configuration over implicit behavior.
ADR 0025: Strategy for Optional Dependencies and Extensibility¶
Status: Accepted Date: 2025-11-17
Define a formal strategy for optional dependencies using extras and lazy-loading to keep the core library lightweight.
ADR 0026: Strategy for Exception Handling and Error Reporting¶
Status: Accepted Date: 2025-11-17
Formalize the strategy for exception handling, including a custom hierarchy, granular types, and contextual wrapping.
ADR 0027: API Design for State Management (Class-Based Core with Default Instance Facade)¶
Status: Accepted Date: 2025-11-17
Adopt a hybrid API design with a stateful core class (EnvResolver) and default instance facade functions.
ADR 0028: Forbid All Implicit Configuration via Environment Variables¶
Status: Accepted Date: 2025-11-17
Decided to forbid any feature that implicitly alters library behavior based on environment variables, to uphold the principles of security and explicit configuration.
ADR 0029: Logger Propagation Through Layers¶
Status: Accepted Date: 2025-11-25
Pass logger instances explicitly as parameters through all layers rather than mutating instance state, ensuring thread-safe logger override behavior.
ADR 0030: Logging Information Disclosure Boundaries¶
Status: Accepted Date: 2025-11-26
Default logging exposes only operation types and error categories, without specific values. Exceptions contain full details for application-level logging decisions.
ADR 0031: Support Default Values in Variable Expansion (${VAR:-default} Syntax)¶
Status: Accepted Date: 2025-12-20
Implement ${VAR:-default} syntax for providing fallback values when variables are undefined or empty. Default values are expanded recursively and work with existing two-phase algorithm.
ADR Template¶
All ADRs follow a consistent template defined in ADR 0000: ADR Template.
Contributing¶
When making significant architectural decisions, please:
- Review existing ADRs to ensure consistency
- Use the ADR template for new decisions
- Document both what you chose AND what you rejected
- Include the "why" behind your decision