Software ArchitectureAtlas

Software Architecture Atlas

Gain an overview. Understand the connections.

RiskChapter III · Evolution · Building block 4 of 7

Architecture erosion

Architecture erosion occurs when changes gradually subvert agreed boundaries. Baselines and test rules make new deviations from the known state visible.

By Michael Meierhoff · Meierhoff Systems

  1. BaselineThe known initial state.
  2. New derogationEverything above the baseline.
  3. DegradationRemove known paths with a date.

Context

Why this is important

Architectural boundaries rarely disappear through a big decision, but through many small shortcuts. Without a baseline, new infringements cannot be separated from old ones, and the reduction will have no consequences.

This building block deals with detection and controlled degradation of deviations. Fitness functions automate selected rules; module boundaries define the reference point.

At a glance · Planned and grown paths

Alongside the planned route via the service, a shortcut to the data store has grown, which a check rule flags.
Shop example · Playing through stages

Direct accesses with and without check

Shipping has a baseline with two known direct order accesses. A test marks each newly added dependency; the known paths have responsible persons and degradation cut-off date.

This is how you read the picture

  1. Baseline Week 0: 'Direct accesses' shows 2, 'New unnoticed' shows 0.
  2. New derogation With the switch 'Check marks new accesses' on, 'New unnoticed' stays at 0.
  3. Degradation Week 8 with check: 'Direct accesses' falls from 2 to 1 on the removal deadline.
  • 2Direct accesses
  • 0New unnoticed

The baseline records two known direct accesses of the shipping module.

Values illustrative

Move the weeks and switch on the check to compare the development of direct accesses.

Benefits & limitations

Helps if:

  • Frequent small changes can gradually expand module dependencies and responsibilities.
  • Existing boundary violations can be addressed systematically with an owner and a measurable reduction target.

Boundaries

  • Import checks only see static relationships; data accesses and real call paths complement them, as in Fitness Functions.
  • Outdated rules block useful structural changes; justify and adapt them alongside business responsibilities.
  • A baseline without a remediation deadline entrenches legacy problems; classify its entries as Technical debt.

In practice

  1. Define the target structure. Specify permitted dependencies, data ownership and relevant boundaries for the modules under review. Justify each rule through its intended effect. This provides a testable reference for actual relationships.
  2. Investigate the current state using indicators. Use change frequency and co-changes as search signals, and examine concrete commits with their business context through Software Analytics. Combine the findings with import analysis, data access and runtime paths; distinguish new violations from existing deviations and identify their impact and owners.
  3. Reduce deviations or change the rule. Plan a bounded step, prevent new unwanted relationships and verify the effect again. For a legitimate business change, also adjust the target structure. This keeps enforcement aligned with evolution.
Read the detailed explanation

Architecture erosion occurs when small changes add relationships, data access or responsibilities beyond intended boundaries. Cycles, direct access to another module’s data and duplicated rules can spread later changes or failures across several areas. Measurement rules and baselines from Fitness Functions expose some of this; clear Module boundaries define the reference point.

Static analysis captures imports, while runtime calls and shared data need further investigation. Existing violations can be assessed and reduced gradually; new deviations can be flagged early. Rules remain testable design assumptions. When business responsibility deliberately changes, update the target structure and checks together so the rules reflect the new boundary. A baseline records the known state and distinguishes new violations. An accountable owner and a remediation decision place known deviations into future work. Frequent changes, complex hotspots or shared commits suggest where to investigate but do not establish causes. Software Analytics explores investigation of concrete changes.

Check your understanding

Test yourself in three stages

  1. ReadingCheck in the picture

    How many direct accesses does the visual show in week 4 without check?

    View the solution with justification

    5 direct accesses, of which 3 are new and unnoticed (illustrative).

  2. ApplyingTransferred to a new situation

    A pull request adds another direct access of the shipping module. How does the check help?

    View the solution with justification

    It marks it as a new deviation above the baseline of 2. The code then goes via the order contract.

  3. EvaluateWeighing an alternative

    The team wants to fix all legacy accesses before switching on the check. What speaks for it, what speaks against it, and what do you recommend?

    View the solution with justification

    Advantage: a clean state without exceptions. Disadvantage: until then, new accesses grow unnoticed. Recommendation: switch on the check immediately with the baseline and dismantle legacy accesses with owner and date.

Explore further

These building blocks continue the thoughts of this page.

EvolutionFitness functionsFitness Functions continuously and automatically check important architectural properties.Opening EvolutionTechnical debtHere you learn how technical debt arises and how to assess its later change costs.Opening PrinciplesModule boundariesModule boundaries define which data and capabilities a module owns and which contracts others use to access them.Opening

References

Continue on the learning path

Next in Evolution & assessment: Fitness functions.

7 Building blocks

Continue withFitness functions