ubx: architecture and internals,
written for a person trying to understand how the system is built and why
it works the way it does. It is a separate site from
docs.ubiquex.io, which is the user-facing
product documentation — install, concepts, tutorials, the CLI and SDK
reference.
The two mirror each other in spirit but serve different readers. The
per-repo CLAUDE.md/STATE.md files across the ubx codebase are
operational: short, current-state, answering what a session needs to know
before touching anything. This site is explanatory: longer-form, narrative,
answering why a given piece of the system exists and works the way it
does.
The canonical source for exact implementation detail — the full,
chronological build log, the schema constitution’s hashing rules, the
wedge plan, and the real source code itself — stays in the repo that
owns it, ubiquex and, where the story runs through it,
ubx-provider-dynamic. Pages here link out to that source rather than
duplicating it.
Overview
What ubx is, the ledger-over-state-file thesis, and how it differs
from Terraform and Pulumi.
Architecture
The trust chain from authoring to apply, why the execution layer
speaks tfplugin directly, and failure semantics.
Concepts
Proposal, ledger, IR, resolver, executor, drift, cross-stack
references, staleness, blueprints — one page each.
Schema Constitution
The ratified canonical hashing rules — the most load-bearing thing
in the project.
Repository Map
What depends on what, across the 22 repos that make up the current
system.
Provider System
The four real schema sources, why they converge before snapshotting,
and the mixed-source dispatch layer AWS needed.
SDK and Codegen
How a wire type’s name decides where its bindings land, and the
three real bugs that came from getting that wrong.
Docs Pipeline
The artifact model, the coverage check, and the provenance
enforcement that actually closed UBI-197.
Workflows
Update an SDK, update the docs, onboard a new provider — the three
sequences this system actually runs.
Decisions
Why things are the way they are — the one section that can’t be
reconstructed from code alone.
Conventions
The rules and the real incidents that produced them.