Architectural Archaeology

Technology has its own ruins. The inconvenient part is that they are still running.

If nobody can explain why the system works this way, start digging

Archaeology is usually associated with things that stopped working a very long time ago. We excavate what remains, examine the layers and try to reconstruct how people lived, what they valued and why they made the decisions they did. The people responsible are no longer available to explain themselves, the records are incomplete and much of the evidence has been damaged, moved or buried beneath whatever came next.

Technology has its own version, except the ruins are still running.

They may be processing payments, serving customers, storing regulated data, scheduling field operations or holding together a product that has become far more successful than anybody expected when the first version was built. People know enough to keep the service alive, although perhaps not enough to explain why it behaves as it does, how all its parts arrived there, or whether the decisions embedded within it still accord with what the organisation is trying to achieve.

I call the work needed to understand that situation Architectural Archaeology: the recovery of the architecture, operating model, decisions and strategic intent embedded within technology that an organisation can still operate but can no longer adequately explain.

Software archaeology and architecture recovery are established disciplines. They help us inspect poorly documented code, recover structure from an implemented system and reconstruct an as-built architecture where the as-designed view is missing or obsolete. That work matters. But in the situations I am describing, it does not go far enough.

If you recover only the technical architecture, you may understand how the organisation created the problem without understanding why it will create it again.

The test environment that nobody knows how to build

One of the earliest and most revealing signs is often a request that sounds entirely reasonable: build another environment.

Perhaps the organisation needs a scaled replica of production for operational acceptance testing. Perhaps it needs to prove performance, concurrency, resilience, recovery or data migration before an important release. It may need a new geography, a disaster-recovery capability, a secure test environment or somewhere to reproduce the behaviour behind a recurring live-service incident.

The initial assumption is that this is an infrastructure task. Production already exists, so surely somebody can build a smaller version of it.

Then the questions begin.

Which configuration is authoritative? Why does the production database behave differently from every lower environment? Which services are deployed automatically and which were changed by hand? Why does this component call that one directly when the architecture diagram shows an interface in between? Why is a supposedly temporary queue carrying critical workload three years later? Why does the service depend upon data nobody knew it retained? Why is it configured like that?

And nobody has a good answer.

This is not unusual. Production systems are changed under pressure. An incident needs resolving, a customer needs supporting, a supplier changes an interface, a launch date does not move, or somebody discovers that the original design cannot cope with real behaviour. A pragmatic decision is made. Then another. And then another. The service survives, the team moves on and the reason becomes separated from the change.

People leave. Suppliers change. Documentation falls behind. Infrastructure is upgraded in place. Configuration is copied, edited and copied again. The build pipeline recreates most of the service, but not the manual intervention, unusual dataset, inherited certificate, network exception or operational workaround that makes production production.

Just because you have an application, a product and a service does not mean you have an architecture. Sometimes you just have some software that you wrote.

That statement is not a criticism of every early-stage product team. Start-ups need to move quickly. Informal communication, broad generalists and rapid implementation may be entirely appropriate when finding product-market fit. Designing an enterprise operating model before proving anybody wants the product would be its own form of failure.

The problem arrives when the circumstances change but the approach does not. What helped the organisation begin is not necessarily what will help it continue.

When your product or service does not have an architecture, nothing breaks it quicker than SUCCESS!

Failure may expose one weakness. Success applies more customers, transactions, integrations, data, markets, people, regulators and expectations to every weakness at once. The service becomes more important at precisely the point its accidental architecture becomes harder to understand, reproduce and change.

The software that remembers the business

The second clue appears when an organisation decides to replace a legacy system and discovers that the system contains far more than features.

A long-lived application can accumulate business rules, operational constraints, exception handling, prioritisation logic, data relationships, customer commitments, simulation capability and the working knowledge of people who have spent years adapting the service to reality. The organisation changed the system to reflect how the business worked. The system then began shaping how the business could work. Eventually nobody could say confidently where the operating model ended and the technology began.

You may think you have a legacy application. What you may actually have is twenty years of business decisions wearing an application's clothes.

Reading the code can help recover algorithms. Analysing data can expose decision inputs. Mapping interfaces can show information flows. None of those alone explains which rules remain strategically valid, why a manual intervention exists, whether an exception still matters, how operators compensate for the technology, or whether the organisation still wants the balance of automation and human judgement around which the system evolved.

This is where Architectural Archaeology becomes broader than software archaeology. The artefacts include software, data, infrastructure and security controls, but they also include service procedures, customer journeys, funding decisions, product backlogs, support tickets, risk acceptances, supplier boundaries, operating measures and the memories of people who have lived with the system.

