docs/fundamentals/layers

Layers

A layer rule says: things on top can see things below, but not the other way around. It's the single most valuable rule most codebases can add.

last updated · apr 18, 2026·6 min readedit on github →

Why layers

In a healthy codebase, UI calls domain, domain calls infrastructure. Nothing flows back up. That's the boundary your whiteboard sketch implies, and the one your compiler doesn't enforce. Leave it unguarded and a single import can quietly flip it.

A minimal example

Here is the smallest layer rule that pays its rent. Drop it at the root of your repo:

.driftlog.yaml

# three-layer stack. Top to bottom only.
rules:
  - type: layer
    name: "app layers"
    order:
      - ui/**
      - domain/**
      - infra/**
    severity: error

Run it locally to see what breaks right now. No CI required:

$ driftlog check

note

Driftlog treats layer ordering as a list, not a DAG. If you need diamond-shaped dependencies, use a boundary rule instead. Layers are the wrong tool.

Common pitfalls

Layer leaks via re-exports. A barrel.ts that re-exports everything is a layer's worst enemy. Enable trace_reexports.
Tests that import across layers. Scope layer rules to src/ and write separate rules for test/.
Too many layers. Four is a lot. Start with three.

Boundaries