Webneuron
Managed Services

Maintenance is where architecture is actually decided

Design documents describe intent. Ten years of small maintenance decisions describe what the system became, and nobody reviewed any of them.

July 21, 20266 min readBy Webneuron Engineering Team

Architecture is discussed as though it happens at the beginning: a design phase, a set of diagrams, a decision record. That is where architecture is stated. It is not where it is determined.

What a system actually becomes is the accumulated result of several thousand small decisions made during maintenance — the quick fix under incident pressure, the field added because changing the schema properly would have taken a week, the special case introduced for one customer and never generalised. Each is individually defensible. Collectively they are the architecture, and none of them went through review.

Why maintenance decisions escape scrutiny

A change described as a new capability attracts design discussion, review and often a decision record. The same change described as a fix attracts none of that, and the framing is usually accurate — it is a fix. The structural consequence simply travels with it unexamined.

Where maintenance is separated organisationally from development, the effect intensifies. The maintenance team is measured on resolution time, which correctly rewards the fastest safe fix, and the fastest safe fix is almost never the one that improves the structure.

Ten years of that produces a system where the design document and the running code describe different things, and the code is right.

Bringing the decisions back into view

  • Track where changes cluster. The files touched most often during incidents are your architecture telling you where it is wrong, in the clearest terms available.
  • Distinguish the fix from the resolution. Restore service quickly, then record what the proper correction would be, and schedule the ones that recur.
  • Give maintenance work the same review standard as feature work. If a change alters structure, the framing under which it arrived should not determine whether anyone looks at it.
  • Keep the people who maintain the system connected to the people who evolve it, or the two will optimise against each other indefinitely.
  • Review the design record annually against reality, and update it. A document nobody trusts stops constraining anything.

The practical consequence

This matters most at the point organisations least expect it: the modernisation programme. Teams plan a rewrite against the documented design, then discover during delivery that the real system contains a decade of undocumented behaviour that customers depend on — and the estimate doubles.

The organisations that avoid that surprise are the ones that treated maintenance as engineering rather than as upkeep. They ended up with systems that are cheaper to change, and with an accurate account of why the system is the way it is, which is worth more than any diagram drawn at the start.

Let's build the system your business will run on next.

Tell us where it hurts. We'll bring the architects, engineers, and delivery model to fix it — and scale it.