career bridge
The reference architecture
Design interfaces rather than implementations, write down what you are deliberately not deciding, and name your own failure modes.
You have one decision made and documented. Now design the thing several teams will build on, which is a different discipline from designing something that works. It has to hold for people who will never read your document and will not think to ask you first.
What you do
Design interfaces rather than implementations, and write down what you are refusing to decide. Specify the shared capability as a contract: what a team sends, what comes back, what guarantees hold, and what explicitly does not. Then state the parts you are deliberately leaving open, because an architecture that decides everything gets worked around and one that decides nothing is just a diagram. Pick the three or four things that genuinely must be central, usually data access, cost accounting, audit logging and model access, and let the rest be each team's own business. For every central decision write the one sentence saying why it cannot be local. Then design the boring parts properly, because they determine whether any of this survives. How does a team get access on day one, and how long does that take? What happens when the shared thing is down, and what does a dependent team do meanwhile? Who pays, and how is that measured? Where do logs go, and who may read them? Finish by writing the failure modes of your own design into the document. An architect who names the weaknesses gets trusted with the next one.
Done when
- The shared capability is specified as a contract: inputs, outputs, guarantees, and explicit non-guarantees.
- Three or four central decisions are named, each with one sentence on why it cannot be local.
- What you leave to individual teams is written down as a decision rather than left implied.
- Onboarding, outage behaviour, cost attribution and log access are each specified.
- The document names the weaknesses of your own design.
What you end up with
A reference architecture written as a contract, with central decisions justified, local ones left open on purpose, and its own failure modes named.
If you get stuck
The common failure is boxes and arrows with no contract, which every team reads differently and then implements differently. If two teams could build incompatible things from your document, it is a picture rather than an architecture. The second failure is centralising everything because it looks tidier. Every central decision is a queue you now own, and queues are how a platform becomes the thing people route around.