ArchRails
01 · The trap
Architecture is still living in markdown
The intended system is prose. The running system is git. Nothing connects them.
Most teams have security, change management, and model risk. What they do not have is a checkable model of the intended system. CALM is the open language for that model. ArchRails is the gate.
The intended system is prose. The running system is git. Nothing connects them.
They infer a path from the tree. They do not tell you which parts they invented.
The intended system becomes an artifact you can check a change against.
Nodes, allowed paths, and controls in a schema-validated file. Open standard, not our format. calm.finos.org
{ "unique-id": "service-order", "connects": ["service-api-gateway"] }
The pull request is the gate. OrderService is not allowed to call PaymentService.
Markdown is how to build. The model answers whether a change is allowed.
You declare the model. ArchRails judges the merge against it. The agent session runs the same engine so a forbidden file need not be written.
Built on FINOS CALM v1. Evidence an auditor verifies offline.
OrderService calls PaymentService directly — must route via service-api-gatewayOrderDatabase accessed via HTTP — node declares JDBC:5432 onlyInventoryService changes scoped to service-inventory — no leakageNot a wiki sentence. A schema-validated CALM document: nodes, allowed paths, and the controls on them. Humans review it. The merge gate evaluates it.
If that is skipped, the pull request still judges. The product.
Cursor attempts a forbidden DB call during a 3 AM hotfix. ArchRails blocks it in the session; the agent rewrites against the permitted path. Production stays in PCI scope.
Every governed merge produces a signed attestation — what the architecture was, that the change was evaluated against it, and who promoted it. You download it and check it yourself. You never have to take our word.
What an attestation is, and is not. It proves what your architecture was at a merge, that the change was evaluated against it, and by which build. It does not contain your code. Your SCM already holds the pull request. The attestation binds to that record rather than duplicating it.
Paste your calm.json to instantly check for interface violations, missing controls, and structural issues — then render your architecture graph interactively. No account required.
archrails arch generate in your repo and it reads your code and writes a first-draft architecture document, plus the configuration ArchRails needs to enforce it. It uses a coding agent you already have installed — Claude Code, Codex, Gemini CLI or Cursor Agent — so ArchRails calls no model service of its own and no AI API key is involved. Budget 20–40 minutes on a large repo; it is a one-time cost. You review the draft like any other PR, merge it, and enforcement starts on the next one. If you'd rather author by hand, the free CALM Visualizer is available with no account required. Declaring the architecture once is the fundamental that lets AI amplification go in a useful direction; without it, more agents just means more entropy.calm.json. Every comment is traceable to a node ID you authored. It's deterministic, not probabilistic, and the same gate runs at PR time and inside the coding agent — so the agent can't reach an API your architecture forbids. As Adam Bender put it at SE@TP 2026: “all of your APIs just became public” the moment you let agents loose. ArchRails is the contract that says which ones they're allowed to call.calm.json at the repo root describes your full system graph, and ArchRails only evaluates the slice of the graph a given PR actually touches — a payment-service change won't trigger inventory-service checks. This is deliberate: dependency graphs scale quadratically with codebase size, so at the 10× AI-driven velocity everyone is preparing for, evaluating everything on every PR is how you burn your test budget into the ground.Start with one repo and one CALM document. ArchRails will enforce it on every pull request.