docs: Score composition via refs, major architectural progress for simple yet type safe infrastructure component composition #342

johnride · 2026-07-15T17:59:10Z

johnride commented

2026-07-15 17:59:10 +00:00

Proposal to build loosely dependent but strongly typed infrastructure components using refs.

This means that a Zitadel score does not directly depend on a PostgreSQL score, but can be passed a PostgreSQLRef in its builder to know how to connect to it. This is much better than passing strings around as it allows for robust refactoring and extension to support new features without any risk of breaking string parsing in the consumer code.

I say loosely dependent because previous attempts were looking at dependency graphs and pipelines and the way they were envisioned forced much more inter-knowledge than an optional ref to a declarative desired state.

Also, a very important aspect of the refs is that they are not guaranteed to exist or have already converged when they are passed around. Just like kubernetes refs, they are eventually consistent and consumers should be resilient and handle eventual consistency themselves.

In my humble opinion, this is one of the things that kubernetes got fundamentally right : infrastructure is cahotic. You cannot expect an infrastructure component to be up, and even once it is up, it can go down anytime. A continuous convergence mechanism is the correct approach when drives fail, power goes out, buildings catch fire, etc.

The actual convergence mechanism is way out of scope of this p-r and ADR though, but passing around information as eventually consistent refs is a decision that makes sense in this consistency mode.

Proposal to build loosely dependent but strongly typed infrastructure components using refs. This means that a Zitadel score does not directly depend on a PostgreSQL score, but can be passed a PostgreSQLRef in its builder to know how to connect to it. This is much better than passing strings around as it allows for robust refactoring and extension to support new features without any risk of breaking string parsing in the consumer code. I say loosely dependent because previous attempts were looking at dependency graphs and pipelines and the way they were envisioned forced much more inter-knowledge than an optional ref to a declarative desired state. Also, a very important aspect of the refs is that they are not guaranteed to exist or have already converged when they are passed around. Just like kubernetes refs, they are eventually consistent and consumers should be resilient and handle eventual consistency themselves. In my humble opinion, this is one of the things that kubernetes got fundamentally right : infrastructure is cahotic. You cannot expect an infrastructure component to be up, and even once it is up, it can go down anytime. A continuous convergence mechanism is the correct approach when drives fail, power goes out, buildings catch fire, etc. The actual convergence mechanism is way out of scope of this p-r and ADR though, but passing around information as eventually consistent refs is a decision that makes sense in this consistency mode.

johnride added 1 commit 2026-07-15 17:59:11 +00:00

docs: Score composition via refs, major architectural progress for simple yet type safe infrastructure component composition

Run Check Script / check (pull_request) Successful in 1m56s

Details

69146e20e0

johnride added 1 commit 2026-07-15 19:40:31 +00:00

docs: Simplify and clarify the docs and adr around the refs, they are noop, stable and coherent with an eventually consistent system which k8s got right for the chaos of infrastructure

Run Check Script / check (pull_request) Successful in 2m0s

Details

5d7f9935cc

johnride added 1 commit 2026-07-15 21:55:56 +00:00

docs: Simplify and clarify further the score refs architecture, add progressive diagrams explaining the fleet reference architecture