The purpose is not to preserve all of it. Legacy estates contain duplication, obsolete assumptions and workarounds whose original circumstances disappeared long ago. Modernisation should remove some of that complexity. But you cannot make an informed decision about what to preserve, simplify or discard until you understand what exists and why.

The purpose of Architectural Archaeology is not to rebuild the ruins. It is to understand which foundations still carry weight before somebody drives a bulldozer through them.

The architecture is telling you about the organisation

The third clue is a pattern of technical problems that competent engineers repeatedly fix without changing the organisation's trajectory.

The visible symptoms might be database contention, deployment failures, uncontrolled data growth, weak fault isolation, unsafe customer integrations or test environments that cannot reproduce live behaviour. Each problem is real and may require specialist engineering. The technical problem is not imaginary. It is simply not the whole explanation.

Digging beneath those symptoms may reveal that functionality consistently outranked non-functional quality; known risks did not alter priorities; architecture existed as advice rather than decision authority; generalist engineers were carrying specialist responsibilities; service ownership was unclear; operational evidence did not influence the product roadmap; or the organisation was still using a start-up decision model after becoming a business-critical platform operator.

This is not a technology or engineering problem. It is a business, operating-model and decision-making problem surfacing through technology.

That does not excuse poor engineering, nor does it mean every production incident is caused in the boardroom. Sometimes a query is bad, a platform is misconfigured or a deployment contains a defect. But when different technical failures keep producing strangely familiar operational consequences, the investigation needs to widen.

Architecture rarely disappears in one dramatic decision. It is normally negotiated away, one reasonable exception at a time. Meet the deadline. Support the customer. Enter the market. Defer the difficult migration. Restore the service quickly. Each choice may be defensible in isolation. The archaeology begins when the reasons are forgotten but the compromises remain.

Four layers, one architecture

A useful investigation moves through four connected layers.

The technical layer

Software, data, interfaces, infrastructure, configuration, security controls, deployment, runtime behaviour and recovery. This is where much conventional architecture recovery begins, and where hard evidence often survives.

The service layer

Customer journeys, processes, operating procedures, service levels, measures, incidents, workarounds and exceptions. This layer explains how the technical system is used and what people do when it does not behave as expected.

The organisational layer

Ownership, decision rights, team boundaries, suppliers, governance, incentives and capability. Organisational silos leave technical seams. Unclear ownership becomes shared databases and duplicated decisions. Temporary programme boundaries become permanent interfaces.

The strategic layer

Outcomes, value, risk appetite, investment trade-offs and future direction. This is where we decide whether the recovered capability still supports the organisation the boardroom now wants to create.

Evidence flows upwards. Intent should flow downwards. When those movements stop meeting, the technology can continue operating successfully while serving decisions the organisation no longer consciously holds.

So, how do you dig?

Architectural Archaeology is not a request for a larger documentation programme. Producing hundreds of diagrams nobody uses simply creates a better-labelled ruin. The objective is to recover enough truth to make the next important decision responsibly.

Recover what exists

Examine live systems, source, data models, configuration, infrastructure, interfaces, controls, deployments, incidents, test environments and operational procedures. Build views from evidence rather than treating the nearest diagram as fact. If the lower environments disagree with production, production wins the argument.

Recover why it exists

Speak to product, engineering, service, operations, security, data, customer-facing teams and suppliers. Compare memory with evidence. People may remember why something changed, but recollection is not proof. In archaeology, stories help explain the artefacts. They do not replace them.

Decide what future it should serve

Reconnect the recovered architecture to current strategy, customer outcomes, operating-model intent, risk appetite, regulatory obligations and service expectations. A recovered architecture is not automatically an architecture worth preserving.

Build the transition, not merely the destination

Identify what must be stabilised, tested, decoupled, replaced, retained or retired. Define representative environments and safe interim states. Prove the critical assumptions before they harden into procurement, implementation and an expensive new version of the old problem.

AI can help read repositories, summarise documentation, map dependencies and accelerate parts of reverse engineering. That is useful. It can also produce an extremely plausible explanation that does not survive contact with the live system. AI can tell you what appears to be in the repo. It cannot, by itself, decide whether the organisation should still want what the repo was built to deliver.

One final question

If you had to rebuild one of your most important services tomorrow, could your organisation explain not only how it works, but why it works that way?

Could it identify which decisions remain valid, which were temporary compromises, which business rules exist only in software, which responsibilities live only in people's heads and which parts of the system support a strategy the organisation no longer holds?

Could it build a representative test environment without production surprising everybody?

If not, you do not yet have a modernisation problem.

You have an excavation ahead of you.

The question is whether you begin digging before something important collapses.

Watchmen helps organisations recover and understand complex architectures before critical modernisation, migration or transformation decisions become expensive delivery problems. If your organisation can still operate an important service but can no longer adequately explain it, we should talk.