Deterministic

@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:

Edges between nodes reflect what the reconstruction found:

• gateway → service edges are added for all decomposed services.
• service → database edges appear only when the route file itself contains a DB import or env var reference (not when DB access is hidden behind a shared utility module).

Node naming

DB and cache nodes use the most user-recognizable name available:

1. Env var name — process.env.REDIS_URL → node named "redis", process.env.SESSION_REDIS_URL → "session-redis"
2. Connection variable name — const userDb = new Pool(…) → node named "userDb" (for unique variable names)
3. Library / driver name — fallback when no env var or named variable is detectable

Node IDs and names never include env_var or other detection-method metadata.

External service identification

Outbound HTTP/gRPC calls create distinct external nodes per destination:

• axios.post('https://api.stripe.com/…') → node "stripe"
• fetch('https://auth0.com/oauth/token') → node "auth0"
• new PaymentServiceClient('payments-svc:50051') → node "payment" (gRPC)
• Generic fallback for clients without a detectable URL: one shared "external-service" node

Honest scope limits

Reconstruction is best-effort signal, not certainty:

1. Dynamic patterns — eval, reflection, metaprogramming, and generated code are not detected.
2. Runtime config — topology decisions made at runtime (feature flags, config-driven routing) cannot be statically analyzed.
3. Cross-language services — a single codebase containing multiple language runtimes reduces accuracy.
4. Heavy abstractions — macro-based or annotation-processor-heavy frameworks may obscure routes or co