agentic-dev/docs/architecture/dependency-flow.md

Dependency Flow

                    +-------------+   +-----------------+   +-----------+
                    | apps/web-   |   | apps/web-       |   | apps/cms  |
                    | next        |   | tanstack        |   |           |
                    +------+------+   +--------+--------+   +-----+-----+
                           |                   |                  |
        +------------------+--------------+    |                  |
        |                  |              |    |                  |
   +----v-----+      +-----v------+ +-----v----v---+      +-------v------+
   | core-api |      | core-trpc  | | feature      |      | core-cms     |
   |          |      |            | | packages     |      |              |
   +-----+----+      +-----+------+ +------+-------+      +-------+------+
         |                 |               |                      |
         |                 |               |                      |
         +--+-------+------+---------------+----+   +-------------+
            |       |                           |   |
       +----v---+ +-v---------+         +-------v---v---+
       | core-  | | core-ui   |         | core-shared    |
       | shared | |           |         |                |
       +--------+ +-----------+         +----------------+

  Boundary rules (enforced by ESLint + Turborepo boundaries):
    app             → app, core, core-composition, feature, tooling
    feature         → core, tooling
    core            → core, core-composition, tooling
    core-composition → core, core-composition, feature, tooling
    tooling         → tooling
    
    Composition exceptions:
      core-api  → @repo/<feature>/api (subpath only)
      core-cms  → @repo/<feature>/cms (subpath only)

Concrete examples

Allowed:

// in apps/web-next
import { appRouter } from "@repo/core-api";
import { NextTrpcProvider } from "@repo/core-trpc/next";
import { bindProductionBlog } from "@repo/blog/di/bind-production";

// in packages/blog
import { slugifyIfMissing } from "@repo/core-shared/payload";

// in packages/core-api
import { blogRouter } from "@repo/blog/api";          // composition exception
import { router } from "@repo/core-shared/trpc/init"; // core → core fine

// in packages/core-cms
import { articles } from "@repo/blog/cms";             // composition exception

Disallowed:

// in packages/blog (cross-feature)
import { Article } from "@repo/marketing-pages";     // ❌ feature → feature

// in packages/blog (deep import past public exports)
import { articles } from "@repo/blog/src/integrations/cms/collections/articles"; // ❌ no-private

// in packages/core-shared
import { blogRouter } from "@repo/blog/api";         // ❌ core → feature

// in packages/core-trpc
import { someBlogThing } from "@repo/blog";          // ❌ core → feature (only core-api/core-cms have exception)

Enforcement strategy

Three layers work in tandem:

1. package.json dependencies — if you didn't declare it, you can't import it
2. exports map — blocks deep imports; only public subpaths are accessible
3. Two parallel automated checks (both enforcing the same five-tag model):
   • ESLint eslint-plugin-boundaries runs at lint time, catching direct-import violations
   • Turborepo boundaries runs at build time, validating the entire workspace graph including transitive dependencies

The two enforcement layers are independent but complementary. ESLint is stricter on per-import context (e.g., file-specific exemptions via // @boundaries-ignore), while Turborepo catches transitive issues that lint-time checking misses. Run pnpm lint and pnpm turbo boundaries in CI to catch all violations.