Imports flow one way through three layers, and a machine says no to anything else.

The problem

Every codebase starts with a rule about what can import what. Six months later a utility imports a feature “just this once”, the feature imports the app’s router, and now nothing can be moved or tested alone.

A rule that lives in people’s heads doesn’t survive deadlines.

What I concluded

The fix is boring, and that’s the point. Three layers, and a check in CI.

  core/      api, design system, format,   knows nothing about
             session, telemetry             the product
    ▲
  features/  orders, customers, assistant  domain logic, built
                                            from core
    ▲
  app/       routes, pages, wiring         the only thing that
                                            builds

Imports go up that diagram and never down. core can’t import a feature. A feature can’t import the app. Nothing imports in a circle. A dependency checker runs next to the type check, and a pull request that breaks the direction fails with the rule’s name and the two files.

forbidden: [
  { name: "no-circular", to: { circular: true } },
  { name: "core-stays-foundational",
    from: { path: "^core/" }, to: { path: "^(features|app)/" } },
  { name: "features-dont-reach-up",
    from: { path: "^features/" }, to: { path: "^app/" } },
]

What keeps it cheap

Packages are consumed as source. Each has an index file and no build step of its own, and only the app builds. There’s no “rebuild the design system” loop, and go-to-definition lands on real code.

Horizontal libraries get one door each. Everything that fetches goes through core/api, and everything on screen is built from the design system. Because there’s one door, a rule added at the door applies everywhere.

When the rule is in your way

“I had to copy this because of an import cycle” names its own fix. If two features need the same thing, it belongs in the lower layer. Move it down. Don’t copy it and don’t punch a hole in the rule.

Rules

  • Imports go one way. Up the diagram, never down, never in a circle.
  • CI enforces it. The rule is a check, not a convention.
  • Import from the package’s index only. Reaching into another package’s internals is the first step toward a cycle.
  • Shared code moves down. Never copy around a cycle.

What you get

The direction is the architecture. It keeps every later decision local: you can delete a feature without touching core, and you can read core without knowing what the product is.

Related: Data access, Overrides.