DEV Community: Archrad

ArchRad 0.3.0 — Two commands to find architecture violations in your existing stack

Archrad — Fri, 17 Apr 2026 00:18:34 +0000

All our early release of ArchRad has assumed one thing: that you already have an IR graph of your system to validate. You needed to author JSON by hand, learn the schema, map your services yourself before you could see a single violation.
Based on the feedback, we have addressed that issue with release 0.3.0.

The cold start problem

The feedback we kept hearing — from developers who found ArchRad on npm, from platform engineers who tried it in CI — was always the same: the first step is too hard. Before you could run archrad validate, you had to write an IR graph. Before you could write an IR graph, you had to understand the schema. Most people never got that far.

That's the cold start problem. And archrad init is the fix.

archrad init — zero hand-authored JSON

archrad init generates a valid IR graph from artifacts you already have. Starting with Docker Compose.

archrad init --from docker-compose.yml --output graph.json
archrad validate --ir graph.json

Two commands. No JSON authoring. No schema learning. If you have a docker-compose.yml, you can see your architecture violations in under 60 seconds.

Every service in your Compose file becomes a node in the IR graph. The node type is inferred from the image:

Image pattern	node.type
postgres, mysql, mariadb, timescale, cockroach	`postgres`
redis, memcached	`cache`
rabbitmq, kafka, nats, pulsar	`queue`
nginx, traefik, caddy, kong, envoy	`gateway`
elasticsearch, opensearch	`search`
minio, localstack	`storage`
unknown image + published ports	`gateway` (HTTP-facing fallback)
unknown image, no ports	`service` (with warning)

depends_on → edges

Both list and object forms are supported. Each dependency becomes a directed edge in the IR graph.

Connection URL detection

This is where it gets interesting. If a service has a DATABASE_URL, REDIS_URL, AMQP_URL, MONGODB_URI, or any of eight other connection URL environment variables, and the hostname in that URL matches another service in the compose file — archrad init creates an edge.

This is how it catches direct database access automatically. You didn't have to tell it. It found it in your existing configuration.

services:
  api:
    image: my-company/api:latest
    environment:
      DATABASE_URL: postgres://postgres:5432/mydb
    depends_on:
      - postgres
  postgres:
    image: postgres:15

Running archrad init on this file creates:

Two nodes: api (service), postgres (postgres type)
Two edges: api → postgres from depends_on, and api → postgres from DATABASE_URL

Running archrad validate on the resulting IR fires IR-LINT-DIRECT-DB-001. The API is calling the database directly. That is a finding.

Verbose mode

Use --verbose to see exactly what was inferred:

archrad init: mapping:
  api            service   (image: my-company/api:latest)
  postgres       postgres  (image: postgres:15)
  redis          cache     (image: redis:7-alpine)
  → api → postgres  edge  (depends_on)
  → api → postgres  edge  (DATABASE_URL)
  → api → redis    edge  (depends_on)
archrad init: summary: 3 nodes, 3 edges, 0 warning(s)

Everything else that shipped in 0.3.0

archrad yaml-to-ir — now accepts HTTPS URLs

--yaml now accepts a GitHub raw URL or any HTTPS URL, with optional -H for authenticated fetches. Validate a blueprint hosted in your GitHub repo without downloading it first.

archrad yaml-to-ir \
  --yaml https://raw.githubusercontent.com/your-org/blueprints/main/api-gateway.yaml \
  --out graph.json

The lint rules that matter for platform engineers

ArchRad ships 11 deterministic lint rules. The ones that fire most often in real-world systems:

IR-LINT-DIRECT-DB-001 — A service is calling a database directly, bypassing the service layer. This is the rule that fires when DATABASE_URL in your compose file points straight to postgres with no service in between.

IR-LINT-MISSING-AUTH-010 — An HTTP entry point has no auth boundary. No auth node, no middleware, no config.authRequired: false to document the intentional decision. This fires on every unauthenticated endpoint in the Petstore.

IR-LINT-MULTIPLE-HTTP-ENTRIES-009 — Multiple HTTP entry points with no gateway in front. Common in microservice-first architectures before a BFF or API gateway is introduced.

