Module dependency boundaries

Question and use cases

Consumers depend on owner Contracts; the host composes concrete adapters.

Use this view before adding a project reference or designing a cross-module collaboration.

Use the diagram during design review, incident diagnosis, code walkthroughs, and onboarding. It intentionally omits classes and projects unrelated to the focused question, so read it together with the source entry point and related topic pages.

This page covers only the named responsibilities and relationships; consult the relevant module documentation for capabilities not shown here.

Reading path

1. Step 1: Locate the capability owner and its public Contracts project.
2. Step 2: Follow allowed references toward contracts and ports, never toward another module’s Infrastructure.
3. Step 3: Read the composition root last; it selects adapters without transferring domain ownership.

Do not skip arrow direction, numbering, or group titles: they express dependency or time direction, execution order, and responsibility boundaries. If the diagram differs from current source or accepted architecture decisions, correct the generated catalog immediately.

Legend and notation

This is a ARCHITECTURE diagram. Use that form to understand the layout, then test your interpretation against the source facts below.

Key relationships and design meaning

Relationship 1

Source fact: A consuming module references the owner module’s public Contracts, never its Infrastructure project.

Architectural meaning: The owner controls contract evolution; consumers gain a supported surface without gaining access to private implementation details.

Review action: Can the consumer depend on an owner-defined contract instead of an implementation project?

Relationship 2

Source fact: The API host is the composition root that selects concrete adapters after fail-closed defaults are registered.

Architectural meaning: Adapter selection stays centralized, so domain projects do not acquire vendor, database, or host dependencies.

Review action: Would an integration event remove temporal coupling?

Relationship 3

Source fact: Generated registration indexes keep module discovery at compile time.

Architectural meaning: Compile-time discovery turns missing registration into build-time evidence and avoids environment-dependent assembly scanning.

Review action: Does the proposed reference preserve the dependency rule enforced by architecture tests?

Design review questions

Answer each question when reviewing or implementing a related change. If code, tests, or an ADR cannot support the answer, do not decide from the diagram alone.

• Can the consumer depend on an owner-defined contract instead of an implementation project?
• Would an integration event remove temporal coupling?
• Does the proposed reference preserve the dependency rule enforced by architecture tests?

How to use the answers

1. Identify the single owner of the capability or rule.
2. Confirm that dependency, call, or event direction does not reverse ownership.
3. Capture the conclusion with an automated test or repeatable command.

Boundaries and common mistakes

Boundary 1

A shared DTO is not permission to share a database table or aggregate.

• Do not infer: A connector in the diagram does not mean every implementation uses synchronous calls, a shared transaction, or shared data ownership.
• Review requirement: Would an integration event remove temporal coupling?

Boundary 2

Cross-module behavior belongs behind an owner-defined port or integration event.

• Do not infer: A connector in the diagram does not mean every implementation uses synchronous calls, a shared transaction, or shared data ownership.
• Review requirement: Does the proposed reference preserve the dependency rule enforced by architecture tests?

Source verification and regeneration

The primary verification entry point is .ai/constraints/architecture-rules.md. Inspect it and its direct references before regenerating diagram assets and pages.

# Regenerate bilingual SVG, standalone HTML, and documentation pages
npm run diagrams

# Check locale pairs, references, safety attributes, accessibility, and canvas bounds
npm run verify:diagrams

# Confirm that generation changed only the intended diagrams and pages
git diff -- scripts/diagrams diagram-sources public/diagrams src/content/docs

# Verify internal links, MDX structure, and professional depth gates
npm run verify:docs
npm run audit:docs-depth

Change-completion checklist

• Responsibilities, order, states, and relationships match current source.
• Every new element helps answer this page’s question instead of turning the diagram into an inventory.
• Arrows have explicit direction and semantics without implying nonexistent synchronous or transactional guarantees.
• Chinese and English titles, labels, facts, and boundaries remain semantically equivalent.
• The diagram remains readable on narrow screens, in fullscreen, and while zoomed, with no overlap or overflow.
• Relevant architecture tests, integration tests, or verification commands have run.
• If a long-lived constraint changed, its ADR or architecture documentation is updated.

Continue reading

• Architecture overview
• All architecture diagrams
• Platform modules