Short answer
#What it is
- System map
- A structured record of the components of a software system, the containment between them, the relationships that connect them, and the interfaces through which they communicate. Each element carries a description written for a reader who does not open code, and each non-obvious claim carries the file and line range it was derived from.
- In plain terms A written answer to 'what is this software made of, and what talks to what' — where every line can be traced back to something in the code.
The reason to have one is not aesthetic. It is that a large number of ordinary business decisions — can we change supplier, can this person go on holiday, what breaks if that provider has an outage, what do we hand a new team — turn out to require this exact information, and in most companies it exists only as something a particular developer knows.
#What belongs in one
Everything below is present in a 1ADK project because the analysis instruction asks for it explicitly. A map that has only the first row is a picture; a map that has all of them is usable by somebody who was not there.
| Element | The question it answers |
|---|---|
| Components | What is this system made of? Services, modules, databases, queues, jobs, scheduled work, front ends. |
| Containment | What sits inside what — in the application, in the deployment, in the data. |
| Relationships | What uses, depends on, reads from, writes to or implements what — and in which direction. |
| Interfaces | How two things actually talk: the endpoint, the queue, the channel, and what each operation is for. |
| Data | What business objects exist, what shapes they take, and where they move. |
| Evidence | Where each of the above was found. A path and a line range, not a promise. |
| Unknowns | What could not be established, and why it matters. |
| Coverage | Which parts of the system were actually looked at — and which were not. |
The last two are the ones most maps leave out, and they are the ones that decide whether the map can be relied on. A map with no gaps in it has either been produced from a complete analysis or has quietly turned its gaps into silence — and from the outside those two look identical.
#Why it is not a diagram
Architecture diagrams are useful. They are also a different object with different failure modes.
| Architecture diagram | System map | |
|---|---|---|
| Where it comes from | Somebody's understanding, drawn by hand | Derived from an analysis of the system |
| What a box means | Whatever the author intended | A named component with a type and a description |
| How you check it | Ask the author | Open the file it cites |
| What happens when the system changes | It silently becomes wrong | The next analysis reports the difference |
| What it is good at | Explaining intent, and arguing about a design that does not exist yet | Establishing what does exist |
Both are worth having. The trouble starts when a diagram drawn eighteen months ago is used to answer a question about the system as it is today, which is what happens in practice because it is the only artefact in the room.
#What one looks like
A subscription billing system, seen at the level an owner reads. Each line here corresponds to an entry with a type, a description and — where the claim is not obvious — a file and line range behind it.
Customer portal WEB APPLICATION
→ reads from Subscription service
→ sends to Billing service /api/invoices POST
Billing service SERVICE
→ writes to Main database payments, invoices
→ publishes to Payment queue
→ calls Payment provider EXTERNAL · REST
Dunning worker BACKGROUND WORKER
→ consumes Payment queue
→ writes to Main database
Nightly export SCHEDULED JOB
→ reads from Main database
→ writes to (destination not established) UNKNOWNThe last line is the one to look at. A conventional document would either have omitted the export or guessed at where the file goes. Recorded as an unknown, it becomes a question somebody can answer in five minutes — and until they do, nobody builds a plan on top of a guess.
The demonstration project is a working version of this: an invented billing system you can open, click through and read, with no account.
#Five views of the same system
The same components, arranged by the question you are asking.
A component belongs in more than one hierarchy at once. A payment service is inside an application, inside a deployment, and inside a business capability, and those are three different parents. Flattening them into one tree is what makes most architecture documents feel almost right and never quite usable.
- Application — what the software is made of, in software terms.
- Business — what the software does, in the company's terms.
- Organization — who owns what.
- Deployment — what runs where.
- Data — what information exists and where it lives.
The practical value is that two different people can get a straight answer from one record. An owner asking "what happens to invoicing if that supplier goes down" and an engineer asking "what deploys together" are reading the same map through different views.
#What makes it trustworthy
Three properties, and a map missing any of them is a document with better formatting.
-
Every claim can be opened
A statement about a component names the file and the lines it came from. Somebody with the repository can check it in under a minute, without asking the person who produced it.
-
Gaps are visible
What could not be established is recorded as an open question, with a reason. Silence is never used to mean “nothing there”.
-
Staleness is detectable
The map has a date and a coverage record, and the next analysis reports what changed since it — including which of its own earlier claims are no longer supported.
#What a map cannot tell you
What this does not do
- Why it was built this way. A map records what exists; the reasoning behind a decision lives in people, and an analysis cannot recover it. It can, however, tell you which decisions you need to ask about.
- Whether it is any good. There is no quality score. A map that shows nine services where two would do is not flagged as bad architecture — it just shows nine services.
- What happens at runtime. Nothing is executed, so load behaviour, real latency and what a specific user sees are outside its reach.
- What is not in the repository. A dependency configured only in a cloud console tends to show up as an unknown rather than as a component.
- Whether it is secure. A map is not a vulnerability scan and does not attempt to be.