Skip to content

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.json
resolve:
scopes:
- files: ""
language: typescript
options: { tsconfig: tsconfig.json }
unresolved: error
baseline: .architecture-baseline.json
aliases: { "@": packages/server/src, "~": packages }
deny: []
exports: []
graph: {}
limits: {}
defs: {}
tree: {}
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 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.

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.json

The 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 key

Quote every glob and every message in YAML. See Patterns.

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.