Concepts
The words that the CLI, the checks and these docs use, each in one or two sentences. Learn them once and every command reads plainly.
An agent states what an architecture is through the CLI. Archboard stores that statement as files in your repository, draws it for the people who read it, and holds it to the code. The picture below is one such model, the example web shop, as Archboard draws it.
The example shop’s current architecture, drawn by archboard model render.
The model#
- Vault
The directory that holds one model,
.archboard/vaultat the root of a checkout. It is versioned with the repository, so a reviewer reads a change to it in the same diff as the code.- Model
The one architecture that a vault holds: its modules, relationships, flows, walkthroughs and active proposals. Every picture is a reading of it.
- Module
One architectural responsibility with a stable identity. A module can hold other modules, which are its parts when you open it. Containment has no fixed levels.
- Relationship
A directed connection that one module owns and that names another module as its target. It has a kind, such as
httporqueue, from the vault’s vocabulary.- Qualified identity
The stable identity of a module, relationship, flow or step, such as
Shop#Gateway. A rename keeps it, and a former name still finds it.- Reading
A selection of what to draw: the state, the scope, the open modules, the focus, the filters and the grammar. A reading copies nothing, so nobody authors one first.
Flows#
- Flow
One request, job or event told as an ordered exchange between modules. Its summary says what the exchange does and why it matters.
- Step
One thing that happens in a flow: a message with a kind (
sync,return,asyncorself), a decision with alternatives, or a loop.- Grammar
How a reading draws:
architecturedraws modules and relationships,sequenceandflowchartdraw one flow.
States and proposals#
- State
One identified architecture of the whole model. It is current, a draft, historical or shelved, and it keeps its identity through each change of lifecycle.
- Current
The state that describes the architecture that exists. A model has at most one. A planning model has none yet.
- Proposal
A draft state: a change that nobody has built yet, stored as changes against the state that it follows.
- Comparison
The differences between two states, by the identities of their subjects. Interface changes come first, because a change to an interface costs every caller.
- Adoption
Making a proposal the current state, with the reason. The old current state stays as history. A Git merge never adopts a proposal.
- Checkpoint
An exact retained copy of the model’s inputs, held in Git. A walkthrough or a recording that you share points at one.
- Claim
A writer’s visible hold on the subjects that it changes. Every pane shows who holds it and why, and a person can take it back.
Code and evidence#
- Binding
Where a module’s code is: a repository identity, a path and an optional symbol. It never stores an absolute path, so it resolves on every machine.
- Repository identity
The name a binding uses for a repository. It comes from the checkout’s
originremote, such asgithub.com/acme/payments.archboard repo addtells this machine where a checkout of it is.- Anchor
The one place in code that an author cites as proof of a relationship or a flow step. The code check holds it to the code.
- Evidence
What a piece of code or infrastructure proves about two modules: a call, a configured path, a permission, an import, a build dependency or provisioning.
- Configured path
Evidence across a network hop. Code reads an environment value, and the manifest, compose file or Terraform that runs the code sets it to another module’s address.
- Resolved and candidate
Resolved evidence names its target for certain, through a language server or the code itself. A candidate matches by name only, so a finding on it is information, never a warning.
Checks and findings#
- Semantics check
Reads the model against the vault’s own vocabulary and rules. It reads no code. Its errors and warnings are diagnostics.
- Code check
Compares what a state claims with the code and infrastructure that its bindings and anchors name. It reports findings with the evidence that they rest on.
- Embeds check
Reads each picture that the repository tracks against the model that it draws, and says which picture is outdated.
- Finding
One thing that the code check reports about a module, relationship or step. A warning fails the check. Information never does.
- Skip
Something that a check did not read, with the reason, such as a language with no server. A skipped subject never looks like a subject with nothing to report.
Sharing#
- Embed
An SVG or PNG that Archboard drew and that the repository tracks, for a README or an ADR. It carries its render recipe, so
archboard check embeds --fixdraws it again.- Walkthrough
An ordered tour of readings, each beat with a title and a narrative. The Codex voice can narrate it, and
model recordmakes a video of it.