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
Top comments (0)