fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs(architecture): rewrite dependency-flow for vertical features + boundary rules

Browse Source
This commit is contained in:
Danijel Martinek
2026-05-05 09:32:25 +02:00
parent f6e86cf55e
commit 590543fb65
1 changed files with 56 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
docs/architecture/dependency-flow.md
View File

@@ -1,50 +1,70 @@
# Dependency Flow # Dependency Flow
## Package Dependencies (one direction only)
``` ```
apps/web-next → @repo/api-client, @repo/ui +-------------+ +-----------------+ +-----------+
Startup: @repo/cms-core (config) + @repo/cms-client (init local) | apps/web- | | apps/web- | | apps/cms |
apps/web-tanstack → @repo/api-client, @repo/ui | next | | tanstack | | |
Startup: @repo/cms-core (config) + @repo/cms-client (init local) +------+------+ +--------+--------+ +-----+-----+
apps/cms → @repo/cms-core, payload, next | | |
apps/storybook → @repo/ui +------------------+--------------+ | |
| | | | |
+----v-----+ +-----v------+ +-----v----v---+ +-------v------+
| core-api | | core-trpc | | feature | | core-cms |
| | | | | packages | | |
+-----+----+ +-----+------+ +------+-------+ +-------+------+
| | | |
| | | |
+--+-------+------+---------------+----+ +-------------+
| | | |
+----v---+ +-v---------+ +-------v---v---+
| core- | | core-ui | | core-shared |
| shared | | | | |
+--------+ +-----------+ +----------------+
@repo/api-client → @repo/api (router types only) Boundary rules (enforced by eslint-plugin-boundaries):
@repo/api → @repo/core/interface-adapters (controllers) app → app, core, feature, core-composition (any)
@repo/cms-core → @repo/core/application (use cases for hooks), payload (types) feature → core (any), but NOT other features, NOT app
@repo/cms-client → (standalone — receives Payload instance, doesn't import it) core → core, but NOT feature, NOT app
@repo/ui → (standalone — tailwind, shadcn) core-composition → core, feature subpath exports only (`/cms`, `/api`)
core-api → @repo/<feature>/api
core-cms → @repo/<feature>/cms
``` ```
## Core Internal Dependencies ## Concrete examples
``` Allowed:
core/entities → (standalone — zero deps) ```ts
core/application → core/entities only // in apps/web-next
core/interface-adapters → core/application, core/entities import { appRouter } from "@repo/core-api";
core/infrastructure → core/application, core/entities, @repo/cms-client, external libs import { NextTrpcProvider } from "@repo/core-trpc/next";
core/di → all internal layers 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
``` ```
## Circular Dependency Prevention — HARD RULES Disallowed:
```ts
// in packages/blog (cross-feature)
import { Article } from "@repo/marketing-pages"; // ❌ feature → feature
- **NEVER:** packages/core → apps/* // in packages/blog (deep import past public exports)
- **NEVER:** apps/cms → packages/core/infrastructure import { articles } from "@repo/blog/src/integrations/cms/collections/articles"; // ❌ no-private
- **NEVER:** packages/cms-client → apps/cms or packages/core or packages/cms-core
- **NEVER:** packages/cms-core → packages/cms-client
- **NEVER:** core/entities → anything
- **NEVER:** core/application → core/infrastructure
## Why These Rules Exist // in packages/core-shared
import { blogRouter } from "@repo/blog/api"; // ❌ core → feature
The Payload CMS integration creates a potential circular dependency: // in packages/core-trpc
``` import { someBlogThing } from "@repo/blog"; // ❌ core → feature (only core-api/core-cms have exception)
apps/cms hooks → @repo/core/application (use cases)
@repo/core/infrastructure → @repo/cms-client → Payload API
``` ```
This is resolved by: ## Three-layer enforcement
1. `cms-client` is standalone — receives Payload instance via injection, never imports it
2. `cms-core` hooks only import from `core/application`, never `core/infrastructure` ESLint catches accidental cross-package imports at lint time. The `package.json` `exports` map blocks deep imports at module-resolution time. Workspace `dependencies` declarations make the package graph itself the source of truth — if you didn't declare it, you can't import it.
3. App startup code (not a shared package) wires Payload instance into cms-client