DEV Community

Archrad
Archrad

Posted on

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

#architecture #devops #opensource #platformengineering

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Try it 

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

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.

Top comments (0)