> ## Documentation Index
> Fetch the complete documentation index at: https://developer.ubiquex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ubx Internals

> How ubx is built and why, for a human trying to understand the system.

This is the developer documentation for `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](https://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.

<CardGroup cols={2}>
  <Card title="Overview" icon="compass" href="/overview">
    What ubx is, the ledger-over-state-file thesis, and how it differs
    from Terraform and Pulumi.
  </Card>

  <Card title="Architecture" icon="route" href="/architecture">
    The trust chain from authoring to apply, why the execution layer
    speaks tfplugin directly, and failure semantics.
  </Card>

  <Card title="Concepts" icon="book-open" href="/concepts/proposal">
    Proposal, ledger, IR, resolver, executor, drift, cross-stack
    references, staleness, blueprints — one page each.
  </Card>

  <Card title="Schema Constitution" icon="scroll" href="/schema-constitution">
    The ratified canonical hashing rules — the most load-bearing thing
    in the project.
  </Card>

  <Card title="Repository Map" icon="diagram-project" href="/repository-map">
    What depends on what, across the 22 repos that make up the current
    system.
  </Card>

  <Card title="Provider System" icon="plug" href="/provider-system">
    The four real schema sources, why they converge before snapshotting,
    and the mixed-source dispatch layer AWS needed.
  </Card>

  <Card title="SDK and Codegen" icon="brackets-curly" href="/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.
  </Card>

  <Card title="Docs Pipeline" icon="file-code" href="/docs-pipeline">
    The artifact model, the coverage check, and the provenance
    enforcement that actually closed UBI-197.
  </Card>

  <Card title="Workflows" icon="repeat" href="/workflows">
    Update an SDK, update the docs, onboard a new provider — the three
    sequences this system actually runs.
  </Card>

  <Card title="Decisions" icon="scale-balanced" href="/decisions">
    Why things are the way they are — the one section that can't be
    reconstructed from code alone.
  </Card>

  <Card title="Conventions" icon="shield-check" href="/conventions">
    The rules and the real incidents that produced them.
  </Card>
</CardGroup>