arc42-language

Architecture was something only architects cared about. Developers read the docs. Hopefully. Once. At the start. Then reality kicked in — and the docs stayed behind.

Architecture drift has always existed. Agents just made it worse: change accelerates, docs don't.

arc42-language makes architecture a first-class citizen — readable by humans, checkable by machines, visible to agents.

or see a live demo of a sample architecture of a bookstore by running

git clone https://github.com/docToolchain/arc42-language.git
cd arc42-language
npx @doctc/arc42 --dir examples/bookstore-backend serve

In the browser, arc42 serve renders the architecture as readable chapters, with every element, relation and decision one click away:

(video · recorded by pnpm --filter @arc42/web demo)

Architecture changes with every commit — arc42 serve --diff shows how: changes inline in their chapters, only the changed words marked, lint warnings linked to their elements, and a history with one pearl per commit.

(video · screenshots · recorded by pnpm --filter @arc42/web demo:diff)

A structured language for arc42 software architecture documentation. Human-readable first — Markdown prose with typed :::block fences for structured metadata. Machine-verifiable second — a CLI validates consistency and coherence across all elements.

• Write architecture documentation in plain Markdown (.arc42.md files)
• Embed structured elements — quality goals, solution strategy, building blocks, interfaces, runtime scenarios, concepts, decisions — as typed blocks alongside narrative prose
• Validate that your architecture model is internally consistent: no broken references, no isolated components, no unaddressed quality goals, no forgotten proposed decisions
• Query the model from the command line or pipe JSON into other tools

Each element lives in its own section: heading, prose explaining purpose and rationale, then the block as the machine-readable summary.

Example:

## Catalog Service

Owns all product data. The only service that writes to the catalog database.
Search results are cached in Redis to meet the p95 latency target.

```arc42
:::building-block
id: bb-catalog-service
title: Catalog Service
technology: Node.js / Express
implements: concept-logging, concept-error-handling
path: packages/catalog-service
:::
```

The block types cover the main arc42 sections. See the starter templates surfaced by `arc42 guide chapter <n>` for ready-to-use files, one chapter at a time. See `examples/bookstore-backend/` for a complete, valid workspace with realistic prose.

### The CLI

