Reference Architectures Are Lying to You

Jordan — Sat, 09 May 2026 18:57:22 +0000

Every cloud provider has one. Every major consultancy sells one.
Every conference talk ends with one on the final slide.

Reference architectures are everywhere. And most of them are making your platform worse.

The problem with reference architectures

A reference architecture is a idealised blueprint for how a system should be structured. In theory, it gives teams a proven starting point, reduces decision fatigue, and encodes best practices from organisations that have already solved the hard problems.

In practice, most organisations use them wrong. They treat the reference architecture as the destination rather than the starting point. They adopt the full stack because the diagram says so, not because they have validated that each component solves a problem they actually have. They optimise for looking like the reference architecture rather than optimising for what their developers actually need.

The result is platforms that are architecturally impressive and operationally painful. Teams running service meshes they do not need. Organisations operating multi-cluster Kubernetes setups at a scale that does not justify the overhead. Platform teams spending more time maintaining the architecture than delivering value through it.

Where reference architectures come from

It is worth understanding what a reference architecture actually represents before adopting one.

A cloud provider reference architecture represents what is possible on that provider's platform, optimised for showcasing their services. It is not a neutral recommendation. It is a product catalogue with arrows between the boxes.

A consultancy reference architecture represents what worked at the clients that consultancy has served, filtered through the biases and preferences of the people who designed it. It may be excellent. It may also encode decisions that made sense in a context completely different from yours.

A CNCF reference architecture represents the consensus view of a community with strong opinions about open source tooling. That community is smart and well-intentioned. It is also not operating your platform or accountable for your on-call rota.

None of these are wrong. All of them require translation before they are useful to your specific organisation.

What to do instead

Start with the problems your developers are actually experiencing, not with the architecture you want to build toward.

If the problem is inconsistent deployment practices across teams, you need a CI/CD opinion and a way to enforce it. You may not need a service mesh, a service catalogue, and a full GitOps implementation on day one.

If the problem is slow onboarding for new teams, you need a repeatable path from zero to first deployment. You may not need a sophisticated internal developer platform before you have validated what that path should look like.

Use reference architectures as a map of the territory, not as a set of instructions. They tell you what exists and what is possible. They do not tell you what you need right now, in what order, or at what cost.

The question worth asking

Before adopting any component from a reference architecture, ask one question: what specific problem does this solve for the engineers who will have to operate it?

If you cannot answer that question concretely, the component is not ready to be adopted. It is being adopted because it is on the diagram.

The best platform architectures I have worked with look nothing like the reference architectures they started from. They look like the specific, considered,incrementally
validated answers to the specific problems that organisation
faced.

That is harder to put on a slide. It is also the only version that actually works.

This is one of the themes I explore in
The Comprehensive Guide to Platform Engineering, particularly around how platform teams make and sequence architectural decisions in practice rather than in theory.
Free sample at Platform Engineering Guide Sample if you want to get a feel for the depth before committing.

Why Most Internal Developer Platforms Fail (And What To Do About It)

Jordan — Wed, 06 May 2026 11:08:29 +0000

I've spent twenty years building and scaling platforms across financial services technology. In that time I've seen internal developer platforms succeed and I've seen them fail. The technical differences between the successes and the failures are smaller than you'd expect.

The organisational differences are enormous.

The adoption problem nobody talks about

Most IDP failures share a common characteristic: the platform team
treated adoption as inevitable rather than earned.

The assumption goes like this, if we build something genuinely better
than what exists, developers will naturally migrate to it. This is
rarely true. Developers are busy, sceptical of platform initiatives
based on past experience, and rational about where they invest their
time.

The teams that get adoption right treat the platform as a product with a go-to-market problem. They identify a first team, make that team successful, and let word of mouth do the rest.

The metrics that actually matter

The industry has converged on DORA metrics as the standard for
measuring engineering performance. They're useful and worth tracking.
But they measure outputs, not platform health.

A platform can have strong DORA metrics and still be quietly failing.

The metrics I've come to care about most:

Time to first deployment for a new team. Not a team that's been
on the platform for two years — a new team starting fresh. If this
is measured in days rather than hours, the platform has an onboarding
problem that deployment frequency won't reveal.

Unplanned dependency rate. How often do developers go outside the
platform to get something done? Every workaround is a product signal.

Platform team toil ratio. What percentage of time is reactive
versus proactive? If this isn't improving quarter on quarter, the
platform is treading water.

Developer NPS. Uncomfortable to measure. Impossible to argue with.

The documentation trap

Platform teams that rely on documentation to drive adoption have
already lost.

If developers need to read three Confluence pages to understand how
to deploy a service on your platform, the platform has a usability
problem. The documentation is papering over the gap between what the
platform is and what it should be.

When I hear a platform team say "we need better documentation," I now
ask a different question: what specifically are developers confused
about, and why does the platform not make that thing obvious?

The answer to that question is a product improvement. Not a new
Confluence page.

Where this comes from

These are some of the themes I explore in depth in
The Comprehensive Guide to Platform Engineering a 550-page practitioner reference I've just published covering the full platform engineering lifecycle, from Kubernetes and GitOps through to IDPs, AI-native infrastructure, and the organisational change required to make any of it stick.

Happy to discuss any of this in the comments, I'm particularly interested in what others are seeing around IDP adoption in practice.

Forem: Jordan