# Freezing (Gradual Adoption)
Adding architecture rules to an existing codebase almost always reveals violations. You can't fix them all on day one — but you also can't leave the rules permanently disabled. The **freeze** mechanism solves this: you baseline the current violations and fail only on *new* ones. The codebase can only improve, never regress.
---
## 1. The problem
You add a rule:
```elixir
test "domain doesn't depend on web" do
modules_matching("MyApp.Domain.**")
|> should_not_depend_on(modules_matching("MyApp.Web.**"))
end
```
It fails with 47 violations. You can't fix 47 violations today. You could comment the test out — but then new violations will go undetected.
---
## 2. The solution: freeze
Wrap the rule in `ArchTest.Freeze.freeze/2`:
```elixir
test "domain doesn't depend on web" do
ArchTest.Freeze.freeze("domain_web_deps", fn ->
modules_matching("MyApp.Domain.**")
|> should_not_depend_on(modules_matching("MyApp.Web.**"))
end)
end
```
On the first run with no baseline, all violations are reported as new and the test fails. That's expected — the next step is to establish the baseline.
---
## 3. Establish the baseline
Run once with the update flag:
```sh
ARCH_TEST_UPDATE_FREEZE=true mix test
```
This writes a file at `test/arch_test_violations/domain_web_deps.txt` listing every current violation. Commit that file to version control.
On all subsequent runs, the freeze mechanism:
1. Runs the assertion and collects all current violations
2. Reads the baseline from the file
3. Computes `current − baseline`
4. Fails only if there are new violations not in the baseline
The 47 existing violations are silently ignored. Any *new* violation — introduced in a PR — causes a failure.
---
## 4. Clean up violations over time
As you fix legacy violations, re-run with the update flag to shrink the baseline:
```sh
ARCH_TEST_UPDATE_FREEZE=true mix test
```
The baseline file now has fewer entries. Eventually you can delete it entirely and the rule will enforce with zero tolerance.
A smaller baseline file on each PR is a visible, trackable signal of architectural progress.
---
## 5. Configure the baseline directory
Default location: `test/arch_test_violations/`
To change it:
```elixir
# config/test.exs
config :arch_test, freeze_store: "test/arch_violations"
```
---
## 6. Multiple frozen rules
Each rule gets its own key and its own baseline file:
```elixir
test "web ↛ domain (freeze)" do
ArchTest.Freeze.freeze("web_domain", fn ->
modules_matching("MyApp.Web.**")
|> should_not_depend_on(modules_matching("MyApp.Domain.**"))
end)
end
test "no Manager modules (freeze)" do
ArchTest.Freeze.freeze("no_managers", fn ->
modules_matching("MyApp.**.*Manager") |> should_not_exist()
end)
end
```
Files: `test/arch_test_violations/web_domain.txt`, `test/arch_test_violations/no_managers.txt`.
---
## 7. Recommended workflow
| Step | Command | Effect |
|------|---------|--------|
| First adoption | `ARCH_TEST_UPDATE_FREEZE=true mix test` | Writes baseline for all frozen rules |
| Normal CI | `mix test` | Fails on new violations only |
| After fixing violations | `ARCH_TEST_UPDATE_FREEZE=true mix test` | Shrinks baseline files |
| Rule fully clean | Delete the baseline file, remove `freeze` wrapper | Enforces at zero tolerance |
---
## How the freeze key is matched
Violations are compared as strings. The key format is `"CallerModule → CalleeModule"`. If a violation string appears in the baseline file, it is ignored. If it is not in the file, the test fails.
This means renaming a module *removes* it from the baseline and treats it as a new violation — which is correct, because the new name should not carry forward the old waiver.
---
## Next steps
- [Getting Started](getting-started.md) — basic dependency assertions without freezing
- [Modulith Rules](modulith-rules.md) — bounded-context isolation, a common place to start freezing
