Architecture case studies
Four Classes of Having Built It
Workplace architecture, published honestly.
- Role
- Author
- Classification
- Reference implementation
Problem
A diagram can quietly imply you built it alone.
How it was solved
I measured authorship, sorted it into four classes and redacted the rest.
- Measure
- Classify
- Redact
- Publish
Result
22
diagrams, each with its authorship stated
Built with
- diagrams.net
- Mermaid
- SVG
- Git
Architecture case studies / Attribution
Publishing architecture from employer systems means describing work that was not all yours. What does an honest claim look like when the easy options are to say nothing or to say everything?
Authorship, measured and then judged4 classes
A measured share, and the class allowed to overrule it
This diagram in words
- Four workstreams source — One platform, drawn as the four streams of work across it.diagrams.net · Mermaid
- Measured commit share source — Counted per component rather than remembered.Git
- Authorship class gate — Four classes. The count informs them and does not decide them.
- Decision records artifact — Context, reason, trade-off and limitation, each written down.Markdown
- What is not claimed artifact — Stated before anyone has to ask for it.
- Published case studies sink — Generated, link-checked and screened for what may be shown.SVG
Read the full background
Problem
Why this work exists
Architecture from a workplace is the most useful thing an engineer can show and the hardest to publish honestly. Say nothing and the work is invisible; say it plainly and every diagram quietly becomes a claim of sole authorship over systems that teams built, with impact figures nobody measured attached to them.
Contribution
What I can claim
Produced the diagrams, the decision record and the evidence notes, and built the attribution discipline around them: every component carries one of 4 authorship classes, commit shares are measured rather than estimated, and the repository states plainly that a commit count is evidence of weight rather than of authorship - two of its classifications disagree with the counts on purpose and say so.
Method
Describing work that was not all yours
Architecture from a workplace is the most useful thing an engineer can show and the hardest to publish honestly.
- 466/498
- 144/167
- 123/148
- 77/94
- 0/56
The services are unnamed because their names are internal, and the shape is the point either way. A commit count is evidence of weight, not of authorship — two classifications in the repository disagree with these counts deliberately, and say so.
Not official documentation of those systems, and internal detail is generalised or omitted. The four lines above are the ones that keep everything else readable.
Draw
Four workstreams over one event-driven platform, diagrammed down to the stores and the gates.
Measure
So each component's commit share is taken with a named command on a stated date.
Overrule
A commit count measures weight, not authorship.
Attribute
Every component then lands in one of four classes, from primary implementation down to existing platform.
Decline
Finally, the things that will not be said: no production deployment, no impact metrics, no certification, no clinical claim.
What this does not show
This is not official documentation of the employer's systems, and internal detail is generalised or omitted - so a reader outside the organisation cannot check the diagrams against what they describe. Commit share is a weak proxy for contribution, and where it is overridden the classification rests partly on self-report. The services ran in development and QA only; no production environment exists, no business impact was measured, and the medical-imaging work is a research prototype with no device, clearance, validation or accuracy figure.
How it was built
System
Workflow and decisions
a verifiable legal knowledge base, the insurance AI compliance product it serves, document intelligence over insurance paperwork, a medical-imaging prototype with explainability - diagrammed across 22 architecture views, with the decision record and the evidence notes beside them. The companion to the case studies on this site rather than a duplicate of them: those describe what the systems do, this describes how they fit together and who built which part.
- 1Diagram 4 workstreams across one platform
- 2Measure the commit share of each component rather than recalling it
- 3Assign one of 4 authorship classes, overriding the count where the count misleads
- 4Write the decisions down as context, reason, trade-off and limitation
- 5State what is not claimed, before anyone has to ask
- diagrams.net
- Mermaid
- SVG
- Markdown
- Git
Evidence
What is actually versioned
primary implementation, significant contribution, integration and shared, existing platform. Commit shares were taken with git shortlog on 12 September 2026: first service 466 of 498, second service 144 of 167, third service 123 of 148, fourth service 77 of 94. The a fifth, for contrast appears at 0 of 56 and is classified as existing platform, which is what makes the rest of the list more than self-description.
no production deployment (the services ran as pods in Dev and QA; there is no production environment); no business impact metrics (none exist in any repository); no EU law certified (the parsers work; the assurance contract for them does not exist yet); no clinical claim (the imaging work is a research prototype: no device, no clearance, no validation, no accuracy figure). Each is a sentence that could have been written and was not, and together they are the reason the architecture around them can be read at face value.
22 architecture diagrams as SVG with 8 editable sources and 8 simplified Mermaid versions, 11 written design decisions, and a 12-slide deck. No code from the systems themselves: this is not official documentation of them, and internal detail is generalised or omitted.
How the work is checked
Quality controls
How the work is checked
- Every component carries an authorship class, so a diagram cannot imply sole authorship of a platform by being drawn well
- Commit shares are measured and dated rather than remembered, and the measurement command is named
- Where the count would mislead, the classification overrides it and the disagreement is stated rather than hidden
- A component with zero commits of mine is listed by name, which is what gives the other classifications their weight
- The non-claims are in the README rather than a footnote: no production deployment, no impact metrics, no certification, no clinical claim
Limitations
Where the evidence stops
- No code from the underlying systems is published, so the diagrams cannot be checked against the thing they describe by anyone outside it
- Commit share is a proxy for contribution and a poor one; the repository says so and overrides it twice, which also means the classification rests partly on self-report
- The systems ran as pods in development and QA. There is no production environment, so nothing here describes how any of it behaves under real load
- No business impact is claimed because none was measured. The absence is a fact about the organisation rather than a modesty
- It documents work at BP-ITCS and is not official documentation of it; internal detail is generalised or omitted, which necessarily limits how much a reader can verify
What this changed in my practice
What this changed in my practice
The hard part of publishing work from a job is not redaction, it is attribution. I could describe every one of these systems accurately and still leave a false impression, just by not saying who else was in the repository. Measuring the commit shares was easy; the useful part was deciding that two of them were wrong about authorship and writing down that I had overruled them.