Clean code in every module does not guarantee a healthy system. System entropy is decay at the level above the code: in the boundaries between components, the dependencies among them and the assumptions that hold them together.
How to recognize it
- New features take far longer than their size suggests.
- A change in one area breaks something apparently unrelated.
- New engineers need months before they can work safely.
- Nobody can draw the current architecture from memory, and the diagrams are out of date.
- Performance problems appear at load levels the system should handle.
What causes it
Boundary erosion. A module reaches directly into another's database table because it is quicker than asking for a new interface. Once it has happened a few times, neither module can change independently.
Unmanaged dependencies. Each library or external service is a commitment to track its updates and survive its failures. Abandoned dependencies also become a security problem.
Undocumented decisions. When a design's reasoning is lost, later engineers cannot tell a constraint from an accident, so they either preserve the wrong things or remove the right ones.
Integrations added one at a time. Every point-to-point link is reasonable. Together they form a web nobody can reason about.
Managing it
- Enforce boundaries. Components communicate through defined interfaces. Sharing a database table across modules should be a deliberate exception.
- Record architecture decisions. A short note on what was decided, why and what was rejected is enough, and it outlives the people involved.
- Keep an inventory of dependencies. Know what you depend on, who maintains it and when you last updated it.
- Automate the release path. Continuous integration catches a large share of regressions before they reach production.
- Monitor behaviour. Logs and metrics show how a system actually behaves, which is often not how it was designed to behave.
When to modernize
A full rewrite is rarely the right first move. It carries the risk of losing years of embedded business rules. Replacing a system in stages, one boundary at a time, is slower to announce and much safer to deliver. Start with the part that costs you the most.
For the wider picture, read why software falls apart. For the structural basics, read software architecture fundamentals.