IR-LINT-NO-HEALTHCHECK-003 — No health or readiness endpoint defined. Kubernetes, ECS, and any load balancer needs this.

IR-LINT-DEAD-NODE-011 — A node with no inbound or outbound edges. Orphaned service, probably left over from a previous topology.

All rules are deterministic. No LLM in the validation loop. Every finding has a fix suggestion and a compliance impact statement.

CI integration

archrad validate exits 0 or 1. Drop it in any pipeline:

# GitHub Actions
- name: Validate architecture
  run: |
    archrad init --from docker-compose.yml --output graph.json
    archrad validate --ir graph.json

Try it

npm install -g @archrad/deterministic
archrad init --from docker-compose.yml
archrad validate --ir archrad-graph.json

Apache-2.0. No telemetry. IR graphs never leave your machine.

GitHub: github.com/archradhq
npm: @archrad/deterministic

If you run it against your stack and find something interesting — or find a false positive — open an issue or drop a comment below. Every piece of feedback shapes 0.4.0.

Detecting architecture drift during system design

Archrad — Sat, 11 Apr 2026 02:43:57 +0000

A team ships a feature. Weeks later, a security flaw surfaces. Not a bug in the code — a flaw in the architecture. The API gateway talks directly to the database. No auth boundary. A compliance gap that was baked in from day one.
The fix takes months. Not because the code is hard to change. Because the architecture is.
The real problem? Nobody caught it at design time. The architecture decision was made, the code was written, the system was deployed. By the time anyone looked at it through a compliance lens, it was too late to be cheap.
AI coding agents make this worse. Cursor and Copilot write code faster than ever. But they have no idea what your architecture rules are. They'll generate a service that bypasses your auth layer, connects directly to a database it shouldn't touch, or creates a sync chain that kills your P99 latency. It passes tests. It ships.
I built ArchRad to move architecture governance to where it should have been all along — design time.

What it does
ArchRad is a deterministic engine that validates your system architecture before you write code. You describe your architecture as an IR graph. ArchRad validates it against a set of lint rules — structural issues, missing auth, direct DB access, sync chain depth, isolated nodes — and blocks on violations.
It ships as an MCP server. So Cursor, Copilot, and Claude Desktop can call it mid-session.
I tested it cold this week. No system prompt. No hand-holding. Just a 6-node IR graph and a fresh Claude Desktop session.
Here's what fired:
⚠ IR-LINT-DIRECT-DB-ACCESS-002
api-gateway connects directly to user-db
Fix: introduce a service layer

⚠ IR-LINT-MISSING-AUTH-010
api-gateway has no auth coverage
Fix: add auth node or set config.authRequired: true

⚠ IR-LINT-ISOLATED-NODE-005
orphaned-analytics has no edges
Fix: remove or connect the node

⚠ IR-LINT-NO-HEALTHCHECK-003
No HTTP node exposes /health or /healthz
Fix: add a health route
Four violations. Six nodes. Caught before a single line of code was written.

How to install
npm install -g @archrad/deterministic
Add to Claude Desktop config:
json{
"mcpServers": {
"archrad": {
"command": "npx",
"args": ["-y", "@archrad/deterministic", "mcp"]
}
}
}
Restart Claude Desktop. Ask it to validate an IR graph. It calls archrad_validate_ir first try.

CI integration
Works on any platform. One command:
npx @archrad/deterministic validate \
--ir ./architecture/ir.json \
--fail-on-warning
Bitbucket, GitLab, Jenkins, Azure DevOps — all the same shell command. Exit 1 on violations. PR blocked.

What's next
The next step is ArchLora — a fine-tuned model that generates IR from plain English descriptions. Describe your system in plain English, get a validated IR back. Right now we support OpenAPI ingestion. Terraform and multi-repo ingestion are on the roadmap.
The OSS engine is Apache 2.0. Free. No telemetry.
GitHub: https://github.com/archradhq/arch-deterministic
npm: https://www.npmjs.com/package/@archrad/deterministic
If you've hit the same problem — security or compliance issues found late because architecture governance wasn't part of the design process — I'd like to hear about it

Your architecture drifts before you write a single line of code

Archrad — Wed, 08 Apr 2026 00:02:27 +0000

v0.1.5

