Good decisions can only be made with accurate facts.
How do we keep accurate facts about our software?
This is an industry story, not ours alone.
Part one
Facts.
Then the problem they point to.
Part one · Facts
Good decisions can only be made with accurate facts.
Our software is connected: a change in one place reaches others.
A machine checks a rule the same way every time. People don’t.
AI works only from what it’s given: wrong facts become wrong decisions, faster.
So we need accurate, trusted facts about our software, kept accurate.
Part one · The problem
No one can just ask.
Every change starts half-blind.
Part one · The problem
Too big for people alone.
This problem can be solved by making people better at what people are better at.
Part two · a proposal
A model of accurate facts.
The proposal
One model. Every component, every relationship.
The proposal
What the facts are.
Componentsan inventory of everything we run
Levelswhere each one sits, from a whole system down to its code
Relationshipshow they connect
Get these right and we understand our software.
The proposal
Useful gets used.
The parts · 1 of 5
1
C4: a shared shape and zoom levels.
Where the inventory, the levels and the relationships are written down, as code.
Four levels: system, container, component, code.
The parts · 1 of 5
C4
Why this
What it costs
What it solves
Connected systems need one shared way to write down what exists, where it sits and what it connects to.
Four levels won’t capture every nuance — and teams must learn and agree them.
One written inventory of components, levels and relationships, read the same way by everyone.
The parts · 2 of 5
2
Code & compiler: precision.
Rules that make wrong entries impossible to write.
Checks every time. One meaning, no ambiguity.
The parts · 2 of 5
Code & compiler
Why this
What it costs
What it solves
A machine checks a rule the same way every time. Wrong entries cannot be written.
Rigid: it can’t interpret intent — and someone has to set the rules.
No more checking rules by hand — and an exact answer to “what does this affect?”
The parts · 3 of 5
3
Git: history and accountability.
Who changed what, when and why.
Reviewed and approved before it counts — and we can always go back.
The parts · 3 of 5
Git
Why this
What it costs
What it solves
Every change has an author, a reason and a reviewer — and you can see what was true on any date.
It records any change, right or wrong — and review takes people’s time.
A reliable record of who changed what, when, and why.
The parts · 4 of 5
4
Agents: understanding and translation.
Perhaps their biggest strength: the view that suits you.
The reverse: say what, not how.
They translate both ways — and are never the source of truth.
The parts · 4 of 5
Agents
Why this
Why AI alone isn’t enough
What it costs
What it solves
Each person gets the facts in the form that suits their understanding — and can ask for change in their own words.
Agents alone, no modelWrong facts, wrong decisions — faster.
No AI at allSlow, tiring work; wastes what the framework built.
Skills aloneHow we work, not what’s true.
Can be confidently wrong — so never trusted alone, always checked.
Understanding for everyone, not just experts — and changes asked for in plain terms.
The parts · 5 of 5
5
People: judgement.
Someone accountable decides what’s right.
Ownership and sign-off, by the right people.
The parts · 5 of 5
People
Why this
Why people still decide
What it costs
What it solves
Code can’t decide what the rules should be, and agents can be confidently wrong. Someone accountable has to decide.
Let the machine decideIt checks rules; it can’t say what’s right.
Let the AI decideFast, but confidently wrong at times.
No clear ownerNo sign-off, no accountability.
Review and judgement take people’s time — the slow part, on purpose.
Every change, and every difference found, has an accountable owner.
Together
Five parts. Some you know well, some you may not.
We already have everything we need, except the model. This is about composing what we own.
Here’s what they do together.
Together
How it fits together.
Every scenario that follows is a path through this.
Together
One shape inside. Any shape outside.
Scenario 1 of 6 · the ask
Ask ↵
Landscape
All our systems
Scenario 1 of 6 · behind the scenes
Behind the scenes.
No canonical model: there’s nothing to zoom into. It couldn’t be done.
No compiler: a box at one level could be missing from the next.
No agent: you’d need to know exactly where to look.
Now possible. Now assured.
Scenario 2 of 6 · the ask
Ask ↵
Landscape
All our systems
Scenario 2 of 6 · behind the scenes
Behind the scenes.
No canonical model: no single answer. It couldn’t be done.
No agent: you’d have to write the query yourself.
No compiler: the list could miss something.
No person: no one accountable for the decision.
Now possible. Now assured.
Scenario 3 of 6 · the ask
Ask for the change the way you think of it.
Ask ↵
Checked by the rules. Approved by a person. Recorded.
Scenario 3 of 6 · behind the scenes
Behind the scenes.
No agent: the change couldn’t be made from a plain request.
No compiler: a wrong entry gets in.
No person: no one accountable.
No git: no record of who changed it.
No canonical model: nowhere for the change to live.
Now possible. Now assured.
Scenario 4 of 6 · the ask
Ask ↵
From
To
What
Customer Channels
Payments System
Makes payments
Payments System
Accounts System
Debits and credits
Payments System
Notifications
Sends alerts
Payments System
Partner Bank
Sends payments
Payments System
Customer Channels make payments through it.
It debits and credits the Accounts System.
It sends alerts through Notifications.
It sends payments to the Partner Bank.
Scenario 4 of 6 · behind the scenes
Behind the scenes.
No canonical model: every view holds its own facts. They couldn’t agree.
No agent: every new view is a new build.
Now possible. Now assured.
Scenario 5 of 6 · the ask
Any date. Every change has a name on it.
Ask ↵
14 April 2026 · added Fraud Check and two relationships Author: Payments team · Reviewed and approved by: the Payments owner Reason: screen every payment for fraud
Scenario 5 of 6 · behind the scenes
Behind the scenes.
No git: no record of who changed it, or what was true then.
No canonical model: nothing to rebuild the past from.
No person: no name on the change.
Now possible. Now assured.
Scenario 6 of 6 · the ask
Ask ↵
Scenario 6 of 6 · behind the scenes
Behind the scenes.
Still possible without the model. With it, more accurate: the code is checked against the architecture.
Now more accurate. Now assured.
The difference
Foundations first. Everyone’s a mapper.
What will always be true?
Good decisions can only be made with accurate facts.