aw-spec-cli 0.1.10 → 0.1.11

package/assets/guardrails/technology/java-spring/folder-structure.md

@@ -0,0 +1,1537 @@
+# Java Hexagonal Architecture — Reusable Project Structure Standard
+
+## 1. Purpose
+
+This document defines the standard project architecture and folder structure for Java applications generated through the AW-Spec spec-driven development pipeline.
+
+This document is **project-agnostic** and MUST be reusable across Java projects regardless of the business domain.
+
+Examples of projects that MAY use this standard:
+
+* Flight Booking
+* Library Management
+* Project Allocation
+* Healthcare
+* Banking
+* E-commerce
+* Order Management
+* Any other Java/Spring Boot application
+
+The business domain MUST NOT determine the top-level architectural structure.
+
+The project specification determines the business-specific classes, features, entities, use cases, and adapters that are created within this structure.
+
+---
+
+# 2. Architectural Style
+
+The default architecture is:
+
+**Hexagonal Architecture (Ports and Adapters)**
+
+with:
+
+* Domain-driven design principles
+* Application/use-case layer
+* Inbound and outbound ports
+* Infrastructure adapters
+* Dependency inversion
+* Technology isolation from the domain
+
+The architecture MUST separate business rules from technical implementation details.
+
+The primary architectural boundaries are:
+
+```text
+adapter
+    ↓
+application
+    ↓
+domain
+
+infrastructure
+    ↓
+application ports
+    ↓
+domain
+```
+
+Infrastructure implements application-defined outbound contracts.
+
+---
+
+# 3. Architecture Goals
+
+The generated project MUST aim for:
+
+* Clear separation of concerns
+* Dependency inversion
+* Domain independence
+* Testability
+* Replaceable infrastructure
+* Explicit use cases
+* Explicit external boundaries
+* Consistent package organization
+* Predictable code generation
+* Maintainable project structure
+
+The folder structure is an architectural contract and MUST NOT be treated merely as a naming convention.
+
+---
+
+# 4. Standard Project Structure
+
+Every project using this architecture SHOULD start with the following structure:
+
+```text
+<project-root>/
+│
+├── src/
+│   ├── main/
+│   │   ├── java/
+│   │   │   └── <base-package>/
+│   │   │       │
+│   │   │       ├── adapter/
+│   │   │       │
+│   │   │       ├── application/
+│   │   │       │
+│   │   │       ├── domain/
+│   │   │       │
+│   │   │       ├── infrastructure/
+│   │   │       │
+│   │   │       └── Application.java
+│   │   │
+│   │   └── resources/
+│   │
+│   └── test/
+│       └── java/
+│           └── <base-package>/
+│
+├── pom.xml
+└── README.md
+```
+
+The exact build tool MAY differ.
+
+For Maven:
+
+```text
+pom.xml
+```
+
+For Gradle:
+
+```text
+build.gradle
+```
+
+or:
+
+```text
+build.gradle.kts
+```
+
+The architectural package structure MUST remain independent of the build tool.
+
+---
+
+# 5. Base Package
+
+All application code MUST reside below a single root Java package.
+
+Example:
+
+```text
+com.company.application
+```
+
+or:
+
+```text
+io.appweaver
+```
+
+The base package MUST be determined by the project specification or foundation configuration.
+
+The architecture document MUST NOT hard-code a specific organization or application package.
+
+Example:
+
+```text
+<base-package>/
+├── adapter/
+├── application/
+├── domain/
+├── infrastructure/
+└── Application.java
+```
+
+---
+
+# 6. Top-Level Architectural Packages
+
+The standard top-level structure is:
+
+```text
+<base-package>/
+├── adapter/
+├── application/
+├── domain/
+├── infrastructure/
+└── Application.java
+```
+
+Each package has a distinct responsibility.
+
+| Package            | Responsibility                          |
+| ------------------ | --------------------------------------- |
+| `adapter`          | External entry and exit mechanisms      |
+| `application`      | Use cases and application orchestration |
+| `domain`           | Business model and business rules       |
+| `infrastructure`   | Technology-specific implementations     |
+| `Application.java` | Application bootstrap                   |
+
+---
+
+# 7. Adapter Layer
+
+## Location
+
+```text
+adapter/
+```
+
+The adapter layer contains implementations that connect the application to external interfaces.
+
+The adapter layer MAY contain:
+
+```text
+adapter/
+├── in/
+└── out/
+```
+
+---
+
+# 8. Inbound Adapters
+
+Inbound adapters represent external systems calling the application.
+
+Standard structure:
+
+```text
+adapter/
+└── in/
+    ├── controller/
+    ├── messaging/
+    └── ...
+```
+
+Only required adapter types SHOULD be created.
+
+For a REST application:
+
+```text
+adapter/
+└── in/
+    └── controller/
+```
+
+Example:
+
+```text
+adapter/
+└── in/
+    └── controller/
+        └── <Feature>Controller.java
+```
+
+Examples of other inbound adapters:
+
+```text
+adapter/in/
+├── controller/
+├── messaging/
+├── scheduler/
+└── cli/
+```
+
+These are optional and MUST only be created when required by the project.
+
+---
+
+# 9. Inbound Adapter Responsibilities
+
+Inbound adapters MUST:
+
+* Receive external input.
+* Translate external input into application contracts.
+* Invoke inbound application ports.
+* Translate application results into external responses.
+* Handle transport-specific concerns.
+
+Inbound adapters MUST NOT:
+
+* Contain domain business rules.
+* Access repositories directly.
+* Access JPA repositories directly.
+* Access persistence entities directly.
+* Implement application use cases.
+* Implement domain behavior.
+
+The dependency direction MUST be:
+
+```text
+Inbound Adapter
+       ↓
+Inbound Application Port
+```
+
+---
+
+# 10. Outbound Adapters
+
+Outbound adapters represent external systems used by the application.
+
+Standard structure:
+
+```text
+adapter/
+└── out/
+```
+
+Possible examples:
+
+```text
+adapter/out/
+├── external/
+├── messaging/
+├── notification/
+└── ...
+```
+
+Outbound adapters are optional.
+
+They SHOULD be created only when the application communicates with external systems.
+
+Examples:
+
+* REST clients
+* External APIs
+* Message brokers
+* Email providers
+* Payment gateways
+* File storage
+* Third-party services
+
+---
+
+# 11. Application Layer
+
+Location:
+
+```text
+application/
+```
+
+The application layer defines and orchestrates application use cases.
+
+Default structure:
+
+```text
+application/
+├── dto/
+│   ├── request/
+│   └── response/
+│
+├── port/
+│   ├── in/
+│   └── out/
+│
+└── service/
+```
+
+Optional packages MAY be added when required by the project.
+
+---
+
+# 12. Application DTOs
+
+## Request DTOs
+
+Location:
+
+```text
+application/dto/request/
+```
+
+Request DTOs represent data entering an application use case.
+
+Example:
+
+```text
+<CreateFeature>RequestDto.java
+```
+
+Rules:
+
+* DTOs MUST represent application contracts.
+* DTOs MUST NOT contain domain business logic.
+* DTOs MUST NOT depend on persistence entities.
+* DTOs SHOULD remain independent of transport-specific models where practical.
+
+---
+
+## Response DTOs
+
+Location:
+
+```text
+application/dto/response/
+```
+
+Response DTOs represent application results.
+
+Example:
+
+```text
+<CreateFeature>ResponseDto.java
+```
+
+The exact DTO naming convention MAY be adapted to project conventions.
+
+---
+
+# 13. Inbound Application Ports
+
+Location:
+
+```text
+application/port/in/
+```
+
+Inbound ports define application use cases.
+
+Example:
+
+```text
+application/
+└── port/
+    └── in/
+        └── <Feature>UseCase.java
+```
+
+Inbound ports MUST:
+
+* Define application capabilities.
+* Represent use cases.
+* Be independent of controllers.
+* Be independent of HTTP.
+* Be independent of persistence.
+* Be implemented by application services.
+
+Example conceptual relationship:
+
+```text
+Controller
+    ↓
+<Feature>UseCase
+    ↓
+<Feature>UseCaseImpl
+```
+
+---
+
+# 14. Outbound Application Ports
+
+Location:
+
+```text
+application/port/out/
+```
+
+Outbound ports define dependencies required by the application.
+
+Examples:
+
+```text
+application/port/out/
+├── <Domain>Repository.java
+├── <ExternalService>Port.java
+└── ...
+```
+
+Outbound ports MUST define contracts rather than technical implementations.
+
+For example:
+
+```text
+Application
+    ↓
+Repository Port
+```
+
+rather than:
+
+```text
+Application
+    ↓
+JpaRepository
+```
+
+The application layer MUST depend on the abstraction.
+
+---
+
+# 15. Application Services
+
+Location:
+
+```text
+application/service/
+```
+
+Application services implement inbound use cases.
+
+Example:
+
+```text
+application/service/
+└── <Feature>UseCaseImpl.java
+```
+
+Application services SHOULD:
+
+* Implement inbound ports.
+* Coordinate application operations.
+* Invoke domain behavior.
+* Invoke outbound ports.
+* Manage application-level transactions where appropriate.
+* Coordinate multiple domain objects when required.
+
+Application services MUST NOT:
+
+* Depend directly on controllers.
+* Depend directly on `JpaRepository`.
+* Contain HTTP concerns.
+* Contain database implementation details.
+* Replace domain behavior with procedural business logic when the behavior belongs to the domain.
+
+---
+
+# 16. Domain Layer
+
+Location:
+
+```text
+domain/
+```
+
+The domain layer represents the business model.
+
+Default structure:
+
+```text
+domain/
+├── entity/
+├── enums/
+├── exception/
+└── valueObjects/
+```
+
+Additional domain packages MAY be introduced when required.
+
+Possible optional packages:
+
+```text
+domain/
+├── entity/
+├── valueObjects/
+├── enums/
+├── exception/
+├── service/
+├── event/
+├── repository/
+└── ...
+```
+
+Only packages required by the project SHOULD be generated.
+
+---
+
+# 17. Domain Entities
+
+Location:
+
+```text
+domain/entity/
+```
+
+Domain entities represent business concepts with identity and behavior.
+
+Example:
+
+```text
+<DomainEntity>.java
+```
+
+Domain entities SHOULD:
+
+* Encapsulate business state.
+* Protect invariants.
+* Expose meaningful domain behavior.
+* Avoid exposing unrestricted mutable state.
+* Remain independent of infrastructure technology.
+
+Domain entities MUST NOT depend on:
+
+```text
+Spring MVC
+Spring Data
+JpaRepository
+Hibernate
+REST
+Controllers
+Infrastructure adapters
+External API clients
+```
+
+---
+
+# 18. Value Objects
+
+Location:
+
+```text
+domain/valueObjects/
+```
+
+Value objects represent domain concepts defined by their values rather than identity.
+
+Examples of conceptual value objects:
+
+```text
+Identifier
+Money
+EmailAddress
+Quantity
+Code
+Address
+```
+
+The actual value objects MUST be derived from the project domain specification.
+
+Value objects SHOULD:
+
+* Be immutable.
+* Validate their invariants.
+* Encapsulate domain-specific behavior.
+* Avoid infrastructure dependencies.
+
+---
+
+# 19. Domain Enums
+
+Location:
+
+```text
+domain/enums/
+```
+
+Enums SHOULD be used for stable domain classifications.
+
+Examples:
+
+```text
+Status
+Type
+Category
+State
+```
+
+Enums MUST represent meaningful domain concepts rather than technical implementation states.
+
+---
+
+# 20. Domain Exceptions
+
+Location:
+
+```text
+domain/exception/
+```
+
+Domain exceptions represent meaningful business failures.
+
+Examples:
+
+```text
+<DomainRule>ViolationException.java
+<DomainEntity>NotFoundException.java
+<InvalidDomainState>Exception.java
+```
+
+Exception names MUST be derived from actual domain rules.
+
+---
+
+# 21. Domain Services
+
+Location:
+
+```text
+domain/service/
+```
+
+This package is OPTIONAL.
+
+A domain service SHOULD be introduced only when a business operation:
+
+* Does not naturally belong to a single entity or value object.
+* Represents domain behavior.
+* Requires multiple domain concepts.
+
+Domain services MUST NOT be used merely to move arbitrary business logic out of entities.
+
+---
+
+# 22. Domain Events
+
+Location:
+
+```text
+domain/event/
+```
+
+This package is OPTIONAL.
+
+It SHOULD only be generated when the project requires domain events.
+
+Example:
+
+```text
+<BusinessEvent>.java
+```
+
+Domain events MUST represent business-significant occurrences rather than infrastructure events.
+
+---
+
+# 23. Infrastructure Layer
+
+Location:
+
+```text
+infrastructure/
+```
+
+Infrastructure contains technology-specific implementations.
+
+Default structure:
+
+```text
+infrastructure/
+├── config/
+└── persistence/
+```
+
+Additional infrastructure packages MAY be created when required.
+
+Possible structure:
+
+```text
+infrastructure/
+├── config/
+├── persistence/
+├── security/
+├── messaging/
+├── external/
+└── ...
+```
+
+Only required infrastructure components SHOULD be generated.
+
+---
+
+# 24. Infrastructure Configuration
+
+Location:
+
+```text
+infrastructure/config/
+```
+
+Configuration classes MAY include:
+
+* Framework configuration
+* Security configuration
+* Serialization configuration
+* Database configuration
+* Messaging configuration
+* Integration configuration
+
+Example:
+
+```text
+SecurityConfig.java
+PersistenceConfig.java
+```
+
+Configuration MUST remain outside the domain.
+
+---
+
+# 25. Persistence Structure
+
+When relational persistence using JPA is required, the default structure is:
+
+```text
+infrastructure/
+└── persistence/
+    ├── mapper/
+    ├── <Entity>JpaEntity.java
+    ├── Jpa<Entity>Repository.java
+    └── <Entity>RepositoryImpl.java
+```
+
+Persistence is OPTIONAL.
+
+Projects that do not require persistence MUST NOT generate persistence packages merely because they exist in the baseline architecture.
+
+---
+
+# 26. JPA Entities
+
+Location:
+
+```text
+infrastructure/persistence/
+```
+
+JPA entities represent the persistence model.
+
+Example:
+
+```text
+<Entity>JpaEntity.java
+```
+
+JPA entities MUST remain separate from domain entities.
+
+The architecture MUST NOT assume:
+
+```text
+Domain Entity == JPA Entity
+```
+
+Instead:
+
+```text
+Domain Entity
+      ↕
+Persistence Mapper
+      ↕
+JPA Entity
+```
+
+---
+
+# 27. Spring Data Repositories
+
+When Spring Data JPA is used:
+
+```text
+infrastructure/persistence/
+└── Jpa<Entity>Repository.java
+```
+
+Example conceptual structure:
+
+```text
+application/port/out/
+└── EntityRepository.java
+
+infrastructure/persistence/
+└── JpaEntityRepository.java
+```
+
+The application MUST depend on:
+
+```text
+EntityRepository
+```
+
+and MUST NOT directly depend on:
+
+```text
+JpaEntityRepository
+```
+
+---
+
+# 28. Repository Implementations
+
+Repository implementations adapt infrastructure persistence to the application port.
+
+Example:
+
+```text
+infrastructure/persistence/
+└── EntityRepositoryImpl.java
+```
+
+Relationship:
+
+```text
+application/port/out/EntityRepository
+                    ▲
+                    │ implements
+                    │
+infrastructure/persistence/EntityRepositoryImpl
+                    │
+                    ▼
+        JpaEntityRepository
+```
+
+This preserves dependency inversion.
+
+---
+
+# 29. Persistence Mappers
+
+Location:
+
+```text
+infrastructure/persistence/mapper/
+```
+
+Mappers convert between domain and persistence representations.
+
+Example:
+
+```text
+<Entity>Mapper.java
+```
+
+Conceptual flow:
+
+```text
+Domain Entity
+      ↓
+Persistence Mapper
+      ↓
+JPA Entity
+```
+
+and:
+
+```text
+JPA Entity
+      ↓
+Persistence Mapper
+      ↓
+Domain Entity
+```
+
+Persistence mapping MUST NOT be embedded into domain entities.
+
+---
+
+# 30. Application Bootstrap
+
+The Spring Boot application entry point SHOULD be located at the root package.
+
+Example:
+
+```text
+<base-package>/Application.java
+```
+
+The application bootstrap class MUST remain outside individual domain or feature packages.
+
+---
+
+# 31. Resources Structure
+
+The standard resource structure is:
+
+```text
+src/main/resources/
+├── application.yml
+└── ...
+```
+
+Additional directories MAY be introduced based on project requirements.
+
+Examples:
+
+```text
+src/main/resources/
+├── application.yml
+├── db/
+│   └── migration/
+├── templates/
+└── ...
+```
+
+Only required resources SHOULD be generated.
+
+---
+
+# 32. Test Structure
+
+Tests SHOULD mirror the production architecture.
+
+```text
+src/test/java/<base-package>/
+├── adapter/
+├── application/
+├── domain/
+└── infrastructure/
+```
+
+Example:
+
+```text
+src/test/java/<base-package>/
+│
+├── adapter/
+│   └── in/
+│       └── controller/
+│
+├── application/
+│   └── service/
+│
+├── domain/
+│   ├── entity/
+│   └── valueObjects/
+│
+└── infrastructure/
+    └── persistence/
+```
+
+Tests MUST be organized according to the responsibility being tested.
+
+---
+
+# 33. Dependency Rules
+
+The following dependency rules are mandatory.
+
+## Allowed
+
+```text
+Adapter → Application
+Application → Domain
+Infrastructure → Application
+Infrastructure → Domain
+```
+
+## Forbidden
+
+```text
+Domain → Infrastructure
+Domain → Adapter
+Domain → Spring
+Domain → JPA
+
+Application → Controller
+Application → JpaRepository
+Application → JPA Entity
+
+Controller → JpaRepository
+Controller → JPA Entity
+```
+
+The domain MUST remain at the center of the architecture.
+
+---
+
+# 34. Dependency Direction
+
+The target dependency model is:
+
+```text
+                 ┌───────────────────┐
+                 │   Inbound Adapter │
+                 └─────────┬─────────┘
+                           │
+                           ▼
+                 ┌───────────────────┐
+                 │    Application    │
+                 │                   │
+                 │  Inbound Ports    │
+                 │  Use Cases        │
+                 │  Outbound Ports   │
+                 └─────────┬─────────┘
+                           │
+                           ▼
+                 ┌───────────────────┐
+                 │      Domain       │
+                 │                   │
+                 │ Entities          │
+                 │ Value Objects     │
+                 │ Domain Services   │
+                 │ Domain Events     │
+                 └───────────────────┘
+                           ▲
+                           │
+                 ┌─────────┴─────────┐
+                 │  Infrastructure   │
+                 │                   │
+                 │ Persistence       │
+                 │ External Systems  │
+                 │ Configuration     │
+                 └───────────────────┘
+```
+
+---
+
+# 35. Feature Generation Rules
+
+When implementing a feature from a specification, the generator MUST determine which architectural artifacts are required.
+
+For a generic use case:
+
+```text
+<Feature>
+```
+
+the generator MAY create:
+
+```text
+adapter/in/controller/
+└── <Feature>Controller.java
+
+application/dto/request/
+└── <Feature>RequestDto.java
+
+application/dto/response/
+└── <Feature>ResponseDto.java
+
+application/port/in/
+└── <Feature>UseCase.java
+
+application/port/out/
+└── <RequiredDependency>Port.java
+
+application/service/
+└── <Feature>UseCaseImpl.java
+
+domain/entity/
+└── <RequiredDomainEntity>.java
+
+domain/valueObjects/
+└── <RequiredValueObject>.java
+
+infrastructure/persistence/
+├── <RequiredEntity>JpaEntity.java
+├── Jpa<RequiredEntity>Repository.java
+├── <RequiredEntity>RepositoryImpl.java
+└── mapper/
+    └── <RequiredEntity>Mapper.java
+```
+
+The generator MUST NOT create every possible artifact automatically.
+
+Artifacts MUST be generated based on the requirements and design.
+
+---
+
+# 36. No Empty Architectural Packages
+
+The generator SHOULD NOT create unnecessary empty packages.
+
+For example, if a project does not require messaging:
+
+```text
+adapter/in/messaging/
+```
+
+SHOULD NOT be created.
+
+If a project does not require JPA:
+
+```text
+infrastructure/persistence/
+```
+
+SHOULD NOT be created.
+
+The architecture defines available extension points, not mandatory empty directories.
+
+---
+
+# 37. Naming Rules
+
+Generated Java types MUST follow standard Java naming conventions.
+
+Examples:
+
+```text
+<ClassName>.java
+<Feature>Controller.java
+<Feature>UseCase.java
+<Feature>UseCaseImpl.java
+<Entity>JpaEntity.java
+<Entity>Repository.java
+<Entity>RepositoryImpl.java
+<Entity>Mapper.java
+```
+
+Class names MUST be derived from the project specification.
+
+Domain-specific names MUST NOT be hard-coded in this architecture document.
+
+---
+
+# 38. Domain Independence
+
+The domain MUST NOT require Spring Boot to execute its core business behavior.
+
+The preferred dependency model is:
+
+```text
+Domain
+  ↓
+Java / Standard Library
+```
+
+rather than:
+
+```text
+Domain
+  ↓
+Spring Boot
+  ↓
+Hibernate
+  ↓
+Database
+```
+
+Framework dependencies MAY be introduced into the domain only when explicitly justified by the project architecture and constitution.
+
+---
+
+# 39. Infrastructure Independence from Application Details
+
+Infrastructure implementations MUST depend on application-defined contracts wherever an external dependency is required.
+
+Preferred:
+
+```text
+Application Port
+       ▲
+       │ implements
+       │
+Infrastructure Adapter
+```
+
+Not:
+
+```text
+Application Service
+       ↓
+Concrete Infrastructure Class
+```
+
+This allows infrastructure implementations to be replaced without changing application use cases.
+
+---
+
+# 40. Architecture Extension Rules
+
+The standard structure MAY be extended when a project requires additional technical capabilities.
+
+Examples:
+
+```text
+infrastructure/
+├── security/
+├── messaging/
+├── external/
+└── storage/
+```
+
+or:
+
+```text
+adapter/
+├── in/
+│   ├── controller/
+│   ├── messaging/
+│   └── scheduler/
+│
+└── out/
+    ├── messaging/
+    └── external/
+```
+
+Extensions MUST:
+
+1. Have a clear architectural responsibility.
+2. Preserve dependency direction.
+3. Not bypass application ports.
+4. Not introduce infrastructure dependencies into the domain.
+5. Be documented when they introduce a new architectural boundary.
+
+---
+
+# 41. Project-Specific Architecture Overrides
+
+This document defines the **default Java architecture**.
+
+A project MAY define additional architectural requirements.
+
+Project-specific requirements MUST NOT silently violate the baseline architecture.
+
+If an override is required, it SHOULD explicitly document:
+
+```text
+Override:
+Reason:
+Affected Layer:
+New Dependency:
+Architectural Impact:
+```
+
+The project specification takes precedence for legitimate project-specific requirements while preserving the core architectural principles.
+
+---
+
+# 42. Generation Decision Rules
+
+The AW-Spec implementation process SHOULD use the following decision process.
+
+```text
+Requirement
+    │
+    ▼
+Does it represent a business concept?
+    │
+    ├── Yes → Domain
+    │
+    └── No
+         │
+         ▼
+Does it represent a use case?
+         │
+         ├── Yes → Application
+         │
+         └── No
+              │
+              ▼
+Does it expose the application externally?
+              │
+              ├── Yes → Inbound Adapter
+              │
+              └── No
+                   │
+                   ▼
+Does it communicate with an external system?
+                   │
+                   ├── Yes → Outbound Port + Adapter
+                   │
+                   └── No
+                        │
+                        ▼
+Does it implement a technical mechanism?
+                        │
+                        └── Yes → Infrastructure
+```
+
+---
+
+# 43. Standard Artifact Mapping
+
+| Requirement Artifact          | Default Location                                     |
+| ----------------------------- | ---------------------------------------------------- |
+| REST Controller               | `adapter/in/controller`                              |
+| Messaging Consumer            | `adapter/in/messaging`                               |
+| Scheduler Entry Point         | `adapter/in/scheduler`                               |
+| External API Adapter          | `adapter/out/external`                               |
+| Request DTO                   | `application/dto/request`                            |
+| Response DTO                  | `application/dto/response`                           |
+| Inbound Use Case              | `application/port/in`                                |
+| Outbound Port                 | `application/port/out`                               |
+| Use Case Implementation       | `application/service`                                |
+| Domain Entity                 | `domain/entity`                                      |
+| Value Object                  | `domain/valueObjects`                                |
+| Domain Enum                   | `domain/enums`                                       |
+| Domain Exception              | `domain/exception`                                   |
+| Domain Service                | `domain/service`                                     |
+| Domain Event                  | `domain/event`                                       |
+| JPA Entity                    | `infrastructure/persistence`                         |
+| Spring Data Repository        | `infrastructure/persistence`                         |
+| Repository Implementation     | `infrastructure/persistence`                         |
+| Persistence Mapper            | `infrastructure/persistence/mapper`                  |
+| Security Configuration        | `infrastructure/config` or `infrastructure/security` |
+| Database Configuration        | `infrastructure/config`                              |
+| External Client Configuration | `infrastructure/config`                              |
+| Application Bootstrap         | `<base-package>/Application.java`                    |
+
+---
+
+# 44. Reusability Requirement
+
+This document MUST remain domain-neutral.
+
+It MUST NOT contain:
+
+* Specific business entities
+* Specific business terminology
+* Specific API endpoints
+* Specific database tables
+* Specific use cases
+* Specific customer requirements
+* Specific domain validations
+* Specific project names
+
+The following are examples of information that belong elsewhere:
+
+```text
+Flight
+Booking
+Library
+Book
+Employee
+Project
+Patient
+Account
+Order
+Payment
+```
+
+Those concepts MUST come from the project's domain specification.
+
+---
+
+# 45. Relationship With AW-Spec
+
+This document acts as the **Java architecture/folder-structure baseline** for AW-Spec.
+
+The intended relationship is:
+
+```text
+Java Architecture Standard
+        │
+        ▼
+Project Foundation
+        │
+        ▼
+Project Constitution
+        │
+        ▼
+Domain Requirements
+        │
+        ▼
+Application Design
+        │
+        ▼
+Implementation
+```
+
+The architecture standard determines:
+
+* Where generated code belongs.
+* Which layers exist.
+* Which dependencies are allowed.
+* Which technical concerns belong to infrastructure.
+* How application ports and adapters are organized.
+
+The project specification determines:
+
+* What the application does.
+* Which domain entities exist.
+* Which use cases exist.
+* Which APIs exist.
+* Which external systems are required.
+* Which persistence mechanisms are required.
+
+---
+
+# 46. Core Principle
+
+The generator MUST follow this principle:
+
+> **Architecture defines the structure; specifications define the behavior.**
+
+Therefore:
+
+```text
+Architecture MD
+    ↓
+Where does code belong?
+
+Project Specification
+    ↓
+What code is required?
+
+Design
+    ↓
+How should the behavior be implemented?
+
+Implementation
+    ↓
+Generate the code
+```
+
+The architecture document MUST provide the reusable structural contract without embedding business-specific implementation details.
+
+---
+
+# 47. Final Standard Structure
+
+The canonical Java project structure is therefore:
+
+```text
+<project-root>/
+│
+├── src/
+│   ├── main/
+│   │   ├── java/
+│   │   │   └── <base-package>/
+│   │   │       │
+│   │   │       ├── adapter/
+│   │   │       │   ├── in/
+│   │   │       │   └── out/
+│   │   │       │
+│   │   │       ├── application/
+│   │   │       │   ├── dto/
+│   │   │       │   │   ├── request/
+│   │   │       │   │   └── response/
+│   │   │       │   ├── port/
+│   │   │       │   │   ├── in/
+│   │   │       │   │   └── out/
+│   │   │       │   └── service/
+│   │   │       │
+│   │   │       ├── domain/
+│   │   │       │   ├── entity/
+│   │   │       │   ├── valueObjects/
+│   │   │       │   ├── enums/
+│   │   │       │   ├── exception/
+│   │   │       │   ├── service/       # optional
+│   │   │       │   └── event/         # optional
+│   │   │       │
+│   │   │       ├── infrastructure/
+│   │   │       │   ├── config/
+│   │   │       │   ├── persistence/   # optional
+│   │   │       │   ├── security/      # optional
+│   │   │       │   ├── messaging/     # optional
+│   │   │       │   └── external/      # optional
+│   │   │       │
+│   │   │       └── Application.java
+│   │   │
+│   │   └── resources/
+│   │
+│   └── test/
+│       └── java/
+│           └── <base-package>/
+│
+├── pom.xml / build.gradle / build.gradle.kts
+└── README.md
+```
+
+This structure is the **reusable Java Hexagonal Architecture baseline**.
+
+Every upcoming Java project SHOULD reuse this architecture unless its project constitution explicitly defines a different architectural strategy.