slartiarch

Slartibartfast: the architect. From The Hitchhiker's Guide to the Galaxy, the curmudgeonly designer of Norway's fjords — and the namesake of this tool.

slartiarch is a coordination CLI that checks consistency between LikeC4 architecture diagrams, LinkML schemas, and SHACL shapes. It also regenerates the diagrams in your architecture document so the prose never drifts.

Each tool is useful on its own with no slartiarch involved. slartiarch adds the seams — rules that span two tools, and checks that the answers still agree.

Install

uv tool install slartiarch
npm install likec4

Use

slartiarch init          # scaffold docs/slarti/ and a config
slartiarch doctor        # resolved paths and tool versions
slartiarch check         # run all validations (CI command)
slartiarch check --json  # structured output for automation
slartiarch docs          # regenerate diagrams and tables into your docs
slartiarch docs --check  # fail if committed output is stale
slartiarch report        # every rule, shape, and check ID
slartiarch report --json # fully detailed, for agents

Run slartiarch with no arguments for a full reference. slartiarch report --json describes every rule, enforcer kind, check ID, and remedy.

Layout

docs/
  architecture.md      prose with generated diagram and table regions
  diagrams/            GENERATED — never hand-edited
  slarti/
    likec4/*.c4        LikeC4 architecture model
    linkml/*.yaml      LinkML domain schemas
    shacl/*.ttl        hand-written SHACL shapes
    constraints.yaml   rule registry
    data/valid/*       fixtures that must pass validation
    data/invalid/*     one fixture per SHACL rule; each must fail

How the tools work together

LikeC4 draws the system. LinkML defines the entities. SHACL validates instances. Each works standalone:

likec4 start docs/slarti/likec4                  # live architecture browser
gen-pydantic docs/slarti/linkml/slarti.yaml       # Python interfaces from schema
pyshacl -s docs/slarti/shacl/invariants.ttl ...   # validate RDF against shapes

A constraint in the registry ties them together:

# docs/slarti/constraints.yaml
- id: D8
  statement: A subtask belongs to the same list as its parent.
  enforced_by:
    kind: shacl_shape
    ref: "todo:SubtaskSharesListWithParent"
    fixture: docs/slarti/data/invalid/D8.yaml

Running slartiarch check walks the seams: it verifies the shape exists, the fixture fails (proving the shape fires), both halves of the ownership claim agree, and the constraint table in your document still matches. slartiarch docs regenerates the Mermaid diagrams and tables so the architecture document never goes stale.

Dogfooding

This repository's docs/architecture.md is generated by slartiarch from docs/slarti/. CI runs slartiarch check and slartiarch docs --check.

Dev

make setup   # uv venv + sync
npm ci       # pinned LikeC4
make domain  # regenerate slarti/domain.py from the LinkML schema
make ci      # tests, lint, types, complexity, duplication, dead code

Architecture decisions live in docs/adr/.