You have an architecture decision record. A Confluence page. Maybe a Miro board with boxes and arrows that everyone agreed on in the last design review.

Then a sprint happens.

A service that was never supposed to touch the database directly now has a db.query() call buried in a helper. A dead node that was deprecated three months ago is still receiving traffic. Nobody noticed. The CI pipeline passed. The linter was happy. The tests are green.

The architecture, however, is already wrong.

The gap that no tool fills

We lint code. We type-check code. We test code. But we have never had a way to formally define an architecture and then enforce it — continuously, deterministically, before a PR is merged.

Code linters catch bad syntax. Architecture linters should catch bad structure. The two aren't the same problem, and a code linter cannot solve the architecture one.

Think of it this way: ESLint is to code what ArchRAD is to architecture blueprints. One enforces style and correctness at the expression level. The other enforces intent at the system level.

What ArchRAD does

ArchRAD is a blueprint compiler and governance layer. You define your architecture as a formal Intermediate Representation — nodes, edges, metadata, allowed connections — and ArchRAD validates it against a deterministic rule engine.

Two rules that ship out of the box:

IR-LINT-MISSING-AUTH-010 — flags any service edge missing an authentication boundary.

IR-LINT-DEAD-NODE-011 — flags any node with no inbound or outbound connections.

Cold-start from an existing OpenAPI spec:

npx @archrad/deterministic ingest openapi ./openapi.yaml
npx @archrad/deterministic validate --ir ./graph.json

Detect drift between your blueprint and generated code:

npx @archrad/deterministic validate-drift --ir ./graph.json --target python --out ./out

If the IR says service A cannot talk directly to the database, and the generated code does exactly that — ArchRAD tells you. Before it ships.

Why deterministic matters

Every other architecture tool gives you opinions. ArchRAD gives you constraints.

The rule engine is graph-based and deterministic. The same IR, the same rules, the same inputs will always produce the same findings. No LLM guessing. No probabilistic output. This matters especially as AI coding agents become part of the workflow — agents need hard constraints, not soft suggestions.

MCP server — architecture governance inside your agent

0.1.5 ships archrad-mcp alongside the CLI. One install, two binaries. Add this to your Cursor or Claude Desktop config:

{
  "mcpServers": {
    "archrad": { "command": "archrad-mcp" }
  }
}

Your agent can now call six tools against the same deterministic engine your CI uses — archrad_validate_ir, archrad_lint_summary, archrad_validate_drift, archrad_suggest_fix, and more. When the agent proposes connecting service A directly to the database, ArchRAD returns IR-LINT-DIRECT-DB-ACCESS-002 — before the code is written, not after the PR is opened.

Static remediation guidance ships for every built-in rule code. No generative output — archrad_suggest_fix returns curated, deterministic text for each finding. 127 tests cover the guidance corpus.

CI in ten lines

No separate Action needed — the CLI runs directly in any GitHub Actions workflow:

name: architecture drift
on: [push, pull_request]
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: |
          npx archrad validate-drift \
            --ir ./graph.json \
            --target python \
            --out ./golden-export \
            --json

PRs fail when generated code drifts from the IR. Add --fail-on-warning to also gate on lint findings.

The OSS core is Apache-2.0

The engine — IR, linter, validator, MCP server — is fully open source under Apache-2.0. No telemetry, no lock-in, works offline.

Try it on your next architecture review:

npm install @archrad/deterministic

GitHub: github.com/archradhq/arch-deterministic

Questions, feedback, or drift horror stories — drop them in the comments or open an issue on GitHub.

Every CI pipeline checks code. Nobody checks architecture. Here's why that matters.

Archrad — Sun, 05 Apr 2026 14:50:39 +0000

Originally built this as a side project — sharing what I've learned along the way.

Your CI pipeline probably does a lot.

It runs unit tests, scans for vulnerabilities, lints your API spec, builds and pushes a container image.

What it almost certainly doesn't do is check whether your architecture is still what you agreed to build.

The problem isn’t that teams don’t care.
It’s that architecture lives in docs — and CI can’t read docs.

The gap nobody talks about

When a team agrees on a service boundary — no direct database access, auth required on every HTTP entry — that agreement lives in a Confluence doc or a Miro board.

Nothing in your pipeline can read those. So nothing enforces them.

A direct DB connection can merge. A missing auth boundary can ship. Not because nobody cared. Because nothing was gating on it.

Code review is the current answer. But code review happens after implementation. The architecture decision has already been made and built. At that point you're reviewing a fait accompli.

The post-code tools don't close this gap

ArchUnit, Spectral, Axivion, OPA — all solid tools. All operating on code, specs, or running systems that already exist.

The intervention point is after the first commit.

None of them can catch an architecture violation before a line of code is written.

What a pre-code gate looks like

Your architecture is a graph — services are nodes, dependencies are edges. Express it as a machine-readable IR. Run a deterministic compiler on it before code generation begins.

# Use your existing OpenAPI spec — no IR authoring required
npx @archrad/deterministic ingest openapi --spec your-api.yaml --out graph.json
npx @archrad/deterministic validate --ir graph.json

No security definitions in your spec → IR-LINT-MISSING-AUTH-010 fires automatically:

⚠️  IR-LINT-MISSING-AUTH-010: HTTP entry node "payment-api" has no auth node
    or auth config in its immediate graph neighbourhood
    Fix: Add an auth/middleware node or set config.authRequired: false for
    intentionally public endpoints.
    Impact: Unauthenticated HTTP entry points are a compliance gap in regulated
    environments and a common attack surface.

Direct DB connection in the graph → IR-LINT-DIRECT-DB-ACCESS-002:

⚠️  IR-LINT-DIRECT-DB-ACCESS-002: API node "payment-api" connects directly
    to datastore node "card-db"
    Fix: Introduce a service or domain layer between HTTP handlers and persistence.
    Impact: Harder to test, swap storage, or enforce invariants at a single boundary.

Same graph. Same compiler version. Same findings. Every time.

High level flow

graph IR (JSON/YAML)
        ↓
archrad validate  ← blocks on violations
        ↓
archrad export
        ↓
code + OpenAPI + Docker
        ↓
archrad validate-drift ← blocks on divergence
        ↓
rest of CI (tests, security scans)

Machine-readable JSON output. CI-gateable. Blocks the PR.

Honest limits

Cold start is real. You have to get your architecture into graph IR format. OpenAPI ingestion helps for teams that already have specs. IaC ingestion — Terraform, CloudFormation — is roadmap, not shipped.

This doesn't prove semantic correctness. Drift detection means "code matches what the IR would generate" — not that your code is correct or matches production behavior. That's your tests.

No round-trip. Once you edit generated code there's no built-in path back to the IR. Think of it as scaffold plus contract validation, not full lifecycle sync.

The CI pipeline this enables

graph.json committed to repo
        ↓
archrad validate --fail-on-warning   ← blocks PR if architecture violated
        ↓
archrad validate-drift               ← blocks PR if code drifted from IR
        ↓
Spectral                             ← lint generated OpenAPI spec
        ↓
Snyk / Semgrep                       ← scan generated code
        ↓
Merge → deploy → operate

ArchRad runs first because structural violations should block before other tools waste time scanning code that shouldn't exist yet.

Try it

OSS under Apache-2.0. No IR authoring needed to get started:

# Ingest your existing OpenAPI spec
npx @archrad/deterministic ingest openapi --spec your-api.yaml --out graph.json
npx @archrad/deterministic validate --ir graph.json

# Or run against the built-in ecommerce fixture
npx @archrad/deterministic validate --ir fixtures/ecommerce-with-warnings.json

👉 github.com/archradhq/arch-deterministic
📦 npm install -g @archrad/deterministic

Closing question: does your CI pipeline gate on architecture today?

And if not — is that a tooling problem, a process problem, or just accepted as inevitable?

Architecture as Code isn't enough — here's why it needs a compiler

Archrad — Sat, 28 Mar 2026 16:05:20 +0000

Originally built this as a side project — sharing what I learned along the way.

Architecture decisions live in Confluence docs and Miro boards. They get reviewed once, approved, and then slowly become fiction as implementation diverges. A cache layer gets added. A direct DB call sneaks in. The agreed service boundary dissolves over three sprints.

There's no CI step for architecture. There's no compiler that says "this violates what you agreed to build." There's just a diagram that nobody updates.

I spent a long time thinking this was a discipline problem. Teams just need to be more rigorous, right? But I've come to think it's actually a tooling problem. Architecture has never been a machine-readable artifact. Diagrams are for humans. Docs are for humans. Nothing in your pipeline can read them — so nothing in your pipeline can gate on them.

The idea this builds on

Neal Ford and Mark Richards recently published a piece on O'Reilly Radar previewing their upcoming book Architecture as Code. They describe "fitness functions" — automated governance checks for architectural concerns, like unit tests but for architecture. The tools they reference (ArchUnit, NetArchTest, PyTestArch) are solid implementations of this idea.

But they all operate on code that already exists.

What I've been building is the pre-code version of that idea: a deterministic compiler that runs the fitness function on the architecture graph before any code is written. The intervention point is different — and so is the cost of fixing what you find.

The insight: architecture needs an IR

In compiler design, an IR (intermediate representation) sits between source code and target output. It's the stable, machine-readable artifact that validation, optimization, and code generation all operate on. Same input, same output, every time.

What if architecture had the same thing?

Not a diagram. Not a doc. A structured graph — nodes and edges — that a deterministic compiler can read, validate, and compile to runnable code. Something CI can gate on before a service repo even exists.

That's what I've been building: a deterministic compiler for system architecture.

What it looks like in practice

You describe your architecture as a graph. Here's a minimal example — a payment API talking directly to a database:

{
  "graph": {
    "nodes": [
      {
        "id": "payment-api",
        "type": "api",
        "name": "Payment API",
        "config": { "url": "/payments", "method": "POST" }
      },
      {
        "id": "user-db",
        "type": "database",
        "name": "User DB",
        "config": { "engine": "postgres" }
      }
    ],
    "edges": [
      { "from": "payment-api", "to": "user-db" }
    ]
  }
}

You run archrad validate on it:

⚠️  IR-LINT-DIRECT-DB-ACCESS-002: API node "payment-api" connects
    directly to datastore node "user-db"
    Fix: Introduce a service or domain layer between HTTP handlers
    and persistence.
    Impact: Harder to test, swap storage, or enforce invariants
    at a single boundary.

⚠️  IR-LINT-NO-HEALTHCHECK-003: No HTTP node exposes a typical
    health/readiness path (/health, /healthz, /live, /ready)
    Fix: Add a GET route such as /health for orchestrators and
    load balancers.

These findings are deterministic. Same graph, same compiler version, same findings — every time. You can run this in GitHub Actions, fail the PR, attach the JSON output to a ticket, and show it to an auditor.

Now fix the graph — add a service layer node between the API and the database, add a health route — and re-validate. Clean gate. Export unlocks.

archrad export --ir graph.json --target python --out ./my-api

Out comes a FastAPI project with OpenAPI, Dockerfile, docker-compose, and Makefile. Scaffold tied to a validated IR.

Where does the IR come from?

This is the first question everyone asks. Three paths:

Path A — Author YAML directly. Lighter than JSON, same result:

archrad yaml-to-ir --yaml graph.yaml --out graph.json
archrad validate --ir graph.json

Path B — Ingest an existing OpenAPI spec. If your team already has one, each operation becomes an HTTP node automatically:

archrad ingest openapi --spec openapi.yaml --out graph.json
archrad validate --ir graph.json

Path C — ArchRad Cloud. Type a natural language prompt in the browser, the planner converts it to a structured graph, download graph.json. The OSS compiler takes it from there — no cloud dependency on the blocking path.

The graph.json commits to your repo like any other source file. From that point everything is local, deterministic, and offline.

"But won't the IR file rot just like a Confluence doc?"

This is the right objection. Someone raised it when I posted about this on Reddit. I didn't have a complete answer then — so I shipped one.

archrad validate-drift re-exports from the IR in memory and diffs it against what's on disk. If generated code has been modified without updating the IR, CI fails:

archrad validate-drift -i graph.json -t python -o ./out

# ❌ DRIFT-MODIFIED: app/main.py
#    File differs from deterministic export for this IR
# archrad: drift detected — regenerate with `archrad export`
#    or align the IR.

The IR becomes the authority. If code diverges from it, you know immediately — in local dev or in CI.

This doesn't fully solve the deeper problem the commenter raised — deriving IR from IaC or service mesh config is the right long-term answer and it's on the roadmap. But it closes the gap where generated code drifts silently from the IR that produced it.

How it fits into a real pipeline

graph.json committed to repo
        ↓
CI: archrad validate --fail-on-warning   ← blocks PR if architecture violated
        ↓
CI: archrad validate-drift               ← blocks PR if code drifted from IR
        ↓
CI: Spectral (lint generated openapi.yaml)
        ↓
CI: Snyk / Semgrep (scan generated code)
        ↓
Merge → deploy → operate

ArchRad runs first because structural violations should block before other tools waste time scanning code that shouldn't exist yet. Findings output as --json for machine consumption — attach to PR comments, tickets, audit logs.

What this does NOT solve (honest scope)

I want to be direct about the limits:

Not semantic correctness. Drift detection means "code matches what the IR would generate." It doesn't prove the code is correct or matches prod behavior. That's your tests and your runtime.

Not full compliance attestation. The OSS layer catches structural and architecture heuristics — missing health routes, direct DB access, sync chain depth, high fan-out. Deeper policy (PCI, HIPAA, SOX rule packs) lives in ArchRad Cloud. OSS findings are supporting evidence for internal programs, not a substitute for external attestation.

Not a round-trip. Once you edit generated code, there's no built-in path back to the IR. Think of it as scaffold + contract validation, not full lifecycle sync.

The IR authoring cold start is real. Getting from "existing system" to a graph IR is work. The OpenAPI ingestion path helps for HTTP surfaces. IaC ingestion is on the roadmap. Hand-authoring YAML works for greenfield.

Can you add your own rules?

Yes — the lint rules are a typed visitor registry. Adding a custom rule is writing one function and appending it:

// my-org-rules/require-timeout.ts
export function ruleRequireTimeout(g: ParsedLintGraph): IrStructuralFinding[] {
  const findings: IrStructuralFinding[] = [];
  for (const [id, n] of g.nodeById) {
    const cfg = (n.config as Record<string, unknown>) || {};
    if (!cfg.timeout) {
      findings.push({
        code: 'ORG-001',
        severity: 'warning',
        layer: 'lint',
        message: `Node "${id}" has no timeout configured`,
        nodeId: id,
        fixHint: 'Add config.timeout to this node.',
      });
    }
  }
  return findings;
}

// In your pipeline:
import { LINT_RULE_REGISTRY } from '@archrad/deterministic';
LINT_RULE_REGISTRY.push(ruleRequireTimeout);

Fork or wrap the package, write visitors that return IrStructuralFinding[], append to the registry. Same pattern the built-in rules use. Org-specific policy packs with more depth are a Cloud feature — but the extension point is open and documented.

The open-core structure

The deterministic engine — validate, architecture lint, export, drift detection — is fully open source under Apache-2.0:

👉 github.com/archradhq/arch-deterministic

npm install -g @archrad/deterministic
archrad validate --ir graph.json

Want to try it without writing any IR? The repo ships fixtures that hit every lint rule:

npx @archrad/deterministic validate --ir fixtures/ecommerce-with-warnings.json

ArchRad Cloud adds natural language authoring, org policy packs, compliance frameworks, and AI remediation — built on the same deterministic contract. The OSS compiler is what makes the cloud product's claims auditable. You can verify what the gate does before you buy anything.

Why the timing matters

The O'Reilly Architecture as Code book and the broader "architecture governance" conversation are converging right now. Academic papers on deterministic compilation for structured pipelines are appearing. The industry is waking up to the idea that architecture needs to be machine-readable.

The gap I'm filling is specific: the moment between architecture decision and first commit. Every existing tool — ArchUnit, Spectral, Snyk, Checkov — operates on artifacts that already exist. This is the only tool I know of that operates before any of those artifacts exist, on the architecture graph itself, with a deterministic gate you can put in CI.

What's your current approach?

I'm genuinely curious how other teams handle this. Do you enforce architecture through code review alone? Have you tried fitness functions or architectural tests? What worked, what failed?

Drop a comment — especially if you have a technical objection. Those tend to become features.