Skip to content

Introduction

Architecture Rules lets you write your repository’s architecture in one file, architecture.yaml, and enforce it with an oxlint plugin and a CLI. Reach for it when you want import boundaries, folder layouts and naming rules checked on every change instead of in code review.

Each question below is answered by one family of rules, each with its own page.

Question Family
What may this folder import? imports
Who may import it? importedBy
Which importers may use this exported symbol? exports
Which names may this file declare or call? members
What may this file export? surface
Which files may live in this folder? structure
What may they be called? structure
Which sibling files does this file require? structure
Is there an import cycle? graph
Does anything import this file? graph
Can this layer reach that one, by any route? graph

The oxlint plugin and the CLI both check the first five. graph needs the whole repository, so only the CLI checks it. To adopt rules on an existing codebase, see adoption.

The manifest reads like a directory listing. Everything about a folder is written at that folder, and its subfolders inherit it:

"@/modules/{module}/domain/":
imports:
reset: true
external: [effect]
allow: ["@/modules/{module}/domain/**"]
children:
"*.root.ts": { requires: ["{base}.root.test.ts"] }

This says domain/ may import only itself and effect, and every *.root.ts needs a test beside it.

The directory tree as the backbone of the policyA directory listing of a billing module. Import allowlists are written on folders: modules/ allows platform/ddd, inherited by every folder below; domain/ allows only itself and effect; commands/ and queries/ each allow themselves and domain/. A command handler importing the repository port is allowed. A query importing it is refused, because the port's importedBy admits only command handlers. The domain importing the live adapter is refused. The domain/ folder admits root and repository files, and refuses a stray helpers.ts. Brackets link owed siblings: each file and its test, and the repository port with its live and fake adapters in infrastructure/. Inside the repository port, its type may declare findOneById and save but not findByCustomer, a query in disguise; and the file may export InvoiceRepositoryShape but not makeRepo, which is not named as a repository.src/modules/imports: platform/ddd/** ↓ inherited belowbilling/domain/imports: domain/**, effectinvoice.root.ts✓*.root.tsinvoice.root.test.ts✓owed: {base}.test.tsinvoice.repository.ts✓*.repository.ts, a porthelpers.ts✗no child domain/ admitscommands/imports: commands/**, domain/**void-invoice.handler.ts✓*.handler.tsvoid-invoice.handler.test.ts✓owed: {base}.test.tsqueries/imports: queries/**, domain/**invoice-summary.query.ts✓*.query.ts · importedBy refusesinfrastructure/invoice.repository-live.ts✓owed by the portinvoice.repository-fake.ts✓owed by the portplatform/ddd/✓✗✗aainside invoice.repository.tsexport type InvoiceRepositoryShape = {✓surface named *RepositoryShape readonly findOneById: (id) => …✓members load by identity readonly save: (invoice) => …✓members save the aggregate readonly findByCustomer: (id) => …✗members a query in disguise};export const makeRepo = () => …✗surface not a *Repository namemay importmay not importowed sibling (requires)✓✗child the folder admits / refuses
Every rule hangs off the tree: a folder states what its files may import (and passes it down), which children it admits, and which siblings a file owes — down to the names a file may declare and export.

To see every rule that governs one file, run architecture explain.

  • Rules match resolved files. An import is resolved through your tsconfig paths and workspace links before any rule sees it. An import that cannot be resolved is an error, not a skip. See resolution.
  • Every rule proves it can fire. Each rule is tested against a generated violation when it loads, and the plugin refuses to load if one no longer matches anything. See probes.