An organisation publishes reference architectures that teams do not follow. What is the failure, and what would work?

The failure

A reference architecture is a document and teams need working code. The gap between a diagram showing the recommended shape and a running service is exactly the work the team was going to do anyway, so the reference saves them nothing and is skipped.

The second failure: it describes an ideal rather than a supported path. A reference that includes components the platform does not actually provide, or that has never been built end to end by anyone, is untested and will not work.

What would work

An executable reference: a template that generates a working service. Compliant, observable, deployable, with authentication, logging, metrics, a health check, a pipeline and a deployment configuration already present.

That is adopted because it is the fastest way to get started, which is enforcement without governance. The reference architecture then becomes the documentation of what the template contains, which is a much smaller and more accurate document.

What the template must include to be adopted

• A running service in one command, deployed to a real environment.
• The compliance and observability requirements already satisfied, so a team using it does not need to learn them.
• An escape hatch: the ability to opt out of one part without abandoning the whole, since a team with one unusual requirement should not be forced to start from scratch.
• Maintenance. A template that ages becomes a source of outdated services, so it needs an owner and a mechanism for propagating improvements to services already created from it — which is the hard part and is usually omitted.

What the reference document should still do

Explain the decisions and their reasoning: why this datastore, why this messaging pattern, when to deviate, what the trade-offs were. That content is stable and is what a team needs when their case does not fit — whereas the structural description is better expressed as code.

The measure

Adoption of the template, voluntary and measured. If teams are not using it, the template is worse than their alternative, and that is a product problem rather than a compliance problem.