aw-spec-cli 0.1.9 → 0.1.11

package/assets/guardrails/technology/java-spring/clean-architecture.md

@@ -0,0 +1,960 @@
+# Backend Clean Architecture Guidelines
+
+> Common technology guardrail for AppWeaver Java/Spring applications.
+>
+> AppWeaver Java applications use Hexagonal Architecture (Ports and Adapters) within a Modular Monolith.
+>
+> This document defines architectural boundaries and dependency rules. It does not define domain-specific business behavior, module-specific business rules, or database-specific implementation standards.
+
+---
+
+## 1. Architecture Pattern
+
+AppWeaver Java applications MUST follow **Hexagonal Architecture (Ports and Adapters)**.
+
+The application MAY be organized as a **Modular Monolith**, where multiple cohesive modules exist within a single deployable application.
+
+Hexagonal Architecture defines dependency direction.
+
+Modular Monolith defines module ownership and module boundaries.
+
+Both MUST be applied together.
+
+The architecture MUST prevent business logic from becoming coupled to:
+
+- Spring MVC
+- Spring Security
+- JPA
+- Hibernate
+- JDBC
+- database implementations
+- external service SDKs
+- messaging frameworks
+- HTTP-specific types
+- servlet APIs
+
+---
+
+## 2. AppWeaver Java Foundation Structure
+
+All production Java code MUST follow the predefined AppWeaver Java foundation.
+
+The mandatory production source root is:
+
+```text
+backend/src/main/java/io/appweaver/
+````
+
+The established architectural structure is:
+
+```text
+backend/src/main/java/io/appweaver/
+├── adapter/
+├── application/
+├── domain/
+└── infrastructure/
+```
+
+These four architectural areas MUST remain the primary structure of the application.
+
+AI agents MUST NOT introduce alternative top-level architectural structures such as:
+
+```text
+controller/
+service/
+repository/
+feature/
+features/
+verticalslice/
+usecase/
+persistence/
+```
+
+directly under:
+
+```text
+backend/src/main/java/io/appweaver/
+```
+
+New packages MUST be created within the established foundation structure.
+
+The exact subpackage structure MUST follow the active AppWeaver Java foundation and existing project conventions.
+
+---
+
+## 3. Architectural Layers
+
+### 3.1 Domain
+
+The domain layer contains business concepts, rules, and invariants.
+
+The domain MAY contain:
+
+* entities;
+* aggregates;
+* value objects;
+* domain services;
+* domain events;
+* domain policies;
+* domain-specific exceptions;
+* domain abstractions required by genuine domain rules.
+
+The domain MUST remain independent of infrastructure and delivery frameworks.
+
+The domain MUST NOT directly depend on:
+
+* Spring;
+* Spring Boot;
+* Spring MVC;
+* Spring Security;
+* JPA;
+* Hibernate;
+* JDBC;
+* Servlet APIs;
+* HTTP types;
+* database-specific APIs;
+* external SDKs.
+
+Domain objects MUST enforce applicable business invariants.
+
+Value objects SHOULD be immutable.
+
+Domain events SHOULD remain framework-independent.
+
+---
+
+## 4. Application Layer
+
+The application layer coordinates application use cases.
+
+It MAY contain:
+
+* input ports;
+* output ports;
+* use-case implementations;
+* application services;
+* commands;
+* queries;
+* application results;
+* application-level policies;
+* application-specific exceptions;
+* transaction boundaries.
+
+The application layer MUST depend inward toward the domain.
+
+The application layer MUST NOT depend on concrete adapters or infrastructure implementations.
+
+Application use cases SHOULD be represented through explicit input ports.
+
+Example:
+
+```java
+public interface CreateProjectUseCase {
+
+    ProjectResult create(CreateProjectCommand command);
+}
+```
+
+An application service MAY implement the input port:
+
+```java
+public class CreateProjectService implements CreateProjectUseCase {
+
+    private final LoadProjectPort loadProjectPort;
+    private final SaveProjectPort saveProjectPort;
+
+    // ...
+}
+```
+
+The application layer MUST depend on output port interfaces rather than concrete persistence or external-system implementations.
+
+---
+
+## 5. Input Ports
+
+Input ports represent application capabilities exposed to inbound adapters.
+
+Example:
+
+```java
+public interface CreateProjectUseCase {
+
+    ProjectResult create(CreateProjectCommand command);
+}
+```
+
+Input ports SHOULD:
+
+* represent meaningful application capabilities;
+* use application-level input and output models;
+* remain independent of HTTP;
+* remain independent of Spring MVC;
+* remain independent of persistence implementation.
+
+Input ports MUST NOT expose:
+
+* HTTP request objects;
+* HTTP response objects;
+* JPA entities;
+* Hibernate objects;
+* Servlet objects;
+* Spring Security objects;
+
+as part of their application contract.
+
+---
+
+## 6. Output Ports
+
+Output ports define dependencies required by the application from external systems.
+
+Examples include:
+
+```text
+LoadProjectPort
+SaveProjectPort
+PublishDomainEventPort
+PaymentGatewayPort
+NotificationPort
+```
+
+Example:
+
+```java
+public interface LoadProjectPort {
+
+    Optional<Project> loadById(ProjectId projectId);
+}
+```
+
+Output ports MUST be interfaces owned by the application side of the architecture.
+
+Concrete implementations MUST reside in the appropriate outbound adapter or infrastructure area.
+
+The application MUST NOT depend on concrete:
+
+* JPA repositories;
+* JDBC implementations;
+* REST clients;
+* external SDKs;
+* messaging clients.
+
+---
+
+## 7. Inbound Adapters
+
+Inbound adapters translate external requests into application calls.
+
+Examples include:
+
+* REST controllers;
+* messaging consumers;
+* scheduled-job adapters;
+* CLI adapters;
+* other external entry points.
+
+For REST APIs, controllers MUST:
+
+* receive HTTP requests;
+* perform appropriate boundary validation;
+* map API contracts to application inputs;
+* invoke application input ports;
+* map application results to API responses.
+
+Controllers MUST remain thin.
+
+Controllers MUST NOT contain domain business logic.
+
+Controllers MUST NOT directly access:
+
+* JPA repositories;
+* EntityManager;
+* Hibernate;
+* JDBC;
+* database connections;
+* persistence entities;
+* external SDKs;
+* outbound persistence implementations.
+
+The preferred flow is:
+
+```text
+HTTP Request
+     ↓
+Inbound Adapter
+     ↓
+Application Input Port
+     ↓
+Application Use Case
+     ↓
+Domain
+     ↓
+Application Result
+     ↓
+Inbound Adapter
+     ↓
+HTTP Response
+```
+
+---
+
+## 8. Outbound Adapters
+
+Outbound adapters implement application output ports.
+
+Examples include:
+
+* JPA persistence adapters;
+* REST clients;
+* messaging adapters;
+* file-system adapters;
+* external service integrations.
+
+Outbound adapters MAY depend on:
+
+* Spring;
+* JPA;
+* Hibernate;
+* JDBC;
+* external SDKs;
+* infrastructure-specific libraries.
+
+These technology dependencies MUST NOT leak into the domain.
+
+Example:
+
+```text
+Application Output Port
+        ↑
+        │ implements
+        │
+Outbound Adapter
+        ↓
+Technology
+```
+
+For persistence:
+
+```text
+Application Output Port
+        ↑
+        │
+JPA Persistence Adapter
+        ↓
+JPA / Hibernate
+        ↓
+Database
+```
+
+---
+
+## 9. Infrastructure
+
+Infrastructure contains technology-specific implementations and configuration.
+
+Infrastructure MAY contain:
+
+* Spring configuration;
+* persistence configuration;
+* datasource configuration;
+* security configuration;
+* messaging configuration;
+* external client configuration;
+* framework integration;
+* infrastructure-specific beans.
+
+Infrastructure MAY depend on framework and technology APIs.
+
+Domain code MUST NOT depend on infrastructure.
+
+Application code MUST NOT depend on concrete infrastructure implementations.
+
+---
+
+## 10. Persistence Boundary
+
+Persistence implementation MUST remain outside the domain model.
+
+JPA entities MUST NOT automatically be treated as domain entities.
+
+Where separate persistence and domain models are used:
+
+```text
+Domain Model
+     ↑
+Mapping
+     ↑
+Persistence Model
+     ↑
+JPA / Hibernate
+```
+
+Persistence entities MUST NOT be exposed directly through:
+
+* REST APIs;
+* application contracts;
+* domain APIs.
+
+Persistence mapping MUST remain within the appropriate outbound adapter/infrastructure boundary.
+
+The persistence technology MUST NOT dictate the domain model.
+
+Database-specific implementation rules MUST be defined by the applicable persistence/database guardrails rather than this document.
+
+---
+
+## 11. Dependency Rule
+
+Dependencies MUST point toward the application/domain core.
+
+The preferred dependency direction is:
+
+```text
+Inbound Adapter
+      ↓
+Application Input Port
+      ↓
+Application
+      ↓
+Domain
+
+Application
+      ↓
+Output Port
+      ↑
+Outbound Adapter
+      ↓
+Infrastructure / External Technology
+```
+
+The domain MUST NOT depend on:
+
+* application;
+* adapter;
+* infrastructure.
+
+The application MUST NOT depend on:
+
+* inbound adapters;
+* outbound adapters;
+* infrastructure implementations.
+
+Adapters and infrastructure depend inward through application contracts and ports.
+
+---
+
+## 12. Dependency Inversion
+
+The application core MUST own the interfaces required to communicate with external systems.
+
+Example:
+
+```text
+Application
+    |
+    | owns
+    ↓
+SaveProjectPort
+    ↑
+    | implements
+    |
+JpaProjectAdapter
+```
+
+This prevents:
+
+* persistence;
+* messaging;
+* HTTP clients;
+* external SDKs;
+
+from becoming direct dependencies of the application core.
+
+---
+
+## 13. Application Services
+
+Application services implement or coordinate application use cases.
+
+They SHOULD:
+
+* coordinate application operations;
+* invoke domain behavior;
+* use output ports;
+* enforce application-level policies;
+* define appropriate transaction boundaries;
+* return application-level results.
+
+Application services MUST NOT contain HTTP-specific behavior.
+
+Application services MUST NOT depend directly on:
+
+* controllers;
+* HTTP request/response objects;
+* JPA repositories;
+* EntityManager;
+* Hibernate;
+* external SDK implementations.
+
+---
+
+## 14. Transaction Boundaries
+
+Transaction boundaries SHOULD normally be established at the application use-case boundary.
+
+Spring transaction management MAY be used to implement application transaction boundaries.
+
+Example:
+
+```java
+@Transactional
+public ProjectResult create(CreateProjectCommand command) {
+    ...
+}
+```
+
+Transaction configuration MUST NOT introduce persistence implementation details into the domain.
+
+Transactions SHOULD represent a coherent application operation.
+
+Cross-module transactions MUST NOT be introduced merely to simplify module interaction.
+
+When cross-module consistency is required, the application SHOULD use an explicitly approved consistency mechanism such as:
+
+* domain events;
+* application events;
+* messaging;
+* transactional outbox;
+* compensating actions.
+
+The selected mechanism MUST follow the application's architecture and consistency requirements.
+
+---
+
+## 15. Modular Monolith Boundaries
+
+The application MAY contain multiple modules within the same deployable application.
+
+Each module SHOULD own its:
+
+* domain model;
+* application use cases;
+* persistence implementation;
+* external integrations;
+* public module contracts.
+
+Modules MUST NOT access another module's internal implementation directly.
+
+Forbidden examples include:
+
+```text
+Module A → Module B Repository
+
+Module A → Module B JPA Entity
+
+Module A → Module B Persistence Adapter
+
+Module A → Module B Infrastructure Configuration
+```
+
+Modules MAY interact through explicitly exposed contracts or application capabilities.
+
+Cross-module dependencies MUST be intentional and MUST NOT bypass module boundaries.
+
+A module MUST NOT access another module's database tables or persistence internals merely because they exist in the same physical database.
+
+---
+
+## 16. Domain Model Independence
+
+Domain objects MUST represent business concepts rather than persistence or transport concerns.
+
+Avoid:
+
+```text
+Domain Entity
+      ↓
+JPA Mapping
+      ↓
+Database
+```
+
+as an architectural dependency direction.
+
+Prefer:
+
+```text
+Domain Model
+      ↑
+Mapping
+      ↑
+Persistence Model
+```
+
+Similarly, API contracts MUST remain separate:
+
+```text
+API Contract
+      ↓
+Application
+      ↓
+Domain
+```
+
+The domain model MUST NOT become an API DTO or persistence entity merely to reduce mapping code.
+
+---
+
+## 17. API Boundary
+
+REST API contracts MUST remain at the inbound adapter boundary.
+
+API request and response DTOs/records MUST NOT become domain entities.
+
+The preferred flow is:
+
+```text
+HTTP Request
+    ↓
+API Request DTO / Record
+    ↓
+Input Port
+    ↓
+Application
+    ↓
+Domain
+    ↓
+Application Result
+    ↓
+API Response DTO / Record
+    ↓
+HTTP Response
+```
+
+API versioning MUST follow:
+
+```text
+api-versioning.md
+```
+
+Global exception handling MUST follow:
+
+```text
+global_exception_handler.md
+```
+
+Problem Details representation MUST follow:
+
+```text
+problem_details.md
+```
+
+Result-to-HTTP mapping MUST follow:
+
+```text
+result_mapping.md
+```
+
+This document MUST NOT redefine those concerns.
+
+---
+
+## 18. Cross-Cutting Concerns
+
+Cross-cutting concerns are implemented when required by the application.
+
+They are NOT automatically mandatory for every application.
+
+When a cross-cutting concern is required, its dedicated AppWeaver technology guardrail MUST be followed.
+
+Applicable Java/Spring guardrails include:
+
+```text
+authorization.md
+domain_abstraction.md
+global_exception_handler.md
+logging.md
+problem_details.md
+result_mapping.md
+```
+
+This document MUST NOT redefine the implementation rules of those concerns.
+
+---
+
+## 19. Architecture Validation
+
+Projects SHOULD use automated architecture tests to enforce the architectural boundaries.
+
+ArchUnit MAY be used for this purpose.
+
+The project MAY use another approved architecture-validation mechanism.
+
+Recommended rules include:
+
+### Domain independence
+
+```text
+Domain classes MUST NOT depend on Spring.
+
+Domain classes MUST NOT depend on JPA.
+
+Domain classes MUST NOT depend on Hibernate.
+
+Domain classes MUST NOT depend on HTTP.
+
+Domain classes MUST NOT depend on Servlet APIs.
+
+Domain classes MUST NOT depend on infrastructure.
+
+Domain classes MUST NOT depend on inbound adapters.
+
+Domain classes MUST NOT depend on outbound adapters.
+```
+
+### Application independence
+
+```text
+Application classes MUST NOT depend on concrete adapters.
+
+Application classes MUST NOT depend on infrastructure implementations.
+
+Application classes MUST use output ports for external dependencies.
+```
+
+### Inbound adapter rules
+
+```text
+Inbound adapters MUST use application input ports.
+
+Inbound adapters MUST NOT directly access persistence implementations.
+
+Inbound adapters MUST NOT directly access outbound adapters.
+```
+
+### Module rules
+
+```text
+A module MUST NOT access another module's internal persistence.
+
+A module MUST NOT access another module's internal adapters.
+
+A module MUST NOT access another module's infrastructure implementation.
+```
+
+The exact architecture tests MUST follow the actual package structure of the application.
+
+This document MUST NOT assume that a specific class such as `ArchitectureTest.java` exists.
+
+---
+
+## 20. Testing Strategy
+
+Testing MUST respect architectural boundaries.
+
+Recommended baseline:
+
+| Layer                | Recommended Test Type      | Typical Tools                      |
+| -------------------- | -------------------------- | ---------------------------------- |
+| Domain               | Unit tests                 | JUnit 5                            |
+| Application          | Unit tests                 | JUnit 5, Mockito where appropriate |
+| Inbound REST Adapter | Integration/slice tests    | Spring Boot Test, MockMvc          |
+| Persistence Adapter  | Integration tests          | Spring Boot Test, Testcontainers   |
+| External Adapter     | Integration/contract tests | Appropriate adapter/test tooling   |
+| Full Application     | Integration tests          | Spring Boot Test, Testcontainers   |
+| Architecture         | Architecture tests         | ArchUnit                           |
+
+The exact testing tools MAY be defined by the active project constitution.
+
+Domain tests SHOULD remain framework-independent.
+
+Integration tests SHOULD use real infrastructure when behavior depends on database or external-system integration.
+
+Testcontainers SHOULD be preferred for integration tests that require real infrastructure compatibility, where practical.
+
+---
+
+## 21. Test Isolation
+
+Tests MUST NOT require production infrastructure.
+
+Integration tests MUST use isolated test resources.
+
+Tests MUST NOT:
+
+* connect to production databases;
+* use production credentials;
+* modify shared production data;
+* depend on developer-specific local configuration.
+
+Test configuration MUST remain separate from production configuration.
+
+---
+
+## 22. AI / AW-Spec Rules
+
+AI-generated code MUST:
+
+* inspect the existing AppWeaver Java foundation before creating files;
+* inspect the owning module before modifying code;
+* follow the established `adapter`, `application`, `domain`, and `infrastructure` structure;
+* identify the correct architectural layer before creating a class;
+* reuse existing ports and application capabilities where appropriate;
+* preserve dependency direction;
+* keep domain code framework-independent;
+* keep persistence implementations outside the domain;
+* keep API contracts outside the domain;
+* respect Modular Monolith module boundaries;
+* use existing cross-cutting implementations when applicable;
+* add or update appropriate tests.
+
+AI agents MUST NOT:
+
+* introduce Vertical Slice Architecture;
+* introduce a competing architecture;
+* create a new top-level architectural package;
+* create speculative abstractions;
+* make controllers directly access persistence;
+* expose persistence entities as API contracts;
+* access another module's internal implementation;
+* move framework-specific logic into the domain;
+* introduce cross-module transactions without explicit approval;
+* duplicate application or domain logic merely to support different adapters;
+* introduce technology-specific persistence rules into the domain layer.
+
+---
+
+## 23. Forbidden Patterns
+
+The following patterns are forbidden:
+
+```text
+Controller → JPA Repository
+
+Controller → EntityManager
+
+Controller → Hibernate
+
+Controller → JDBC
+
+Controller → Database Connection
+
+Controller → Persistence Entity
+
+Controller → External SDK
+
+Domain → Spring
+
+Domain → JPA
+
+Domain → Hibernate
+
+Domain → HTTP
+
+Domain → Servlet API
+
+Domain → Spring Security
+
+Application → Concrete Persistence Adapter
+
+Application → Concrete External SDK
+
+Application → Infrastructure Implementation
+
+Module A → Module B Internal Repository
+
+Module A → Module B Internal JPA Entity
+
+Module A → Module B Infrastructure
+
+API DTO → Persistence Entity Exposure
+```
+
+---
+
+## 24. Foundation Package Placement
+
+All production Java code MUST remain under:
+
+```text
+backend/src/main/java/io/appweaver/
+```
+
+The established architectural areas are:
+
+```text
+backend/src/main/java/io/appweaver/
+├── adapter/
+├── application/
+├── domain/
+└── infrastructure/
+```
+
+Responsibility MUST determine package placement.
+
+General responsibilities are:
+
+```text
+adapter/
+    External entry points and technology-facing adapters.
+
+application/
+    Use cases, application contracts, ports, and application orchestration.
+
+domain/
+    Business model, business rules, invariants, and domain behavior.
+
+infrastructure/
+    Technology-specific configuration and infrastructure implementations.
+```
+
+The exact subpackage structure MUST follow the active AppWeaver Java foundation and existing project conventions.
+
+AI agents MUST NOT invent a competing folder structure.
+
+---
+
+## 25. Governance
+
+Clean Architecture changes MUST comply with:
+
+* the active AppWeaver constitution;
+* the predefined AppWeaver Java foundation;
+* Modular Monolith architecture;
+* Hexagonal Architecture principles;
+* applicable technology guardrails;
+* module-specific specifications;
+* generated AW-Spec design artifacts.
+
+Project-specific architectural decisions MUST be defined in the project's architecture and design artifacts rather than embedded into this generic technology guardrail.
+
+Changes to this document MUST follow the applicable governance and constitution amendment process.
+
+---
+
+## 26. Summary of Required Standards
+
+AppWeaver Java applications MUST follow these principles:
+
+* Hexagonal Architecture is the primary architectural pattern.
+* The application MAY be organized as a Modular Monolith.
+* Production code MUST follow the predefined AppWeaver Java foundation.
+* The primary architectural areas are `adapter`, `application`, `domain`, and `infrastructure`.
+* The domain MUST remain framework-independent.
+* Application logic MUST depend on ports rather than concrete infrastructure.
+* Inbound adapters MUST use application input ports.
+* Outbound adapters MUST implement application output ports.
+* Persistence implementations MUST remain outside the domain.
+* API contracts MUST remain at the API boundary.
+* Modules MUST NOT bypass each other's internal implementation.
+* Transaction boundaries SHOULD normally be established at the application use-case boundary.
+* Cross-cutting concerns MUST follow their dedicated technology guardrails when applicable.
+* Architecture rules SHOULD be enforced through automated architecture tests.
+* Tests MUST respect architectural boundaries.
+* AI-generated code MUST follow the existing Java foundation.
+* AI agents MUST NOT introduce Vertical Slice Architecture or another competing package structure.
+* All production Java code MUST remain within the predefined AppWeaver foundation.
+* Database-specific implementation rules MUST be maintained separately from the Clean Architecture guardrail.
+
+