NationTech/harmony
3
0
Fork 2
Code Issues 38 Pull Requests 16 Actions Packages Projects Releases 1 Wiki Activity

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

Open
johnride wants to merge 5 commits from docs/score-composition-via-refs into master
pull from: docs/score-composition-via-refs
merge into: NationTech:master
Conversation 0 Commits 5 Files Changed 140 +5935 -6725
johnride commented 2026-07-15 17:59:10 +00:00
Owner
Copy Link

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
All checks were successful
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
All checks were successful
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
All checks were successful
Run Check Script / check (pull_request) Successful in 1m53s
Details
2ad1911fac
johnride added 1 commit 2026-07-15 22:33:46 +00:00
docs: Add code samples and diagrams to score ref docs
All checks were successful
Run Check Script / check (pull_request) Successful in 1m55s
Details
b63de408f1
johnride added 1 commit 2026-07-16 21:56:16 +00:00
feat: establish Fleet lifecycle reference deployment
All checks were successful
Run Check Script / check (pull_request) Successful in 1m59s
Details
52df55447b
All checks were successful
Run Check Script / check (pull_request) Successful in 1m59s
Details
This pull request can be merged automatically.
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin docs/score-composition-via-refs:docs/score-composition-via-refs
git checkout docs/score-composition-via-refs
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
Architecture Decision Record
Good first issue
RFC
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
johnride jvtrudel reda stremblay
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: NationTech/harmony#342
No description provided.
Delete Branch "docs/score-composition-via-refs"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?