@archrad/deterministic

Your architecture drifts before you write a single line of code. archrad validate catches it — deterministically, in CI, before the PR merges.

Define your system as a graph. ArchRAD compiles it, lints it against architecture rules, and tells you exactly what's wrong — with rule codes, not opinions.

New in 0.7.x — archrad demo runs a full example with zero setup, and archrad scan drafts an IR from any repo with every node cited to file:line. Lint findings only decrease in this release; nothing that passed on 0.6.x can start failing. See the changelog.

Quick start (60 seconds)

npm install -g @archrad/deterministic
archrad demo

No IR file, no flags, no config — runs from any directory. Lints a bundled example and shows you the findings:

    orders-api (http)  ──▶  orders-db (postgres)

⚠️ IR-LINT-DIRECT-DB-ACCESS-002: API node "orders-api" connects directly to datastore node "orders-db"
   Fix: Introduce a service or domain layer between HTTP handlers and persistence.
⚠️ IR-LINT-MISSING-AUTH-010: HTTP entry node "orders-api" has no auth node or auth config …
⚠️ IR-LINT-NO-HEALTHCHECK-003: No HTTP node exposes a typical health/readiness path …

Then run it on your own repo

archrad scan . --out draft.ir.json    # draft an IR — every node cited to file:line
archrad validate --ir draft.ir.json   # lint it

scan reads your Docker Compose, Kubernetes manifests, Terraform, OpenAPI, package manifests, and source code, then grades every node by confidence so you can see what was parsed versus guessed. The output is a normal IR file — review it, edit it, commit it.

Already have an OpenAPI spec or a Backstage catalog? Skip the scan:

archrad ingest openapi --spec ./openapi.yaml --out ./graph.json
archrad ingest backstage --catalog . --out ./graph.json

Once a graph is committed, archrad validate is your CI gate — exit 1 blocks the merge.

What it does

ArchRAD is a blueprint compiler and governance layer. You define your architecture as an IR — nodes, edges, allowed connections — and ArchRAD validates it against a deterministic rule engine. The same IR, the same rules, the same inputs always produce the same findings.

Ingest + merge workflows: docs/INGEST.md. All commands / flags: docs/CLI_REFERENCE.md. Codegen (export): docs/EXPORT.md.

Draft an IR from a real repo (archrad scan)

archrad scan points at a repository and emits a draft IR — never a final answer, always something to review and edit. It runs six extractors, graded by how much they have to guess:

Every node and edge carries config.provenance[] — inferred_from: "file:line", a confidence, and which extractor found it — so nothing has to be taken on faith. When two extractors describe the same thing, scan merges them (keeping the highest-confidence body, unioning all provenance) instead of duplicating or erroring.

archrad scan . --dry-run                       # print the draft, write nothing
archrad scan ./server --out draft.ir.json       # write it
archrad scan . --extractors compose,manifest    # only run specific extractors
archrad scan . --scope all                      # include tests, examples, docs, and demos

CLI scans default to --scope production so fixtures, documentation examples, Storybook stories, and test-only manifests do not become production findings. Use --scope all when those artifacts are the subject of the review. Library callers retain the backwards-compatible scope: 'all' default.

The output is a normal IR file — pipe it straight into archrad validate once you've reviewed it. Full flags: docs/CLI_REFERENCE.md.

Implementation governance (archrad reconstruct + --codebase)

"The IR looks clean — but is that what was actually shipped?"

The validation pipeline above checks your authored IR (the design contract). The --codebase flag bridges the gap to the real codebase by reconstructing an IR from source code and comparing them.

The "dummy IR" attack — and how to catch it

A developer can author a compliant IR (passes all IR-STRUCT-* and IR-LINT-* rules) while the actual code bypasses the documented architecture. The most dangerous pattern: an IR that shows a clean service layer but code that directly queries the database.

# Catch discrepancies between the authored design and the shipped code
archrad validate --ir authored-ir.json --codebase ./src --report findings.html

When --codebase is provided, the pipeline runs three stages:

1. IR-STRUCT-* structural validation on the authored IR
2. IR-LINT-* architecture lint on the authored IR
3. IR-DRIFT-IMPL-* comparison of authored IR vs reconstructed codebase IR

IR-DRIFT-IMPL-* rules

Implementation drift uses a separate exit threshold: --fail-on, --fail-on-warning, and --max-warnings apply only to IR-STRUCT-, IR-LINT-, and merged PolicyPack findings. IR-DRIFT-IMPL-* are gated solely by --impl-drift-fail-on (default: drift severities error fail the command).

IR-DRIFT-IMPL-003 is the critical one. An error there means the authored IR hides a direct DB dependency.

Reconstruct standalone

# Just reconstruct — write the IR without comparing
archrad reconstruct --from ./src --output reconstructed-ir.json

# Force language detection
archrad reconstruct --from ./src --language python --output py-ir.json

# Print to stdout (dry-run)
archrad reconstruct --from ./src --dry-run

# Show every detected artifact
archrad reconstruct --from ./src --verbose

Supported languages

Service decomposition (Node.js)

The reconstructor detects service boundaries and creates one node per service rather than collapsing everything into a single gateway: