Detecting architecture drift during system design

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