Dependency Rules

Review implemented validation rules for module dependency cycles, forbidden dependencies, public entrypoints, declared contracts, and dependency graph health.

Why it matters

Dependency findings protect architecture boundaries by showing where modules import, depend on, or expose each other in ways the architecture model does not allow.

Overview

Review implemented validation rules for module dependency cycles, forbidden dependencies, public entrypoints, declared contracts, and dependency graph health.

Dependency findings protect architecture boundaries by showing where modules import, depend on, or expose each other in ways the architecture model does not allow.

Why it matters

Cloud uses this guidance to help teams interpret local validation findings in organization context without turning the docs into implementation notes.

When this domain drifts, findings become harder to triage, ownership becomes less clear, and architecture review depends too much on individual memory.

Good architectural practices

Module dependencies that match declared contracts and dependency policy.
Public entrypoints used instead of internal module paths.
Dependency graph patterns such as cycles, orphan modules, high inbound pressure, and layer-direction drift.

Common anti-patterns

Circular module dependency detected
Forbidden cross-module dependency detected
Non-public cross-module import detected
Cross-module dependency missing from module contract
Cross-module import bypasses public module surface
Declared module dependency not used
Potential orphan module detected
Transitive circular module dependency detected
Module has high inbound dependency count
Dependency violates architecture layer direction
Cross-component dependency policy violation

Relationship to other architecture areas

This domain usually overlaps with neighboring validation categories. Use the related pages below to understand the adjacent architecture concerns before changing policy, suppressing a finding, or accepting risk.

Implemented rules

These are the currently implemented rules in this category. Use this table for category-level orientation, then open the Rule Catalog when you need rule-specific examples and remediation guidance.

Rule ID	Rule title	Category	Severity	Short explanation	Example violation	Remediation guidance	Rule detail
AP-DEP-001	Circular module dependency detected	Dependency	error	Flags direct circular dependencies between modules.	billing imports invoices while invoices imports billing.	Move shared behavior into a lower-level module. Introduce a public interface or event boundary. Remove one dependency edge and rerun validation.	View rule page
AP-DEP-002	Forbidden cross-module dependency detected	Dependency	error	Flags dependencies blocked by dependency rule configuration.	A domain module imports a UI module despite a forbidden dependency rule.	Remove or reroute the forbidden dependency. Use an allowed public module boundary. Only update the rule if the architecture decision changed and is documented.	View rule page
AP-DEP-003	Non-public cross-module import detected	Dependency	error	Flags cross-module imports that do not use a public module entrypoint.	import from ../payments/services/internal-ledger	Export the supported symbol from the target public entrypoint. Change consumers to import through that entrypoint. Keep internal-only code inside the owning module.	View rule page
AP-DEP-004	Cross-module dependency missing from module contract	Dependency	error	Flags an actual cross-module import that is not declared in the source module contract.	mobile imports notifications code while mobile's contract does not declare notifications.	Decide whether the dependency is legitimate. If legitimate, add the target module to the source module contract dependsOn list. If not legitimate, move the behavior behind the correct public module boundary.	View rule page
AP-DEP-005	Cross-module import bypasses public module surface	Dependency	error	Flags imports that reach into another module's internals instead of its public entrypoint.	import { SessionPolicy } from '../identity/internal/session-policy'	Export the supported symbol from the target module public entrypoint. Change consumers to import from that entrypoint. If the symbol should stay internal, move the behavior into the owning module.	View rule page
AP-DEP-006	Declared module dependency not used	Dependency	warning	Flags a module contract dependency that no longer appears in implementation imports.	billing declares notifications but no billing code imports notifications.	Remove stale dependsOn entries. If the dependency is intentional but dynamic, document the reason. Run validation after contract cleanup.	View rule page
AP-DEP-007	Potential orphan module detected	Dependency	warning	Flags modules with no declared or actual inbound/outbound module dependencies.	A registered health module has no inbound or outbound dependencies and no ADR explaining the isolation.	Decide whether the isolation is intentional. Connect the module through legitimate dependencies or document the intentional isolation. Remove stale modules that are no longer part of the architecture.	View rule page
AP-DEP-008	Transitive circular module dependency detected	Dependency	error	Flags dependency cycles that emerge through multiple module hops.	payments -> ledger -> settlement -> payments.	Identify the smallest edge that breaks the cycle. Move shared behavior into a lower-level module or explicit interface. Re-run validation to confirm the graph is acyclic.	View rule page
AP-DEP-009	Module has high inbound dependency count	Dependency	warning	Flags modules with a high number of inbound dependencies.	Every feature imports a broad platform module that owns unrelated concerns.	Review whether the module has too many responsibilities. Split unrelated responsibilities into clearer modules. Keep intentional shared-platform modules documented with ADR context.	View rule page
AP-DEP-010	Dependency violates architecture layer direction	Dependency	error	Flags dependencies that point against the configured architecture layer direction.	platform imports repositories because a helper lives there.	Move shared code to an allowed lower-level module. Reverse the dependency through an interface or event. Update layer configuration only if the architecture decision changed.	View rule page
AP-DEP-011	Cross-component dependency policy violation	Dependency	error	Flags dependencies between components that violate the configured cross-component policy.	apps/web imports implementation files from apps/api/src/modules/billing.	Route the dependency through an allowed API, package, or event boundary. Move shared code into an approved shared component. Update policy only when the architecture decision changed and is documented.	View rule page

Dependency Rules & Module Contracts Policy & ADR Workflows Rule Catalog

Next steps

Application Layering API Contract Rules