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

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-tanstack      → @repo/api-client, @repo/ui
                         Startup: @repo/cms-core (config) + @repo/cms-client (init local)
apps/cms               → @repo/cms-core, payload, next
apps/storybook         → @repo/ui

@repo/api-client       → @repo/api (router types only)
@repo/api              → @repo/core/interface-adapters (controllers)
@repo/cms-core         → @repo/core/application (use cases for hooks), payload (types)
@repo/cms-client       → (standalone — receives Payload instance, doesn't import it)
@repo/ui               → (standalone — tailwind, shadcn)

Core Internal Dependencies

core/entities           → (standalone — zero deps)
core/application        → core/entities only
core/interface-adapters → core/application, core/entities
core/infrastructure     → core/application, core/entities, @repo/cms-client, external libs
core/di                 → all internal layers

Circular Dependency Prevention — HARD RULES

• NEVER: packages/core → apps/*
• NEVER: apps/cms → packages/core/infrastructure
• 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

The Payload CMS integration creates a potential circular dependency:

apps/cms hooks → @repo/core/application (use cases)
@repo/core/infrastructure → @repo/cms-client → Payload API

This is resolved by:

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
3. App startup code (not a shared package) wires Payload instance into cms-client