Skip to content
Muhammet Şafak
tr
Journal 4 min read

archlint: Enforcing Architecture Boundaries in CI, Deterministically

Architecture decisions rot in the code. One architecture.json lets archlint enforce Go, TypeScript and Python boundaries in CI on every commit, no model.

A rack-mounted server badged archlint, its violet screen reading archlint check: FAILED and pkg/adapters -> pkg/domain

I wrote separately about why architecture decisions rot: an ADR says “the domain must not import infrastructure,” and two years later you find it importing the database in a hundred places — because nothing was watching the rule. This post is the tooling side of that problem: a small, standalone Go CLI — archlint.

A real system isn’t one language, though: a Go API, a TypeScript frontend, Python workers. All three share the same architectural intent, and archlint governs all three from one architecture.json.

architecture.json: put the rule in code

You declare the layers and their allowed dependencies in one file:

{
  "module": "github.com/acme/app",
  "layers": {
    "domain": ["internal/domain"],
    "db":     ["internal/db"],
    "http":   ["internal/http"]
  },
  "rules": {
    "domain": [],
    "db":     ["domain"],
    "http":   ["domain", "db"]
  }
}

domain may import nothing internal, db may import only domain, http may import both. Any other internal edge is a violation. A same-layer import is always allowed; [] means “may import no other layer.”

The boundary isn’t language-specific; the syntax is

At the layer level the rule is identical in every language: domain → db is forbidden. What differs between languages isn’t the rule, it’s how an import is written and which file it resolves to:

  • Go: an absolute package path — github.com/acme/app/internal/db. Resolve it by stripping the module prefix → internal/db.
  • TypeScript: relative (../db/repo) or aliased (@/db/repo). Resolve the relative one against the file’s location, the alias through the aliases map in architecture.json.
  • Python: dotted and relative — from ..db.repo import find_order. Resolve the leading dots against the file’s package, then map the module to a path.

archlint reduces all of them to one thing: a repo-relative path → a layer. From there the engine is the same: “which layer is this file in, which layer does this import reach, do the rules allow it?”

One config, mixed repo

A single file can govern a three-language monorepo. Layer names are shared; the paths are language-specific:

{
  "module": "github.com/acme/app",
  "aliases": { "@/": "web/src/" },
  "layers": {
    "domain": ["internal/domain", "web/src/domain", "workers/app/domain"],
    "infra":  ["internal/infra", "web/src/infra", "workers/app/infra"]
  },
  "rules": { "domain": [], "infra": ["domain"] }
}

The domain layer exists in all three services (Go internal/, TS web/src/, Python workers/app/) and none of them may import infrastructure. One rule, three languages, one CI gate.

How it works

archlint check extracts the imports of every Go, TypeScript and Python file. Inside there’s a Language interface: each language knows only two things — how to extract a file’s imports and how to resolve an import to a repo-relative path. The rest of the linter is language-agnostic, so adding a language means adding one Language implementation.

Go imports are read with the standard library’s go/parser — no regex guessing, no compilation needed, exact. After mapping each file and each import to a layer, archlint reports the edge that breaks the rule, with file and line:

$ archlint check examples/sample
Scanned examples/sample against examples/sample/architecture.json — 2 layer(s).

1 boundary violation(s):
  internal/domain/bad.go:6  domain → db is not allowed  (import "github.com/acme/app/internal/db")

A violation exits 1 → the build goes red. The offending import is caught before it reaches main, not in an archaeology session two years later.

Design decisions

  • Deterministic, no model. The whole point is a guardrail you can gate CI on: same diff, same verdict, no model in the loop. That’s the difference from telling an LLM to “review the architecture.”
  • Zero dependencies (Go stdlib). Instead of tree-sitter, a heavy CGo dependency, Go is read with go/parser and TypeScript and Python with regex scanners. The config is JSON for now — YAML adds a dependency, so it’s a follow-up.
  • Go is exact, TypeScript and Python are best-effort. go/parser gives Go imports exactly. TypeScript/JavaScript and Python imports are extracted with regex scanners that cover the standard forms, so they are not full parsers.

In CI

From here on it’s the usual two lines of the workflows I build with GitHub Actions; all archlint asks is to be able to fail the job by returning a non-zero exit code on a violation.

- run: go install github.com/muhammetsafak/archlint/cmd/archlint@latest
- run: archlint check

Or with the packaged GitHub Action:

- uses: muhammetsafak/archlint@v0.3.0

Limits — the honest list

  • Regex scanners for TS/JS and Python. Go imports are read with go/parser (exact). TS/JS and Python imports come from regex scanners, so an import-like string inside a comment or string literal can be a false positive. The README says so plainly.
  • Static import graph. check governs the dependency graph between layers, and archlint metrics (added in v0.3.0) adds coupling, bounded-context and Conway signals on that same graph. A synchronous call where an async one was required, or a direct DB query across a domain boundary, needs correlating runtime traces — a later phase.
  • JSON config (YAML is a follow-up). The deterministic design is deliberate: it has to be gate-able.

Try it

Each example plants a deliberate violation:

archlint check examples/sample      # Go     → internal/domain/bad.go
archlint check examples/ts-sample   # TS     → src/domain/bad.ts   (resolves the "@/" alias)
archlint check examples/py-sample   # Python → app/domain/bad.py   (resolves "..db.repo")

All three print the same thing: domain → db is not allowed, exit 1, build red.

Write your architecture.json and run archlint check. If you tell me which language or boundary you want next, I’ll queue it.

Experiments on this topic

Build notes on a dice-free 4X core of 480 hexes and at most 60 turns, offline in the browser: a constraint chose the scope, and it shipped as Regnarium.

What it does today

Runs a full 4X match on a 480-hex map in at most 60 turns; rules, map generation and the opponent AI live in one pure TypeScript core, and combat rolls no dice. Anyone with half an hour and an appetite for strategy can open it in a browser.

Web TypeScript Next.js React +2 more
September 2026 — September 2026

Why a frozen JSON envelope replaced language-specific serialization, and how the experiment ended as a queue standard read by PHP, Python, Go and Node.js.

What it does today

The frozen JSON envelope has four languages — PHP, Python, Go, Node.js — reading the same bytes, with no sidecar and no broker plugin. Teams running a polyglot queue can pick up the spec and the SDKs today.

Open-Source JSON Redis RabbitMQ +4 more
March 2026 — June 2026

Comments

Sign in with your GitHub account to join the discussion. Comments are stored in GitHub Discussions.

Related Posts

Search the site

Start typing to search posts, projects and pages.

Esc to close Powered by Pagefind