Self-maintaining architecture record
An architecture record that tells you when it has aged
Every architecture diagram is accurate on the day it is drawn and decaying by the end of the week. The problem was never drawing it. The problem is that nothing tells you when it stopped matching the code.
From a diagram to a current record
The diagram on the wiki
- The diagram was drawn for a review two reorgs ago
- Three of the services on it no longer exist
- The one that took down checkout last month is not on it
- Nobody trusts it, so nobody updates it, so nobody trusts it
The record in SourceAnt
- Every edge names the manifest it was read from
- A part that aged is marked stale, not silently wrong
- Confidence is a number you can filter the view by
- Approving is a person’s decision, on your schedule
The parts, and how sure it is about each one
Services, datastores, queues, and the edges between them, with pending proposals held apart from the ones your team has signed.
Four questions that used to need a meeting
- What else touches this?
- Traverse inbound from the part you are about to change and get the neighbours back, bounded so the answer fits in front of a person or a model.
- Can we delete this?
- Nothing inbound and a retired status is an answer. A stale edge you have not looked at is a different answer, and the record tells you which one you have.
- What is this and who calls it?
- The same traversal answers for a new hire in week one and for an agent in its first session. One query, two readers.
- How do we know that?
- Every entity and every relationship carries its evidence: the file, the manifest, the revision. An auditor gets citations rather than a spreadsheet.
What this is not
This graph is read from what your repositories declare, not from live traffic. It tells you what depends on what before you deploy. It will not show you a call that only happens at runtime through configuration or service discovery. If you run a tracing tool, the two answer different questions and both are worth having.
Put your system on the record
Run the open core on your own infrastructure, or start on the hosted workspace. The graph is portable either way.