Overview
A manifest is one file, architecture.yaml at the repository root, that describes your
repository as a tree of path patterns. You write each rule at the part of the tree it governs.
# yaml-language-server: $schema=https://dataquail.github.io/goodbones/schema/architecture.schema.jsonresolve: scopes: - files: "" language: typescript options: { tsconfig: tsconfig.json } unresolved: errorbaseline: .architecture-baseline.jsonaliases: { "@": packages/server/src, "~": packages }deny: []exports: []graph: {}limits: {}defs: {}tree: {}Top-level keys
Section titled “Top-level keys”| Key | Meaning |
|---|---|
resolve |
how an import specifier becomes a file — Resolution |
baseline |
path to the baseline file — Adoption |
aliases |
text shorthands expanded in every glob before matching |
deny |
import prohibitions that hold everywhere |
exports |
which importers may name a given exported symbol — Exports |
graph |
cycles, orphans and transitive reach over the whole import graph — Graph |
limits |
ceilings on the adoption backlog and conformance, floors on coverage — Adoption |
campaigns |
refactors in progress — Campaigns |
ledger |
the directory campaign ledgers are written to — Ledger |
defs |
named fragments, reused as { use: <name> } — Reuse and splitting |
tree |
the nodes |
With aliases: { "@": "packages/server/src" }, the glob @/modules/ means
packages/server/src/modules/. Any key, node or list item may be { include: <path> }
instead, read from another file.
A node
Section titled “A node”A key ending in / is a folder; anything else is a file.
"@/modules/{module}/domain/{subdomain}/": message: "domain/ holds the model for one subdomain." imports: { reset: true, external: [effect], allow: ["@/modules/{module}/domain/**"] } children: "*.root.ts": name: { like: "{subdomain}" } requires: ["{base}.root.test.ts"] "*.repository.ts": importedBy: message: "A repository is reached from a command handler." allow: ["@/modules/*/commands/**"] members: - message: 'A port method named "{name}" is a query in disguise.' subject: members declares: [type, interface] in: "*RepositoryShape" allow: [findOneById, save, delete] surface: - message: "A port exports its type and nothing else." declares: [variable, function, class]| Field | Question it answers | Page |
|---|---|---|
message |
what does this folder admit, and why? | |
imports |
what may this reach? | Imports |
importedBy |
who may reach this? | Imports |
members |
which names may it declare or call? | Members |
surface |
what may it export? | Surface |
name |
what may the variable part of a name look like? | Structure |
requires |
which sibling files does this file need? | Structure |
requiresNot |
which filenames skip that requirement? | Structure |
children |
which files and folders does this folder admit? | Structure |
partial |
apply policy here without listing every file | Inheritance |
layout |
open: admit any file name here |
Structure |
Every field is optional. An empty node, "*.root.ts": {}, admits the file and inherits
everything above it.
File formats
Section titled “File formats”Both hosts look at the repository root for, in order, architecture.yaml, architecture.yml,
architecture.json and architecture.config.mjs. Exactly one may exist. Set
ARCHITECTURE_CONFIG to use a file somewhere else. For the .mjs form, see
Reuse and splitting.
Put this first line in a YAML manifest to get completion and validation in your editor. A JSON
manifest uses a $schema key instead.
# yaml-language-server: $schema=https://dataquail.github.io/goodbones/schema/architecture.schema.jsonThe loader reports every error with its file, line and column:
architecture.yaml: the manifest does not decode: architecture.yaml:142:9 tree["~/core/"].members[0].subject: Expected "members" | "calls", got "call" architecture.yaml:201:7 tree["~/cli/"].imports.alow: Unexpected keyQuote every glob and every message in YAML. See Patterns.
Rule names
Section titled “Rule names”A rule is named after its node’s path: the top-level key slugified, then each child key as
written. An imports rule at "@/modules/{module}/" → "domain/{subdomain}/" reports as:
[modules-module/domain/{subdomain}/imports] domain/ holds the model for one subdomain.Top-level deny entries are named repo/deny-0, repo/deny-1, … in order.