How do I track how my system's architecture changes over time?

#What it is

Change history

The semantic difference between two snapshots of a system's technical picture: components, interfaces, relationships and claims that arrived, changed, went away, or ceased to be supported. It is not a source diff — the unit is a component or a claim, not a line.

In plain terms A record of how the technical picture of your system moved between one analysis and the next — not what the code diff was, but what it meant.

Version control already answers "what lines changed". That question has a perfect answer and it is not the one an owner is asking. The question here is "what is different about my system", and the answer to that is a list of things, not a list of edits.

#The four answers

#No longer confirmed

The category that only exists because the picture is kept rather than rewritten.

A written architecture document has two states: current, and quietly wrong. It moves between them without any event, and nobody finds out until somebody acts on it.

A claim in 1ADK has a third state. It was believed, it had evidence, and the latest analysis does not support it any more. That claim is not deleted and it is not left standing — it is marked as no longer confirmed, with the date it was last supported.

This matters most for exactly the claims people rely on. "Payments are retried three times" was true in March. In September the retry logic moved into a queue worker and the claim's evidence no longer supports it. Nobody edited a document, because nobody knew there was a document to edit. The picture, however, noticed.

#Why removal is hard

Reporting that something has been added is easy. Reporting that something has been removed requires knowing that you looked where it used to be.

Every analysis records its coverage — which scopes were examined completely, partially or not at all. Where the current analysis did not cover the area a component lived in, 1ADK does not report the component as removed. It reports that the component was not seen this time, which is a different and smaller statement.

Complete coverage is not enough on its own either. An analysis that read the whole folder and simply never mentioned a component has given silence; an analysis that says it looked for that component and it is not there has given evidence. Only the second is reported as removed. The first becomes a question for a person — absence of mention is not a removal, however thoroughly the reading was done. This is the rule that costs the product the most impressive-looking screen, and it is the one that makes the screen worth reading.

The practical consequence: a deliberately narrow analysis does not read as a demolition. This is not a nicety. Without it, the first person to run a scan limited to one directory would be told that most of their system had ceased to exist.

#Why identity is the hard part

The genuinely difficult engineering problem behind all of this, stated plainly.

To say that a component changed rather than that one component vanished and another appeared, the two analyses have to agree that they are talking about the same thing. Names are not sufficient for that:

• Rename a class and it is still the same class.
• Call two things "Main database" and they are still two different things.
• Move a file and every path-based identity breaks at once.

So an analysis is asked to give every component something stable to be recognised by — a repository path, a fully qualified name, or a label chosen and kept for things that have neither, such as a database, a queue or a deployment target. A component with none of the three is a new thing to every analysis, and its history restarts each time.

This is the part of the product that took the most work to get right, and it is worth knowing about as a buyer for one reason: a tool that cannot do this cannot have a change history at all. It can only ever show you two lists side by side and let you compare them yourself.

#Two analyses, compared

ARRIVED
  Dunning worker              BACKGROUND WORKER
  Payment queue               QUEUE
    → the billing service now publishes to it rather than
      calling the provider inline

CHANGED
  Billing service
    was: calls Payment provider directly
    now: publishes to Payment queue

GONE
  Nightly export              SCHEDULED JOB
    → asserted: this analysis looked in app/ and did not find it

NO LONGER CONFIRMED
  "A failed payment is retried inline, three times."
    last supported  ·  analysis of 14 May 2026
    reason          ·  the code that supported this claim is gone;
                       retry behaviour is now in the dunning worker
                       and has not been established

NEWLY UNKNOWN
  What happens to a payment the dunning worker cannot settle?

That is the shape of the answer, drawn so that all five blocks can be read at once. The demonstration project has a real one: 2 invented analyses put through the pipeline a customer's own scan goes through, compared by the same code. It is worth two minutes for the one line that had to be earned. 3 things arrived, and the Nightly CSV export is reported as gone — not because the later analysis went quiet about it, but because that analysis states, in as many words, that it read the folder that thing lived in from end to end and looked for it there. Take the statement away and the same silence gets you a question instead, which is the rule in the section above and the one case where it costs the product a better-looking screen.

The same comparison also has a line that is neither an arrival nor a departure. the Billing service was read by both analyses, at the same address, and the second one reads it differently: the line says changed. That is the whole of what the section above is about — a comparison that could not tell the two readings were of one thing would print a departure and an arrival instead, and start it over as something new.

You do not have to take that on trust, because the same comparison contains the other half. the Invoice PDF renderer is in the same folder, read just as thoroughly — and the second analysis never mentions it. Identical coverage, no statement, so 1ADK will not call it gone: the line reads no longer confirmed, and it says which of the two it is and on what. Both left the second analysis. Only what that analysis went looking for left the system, as far as anybody can show.

#What owners do with it

• Before a release. Not "what did we merge" — "what is now different about the system", read in an hour rather than reconstructed from pull requests.
• After a contractor's engagement ends. A comparison between the analysis at the start and the one at the end is the most direct account there is of what was actually built.
• Onboarding a technical leader. The last four comparisons tell a new CTO more about the direction of a system than the current state does.
• Sanity-checking an agent's work. Where a large amount of code was written quickly, the comparison is a straightforward way to see the shape of what arrived.

#What it does not tell you