```bash
# Install globally
npm install -g @doctc/arc42

# Or run without installing
npx @doctc/arc42 validate --dir ./docs

# Install the arc42 agent skill (works with Claude Code and ~80 other agents)
npx skills add doctoolchain/arc42-language

# Discover commands and their purpose
arc42 --help

# Read usage, options, defaults, and exit behavior for one command
arc42 validate --help
arc42 --help diff

# Validate the workspace — fix all errors before committing
arc42 --dir ./docs validate

# Review unstaged working-tree changes against the index
arc42 diff

# Review working-tree changes against a specific base commit
arc42 diff origin/main

# Explicitly review the index, equivalent to git diff --cached
arc42 diff --staged

# The --cached alias and reference form match Git as well
arc42 diff --cached origin/main

# Review the changes of the current branch, as in a pull request
arc42 diff origin/main...HEAD

# Machine-readable findings plus the semantic change set (elements, relations, diagrams, prose)
arc42 diff origin/main...HEAD --format json

# See a difference rendered in the browser: live for uncommitted changes …
arc42 serve --diff
# … or as a static review site for a pull request
arc42 build --out review --diff origin/main...HEAD

# Browse the architecture history — every commit that changed the architecture, each
# one's change and its whole architecture — in `arc42 serve`, or include it in a static site
arc42 build --out site/docs --with-history

# Everything in one self-contained HTML file (also works opened from disk)
arc42 build --out review --diff origin/main...HEAD --with-history --single-file

# Show all diff modes, options, and pre-commit guidance
arc42 diff --help

# The command reports findings with file and line references; use Git directly
# when the surrounding diff is needed.

# A failed consistency check prints the exact base SHA needed for acceptance.
# For a pre-commit check, review the index with --staged:
# ARC42_CONSISTENT=<base-sha> arc42 diff --staged

# Browse all elements grouped by arc42 chapter
arc42 --dir ./docs get

# Inspect a single element with its 1-hop relationships
arc42 --dir ./docs get bb-catalog-service

# Filter by type
arc42 --dir ./docs get --type decision

# Understand what each validation rule enforces and why
arc42 rules

# JSON output for scripting and agent use
arc42 --dir ./docs validate --format json
arc42 --dir ./docs get --format json
# Validate implementation links against an explicit repository root
arc42 --dir ./docs --root . validate

--dir defaults to $ARC42_DIR or the current directory. path is optional on building-block and interface blocks and points to a file or directory relative to the repository root. Missing paths are hints; paths that do not resolve are errors. Use --root to override automatic repository-root detection (Git root, then --dir, then the current directory). Exit codes: 0 = no errors, 1 = validation errors or element not found, 2 = usage error. Run arc42 --help for a command-purpose overview and arc42 <command> --help for command-specific usage. Help is also accepted before the command, for example arc42 --help validate.

The validator enforces built-in rules across four categories. Run arc42 rules to see each rule with its rationale. The short summary:

• Errors (broken model): duplicate ids, unresolved references, circular parent chains, interface pointing at non-building-blocks, missing required attributes
• Warnings (inconsistencies): orphaned concepts, isolated building-blocks, stale proposed decisions, blocks without prose, multiple blocks under one heading
• Hints (gaps): decisions or solution strategies without quality-goal links, quality goals without decisions or a solution strategy, building-blocks without a technology

Run npx skills add doctoolchain/arc42-language in the project root. It installs the bundled SKILL.md for whichever agent runtime you're using and orients the agent to the format, instructing it to keep the arc42 files in sync with every architectural change.

The codebase is a pnpm monorepo with two packages:

packages/
  core/   — pure TypeScript library: parser, model, validator, renderer
  cli/    — thin CLI entry point, delegates everything to core
  skill/  — SKILL.md for opencode agent integration (no code)

The pipeline for every command:

discoverFiles(dir)
  → MarkdownParser.parse()        — line-oriented, :::type fences
  → buildWorkspace(documents)     — typed element model + parse errors
  → buildIndex(workspace)         — bidirectional reference index
  → validate(workspace, index)    — builtinRules.flatMap(r => r.check())
  → renderers / CLI output

• TypeScript 5.x with strict mode
• pnpm workspaces
• vite-plus (vp) — unified toolchain: vp pack (build), vp test (Vitest), vp check (lint + types)
• No runtime dependencies beyond Node.js built-ins

pnpm install
pnpm run build   # build core + cli
pnpm run test    # run all tests
pnpm run check   # lint + type-check
pnpm run ready   # check + test + build in one pass

Rules every *42 language has (codes EGxx, WGxx: duplicate ids, parse errors, prose and structure conventions, ignore directives) come from @cli42/lib/rules; arc42's own rules use plain codes (E002, W001, H001, …).

1. Create packages/core/src/validator/rules/<code>-<name>.ts — implement the Rule interface
2. Fill in meta.docs.rationale — explain why the rule exists, not just what it checks
3. Register it in packages/core/src/validator/rules/index.ts
4. Add unit tests in packages/core/tests/validator.test.ts
5. If the rule needs the raw AST (not just the element model), use workspace.documents — see the generic rules WG02/WG03 of @cli42/lib/rules for examples

The Rule interface is ESLint-inspired: a self-describing meta object and a check(workspace, index) function. arc42 rules exposes the full registry to CLI users and agents.

• Flat hierarchy with parent: references — building-block decomposition is modelled as a flat list with parent pointers, not nested blocks. Simpler to parse, simpler for agents to write.
• Parser stays dumb — the parser emits all block types including unknown ones. The meta-model builder rejects unknowns with EG02. This keeps the parser stable as new block types are added.
• Same pipeline for all commands — validate, get, and rules all run the full discover→parse→build→index pipeline. No caching in v1.
• Rule registry — each rule is a self-describing object. arc42 rules is a free by-product. Rules are composable and independently testable.
• Workspace.documents[] — structure-aware rules (WG02, WG03) need the raw AST to scan node sequences. The workspace carries the parsed documents for this purpose.

docs/arc42/ contains the arc42 documentation for arc42-language itself — quality goals, building blocks, concepts, and decisions, all written in the DSL this toolchain validates.

pnpm run validate:docs   # validate the project's own arc42 docs
pnpm run validate:all    # validate docs + examples

pnpm install
pnpm run build          # builds core + cli

# Install git hooks (pre-commit: lint + arc42 diff; pre-push: full validate)
pnpm run hooks:install