Architectural Decision Record (ADR) 004
Document Rule Processing System - Tooling Standardization (Volta & Yarn)
Tooling Standardization (Volta & Yarn)
Status: Accepted ✅
Context
Prior to this decision, the project relied primarily on global system installations or less disciplined local tooling (e.g., manual nvm usage). This led to inconsistent environments where different developers—or continuous integration systems—could execute builds using subtly mismatched versions of Node, npm, or other language tools.
The primary risk identified was "Environmental Drift", which could result in non-deterministic build failures and a high overhead for debugging "works on my machine" issues.
Decision & Rationale
The team selected Option B (Volta) because it provides the most effective middle-ground solution:
- Reproducibility: It locks down both the runtime version (Node) and guarantees a managed environment, dramatically reducing environmental bugs.
- Low Friction: The setup overhead is minimal compared to introducing full containerization for every dependency update cycle.
- Integrity: By coupling Volta with
yarn.lock, we achieve a two-layer defense: the runtime (Volta) and the component dependencies (Yarn).
Options Considered
Option A: Relying on nvm (Node Version Manager)
Requires each developer to manually install and activate the specific Node version for every project.
Effective locally.
Lacks a robust way to pin the entire toolchain (e.g., ensuring both Node AND the associated Yarn binary are from a consistent source).
Option B: Utilizing Project-Level Pinning Tools (Volta) (Selected)
Allows the specification of required versions that are tracked alongside the project code.
Ensures anyone who runs setup gets the exact toolchain intended by the team, irrespective of their local OS environment's pre-installed tools.
Option C: Mandating Docker / Containerization
While this is the gold standard for environment isolation, it adds significant complexity (Dockerfiles, build times).
Might be overkill for the current project scope and maintainability requirements. (Rejected)
Consequences
Positive Consequences (Pros)
- Guaranteed Consistency: Consistent execution across all developer machines and CI/CD pipelines.
- Simplified Onboarding: Developers only need to run one command to set up the correct toolchain for a given project directory.
- Reduced Overhead: Less time spent debugging "works on my machine" environmental mismatches.
Negative Constraints (Cons)
- Required Discipline: Requires team members to install and utilize Volta consistently. If discipline slips, errors will occur.
Future Considerations
We must regularly review tooling standards as our project scales, particularly when evaluating major shifts (like moving towards a language runtime that does not support tools analogous to Volta).