domain-architecture-guidance git:20261027.72b0616A

Immutable. This exact content never changes and is served at /api/v1/blob/36ebed9113b56422.

---
name: domain-architecture-guidance
description: Authoritative architecture guidance for business-domain systems using Domain-Driven Design, Layered Architecture, Onion Architecture, Hexagonal Architecture / Ports and Adapters, and CQRS. Use when designing, reviewing, refactoring, documenting, or implementing domain-heavy systems with package/project boundaries, repositories, aggregates, application services, ports/adapters, CQRS, jMolecules-style annotations, or architecture tests.
---

# Domain Architecture Guidance

## Purpose

Use this skill to guide AI agents and developers in correctly applying Domain-Driven Design, Layered Architecture, Onion Architecture, Hexagonal Architecture / Ports and Adapters, and CQRS in backend business-domain systems. It can also guide client applications when they own substantial business rules, offline workflows, synchronization conflicts, or local persistence boundaries. It does not provide platform-specific mobile or frontend implementation templates. Treat jMolecules as a strong Java reference for expressing and validating DDD and architecture concepts in code, not as a universal framework that every language must copy.

Do not present DDD, Layered, Onion, Hexagonal, CQRS, or Event Sourcing as one canonical combined architecture. Distinguish foundational patterns from opinionated compositions.

DDD is a domain modeling methodology and language for business concepts, boundaries, and invariants. Layered, Onion, Hexagonal / Ports and Adapters, and CQRS are architecture styles or patterns that can host or support DDD in domain-heavy systems, but they are not owned by DDD and should not be reduced to DDD. When a project explicitly chooses one of those architectures, enforce its dependency, boundary, and responsibility rules consistently.

## Workflow

1. Identify the task type: architecture explanation, code review, implementation, refactoring, package/project layout, jMolecules annotation usage, architecture test, or documentation.
2. Determine the stack and runtime role: Java/Kotlin, C#/.NET, Go, Python, or another ecosystem. For a client application, confirm that it owns substantial domain behavior before applying backend-style patterns. Prefer host-ecosystem idioms over imported templates.
3. Consume an applicable `Domain Modeling Result` or explicit project evidence. Record the domain model complexity and the decisions relevant to the requested architecture work. Only confirmed domain decisions or explicitly accepted assumptions with recorded acceptance source/evidence may drive architecture decisions. The agent must not accept an assumption itself; keep unaccepted `inferred` or `proposed` items as uncertainty or open questions.
4. For a review, verify whether the implementation protects those domain decisions. For a design task, do not invent or rewrite a Subdomain, Bounded Context, invariant, lifecycle, Aggregate, or Domain Event without domain evidence; return business-meaning or ownership questions to Domain Modeling.
5. Identify the chosen architecture, if any: Layered, Onion, Hexagonal / Ports and Adapters, CQRS, mixed, or none. If one is chosen, apply its structural constraints before suggesting simplification.
6. Select the architecture complexity justified by the requested decision. Add CQRS, strict ports/adapters, integration mechanisms, or other structural ceremony only when the consumed domain needs and project constraints require them; do not infer those choices from domain model complexity alone.
7. Read each reference whose row in Reference Routing matches this task. Skip every row that does not match. Do not read the skill directory recursively.
8. State uncertainty explicitly when a rule is context-dependent.
9. For architecture decisions, reviews, and boundary-affecting implementation recommendations, produce an `Architecture Guidance Result` from `references/architecture-result.md` with consumed domain decisions, traceable architecture consequences, rule sources, constraints, evidence, open questions, and readiness for the recommended next step. Simple conceptual explanations and documentation answers may remain concise unless the user asks for a structured result.

## Core Rules

- Prefer original and broadly recognized sources over blog-style synthesis.
- When a project chooses DDD, enforce its core modeling discipline: ubiquitous language, explicit bounded-context meaning, invariant-protecting aggregates, identity/value distinction, and behavior placed where it best protects rules. Do not treat DDD as optional decoration after that choice is made.
- Base architecture decisions only on confirmed domain decisions or assumptions with an explicit acceptance source/evidence; the agent cannot promote its own inference or proposal. If an unaccepted item blocks a responsible architecture decision, preserve unaffected conclusions, route the smallest blocking business question to Domain Modeling, and use `needs-input` only for the dependent Architecture Guidance result.
- Treat Domain Modeling as the owner of business meaning and ownership. Architecture Guidance may protect and map domain decisions, but a proposed structural choice that changes them requires renewed domain modeling.
- Do not weaken explicit architecture constraints. Apply only the constraints supplied by the selected style or an explicit project policy. For example, strict Layered and Hexagonal projects usually route controllers through application/use-case boundaries, while foundational Onion Architecture requires inward dependencies but does not itself require every controller call to pass through an application service. If the project has chosen CQRS, enforce command/query responsibility separation, query non-mutation, and read/write model boundaries without importing unrelated layer rules.
- Do not upgrade implementation preferences into universal DDD rules. Repository naming, read-port suffixes, CQRS, Event Sourcing, package layout, jMolecules annotations, and ArchUnit tests become strict only when selected by the architecture, framework, or project policy.
- Use jMolecules primarily for Java/Kotlin code annotation, architecture expression, validation, and documentation.
- For C#/.NET, Go, and Python, translate concepts into idiomatic modules, packages, namespaces, protocols/interfaces, tests, and dependency rules.
- Apply this skill to client applications only when they own substantial business behavior, offline workflows, synchronization conflicts, or local persistence boundaries. Do not imply platform-specific mobile or frontend implementation guidance.
- Keep the domain model free of framework persistence concerns when the domain is behavior-rich; allow simpler transaction script or CRUD designs for low-complexity areas.
- Keep a use-case transaction around local aggregate load, domain behavior, and save only. Do not leave it open across outbound HTTP, client-SDK, or broker calls; reload and recheck in a later short transaction. See Transaction Boundaries in `references/architecture-constraints.md`.
- A secondary adapter translates an outbound contract. It does not load an aggregate and invoke state-changing domain behavior; an application service owns that orchestration. A persistence adapter may depend on the aggregate only to translate its state. See the Hexagonal constraints in `references/architecture-constraints.md`.
- A bounded-context crossing includes another context's stored state, not only a Java type dependency. See Bounded Context Crossings in `references/architecture-constraints.md`.
- Treat CQRS as a targeted pattern for asymmetric read/write needs, complex queries, scalability differences, or task-based write models. Do not make every use case CQRS by default.
- Treat Event Sourcing as separate from CQRS. Do not introduce it unless auditability, temporal reconstruction, or event replay is a real requirement.
- Avoid saying "must" unless the rule follows from the chosen architecture and project context. Prefer "usually", "in this architecture", or "for this bounded context".

## Reference Routing

Read each row that matches the current task. Skip every row that does not match. Do not read the skill directory recursively.

| Current task | Read |
|---|---|
| Conceptual explanation or documentation answer | No reference |
| Judging a dependency or call path, or changing a boundary | `references/architecture-constraints.md` |
| Making a normative claim, choosing a source, or handling Explicit Architecture or Clean Architecture terminology | `references/source-policy.md` |
| Changing code or recommending structure | `references/backend-guidance.md`, using the shared sections and the one section for the stack chosen above. Retrieve current upstream documentation before using an exact framework or library API. |
| Reviewing or changing package granularity, domain type semantics, model naming, port or adapter naming, or marker-based architecture tests | `references/package-and-type-semantics.md`, including its Package And Type Semantics Preflight |
| Returning an architecture decision, review, or boundary-affecting recommendation | `references/architecture-result.md` |
| Selected or proposed Hexagonal / Ports and Adapters work, including port roles, adapter direction, or application-service naming | `references/hexagonal-architecture.md` in addition to the constraints reference when a boundary is also in scope |
| Selecting, implementing, or reviewing architecture validation | `references/architecture-testing.md`, using the one section for the stack chosen above |
| Confirmed jfoundry landing for a Java project | `using-jfoundry`, instead of treating the Java example as a jfoundry template |

When a selected reference has separate stack sections, read its shared sections and the one section for the stack chosen above. Do not apply another stack's section.