aw-spec-cli 0.1.10 → 0.1.11

package/assets/guardrails/technology/java-spring/global_exception_handler.md

@@ -0,0 +1,247 @@
+# Global Exception Handler Component Architectural Specification (Rule)
+
+## 1. Purpose
+
+The Global Exception Handler is a centralized mechanism for handling exceptions that reach the HTTP/framework exception-handling boundary. Its primary flow is:
+
+Exception → Global Exception Handler → Problem Details → HTTP Error Response
+
+The component MUST separate exception interception and handling from standardized HTTP error representation.
+
+## 2. Applicability
+
+This cross-cutting concern applies to centralized handling of exceptions that reach the HTTP/framework exception-handling boundary in a Java/Spring application. It does not apply to exceptions that are intentionally handled locally when local recovery is required.
+
+## 3. Component Responsibilities
+
+The component MUST:
+
+- Centrally intercept exceptions that reach the HTTP/framework exception-handling boundary.
+- Identify the exception type/category.
+- Determine the appropriate handling path for supported exception categories.
+- Handle known exception categories according to the established application exception model.
+- Provide a safe fallback path for unexpected exceptions.
+- Delegate standardized HTTP error representation to the Problem Details component.
+- Prevent common exception-handling logic from being duplicated across controllers/endpoints.
+- Support appropriate diagnostic handling without exposing sensitive internal information.
+
+The component MUST NOT:
+
+- Implement business rules.
+- Generate business exceptions.
+- Perform validation.
+- Implement Result Mapping.
+- Construct its own Problem Details representation.
+- Implement logging infrastructure.
+- Implement metrics.
+- Implement distributed tracing.
+- Make authentication or authorization decisions.
+
+## 4. Exception Categories
+
+The rule MUST support the established application exception model. Exception categories may include established categories such as:
+
+- Domain exceptions
+- Application exceptions
+- Infrastructure exceptions
+- Validation exceptions
+- Not-found exceptions
+- Conflict exceptions
+- Unauthorized exceptions
+
+The Global Exception Handler MUST determine handling behavior from the established exception semantics.
+
+The component MUST NOT invent additional exception categories.
+
+The rule MUST NOT require a separate handler implementation for every exception class when multiple exception types can legitimately share a handling strategy.
+
+## 5. Problem Details Integration
+
+Problem Details is a separate cross-cutting concern.
+
+The responsibility boundary MUST remain:
+
+- Global Exception Handler: Exception interception, exception classification/handling path, and providing the exception/error context required by the Problem Details capability.
+- Problem Details: Standardized HTTP error representation.
+
+The Global Exception Handler MUST delegate standardized HTTP error representation to the approved Problem Details capability.
+
+It MUST NOT:
+
+- Construct Problem Details itself.
+- Duplicate Problem Details fields.
+- Define another HTTP error-response schema.
+- Create a second standardized error representation.
+- Bypass Problem Details for exceptions handled by the global flow.
+
+## 6. Unexpected Exceptions and Security
+
+The component MUST provide a safe fallback for unexpected exceptions.
+
+Unexpected exceptions MUST:
+
+- Be handled centrally.
+- Follow the Problem Details error-response flow.
+- Avoid exposing internal implementation details to clients.
+- Avoid exposing stack traces to clients in production by default.
+- Avoid exposing credentials, tokens, secrets, database details, or other sensitive internal information.
+- Provide sufficient diagnostic information for internal investigation through the approved Logging capability.
+
+The rule MUST clearly distinguish internal diagnostic information from client-facing error information. The exact standardized HTTP error representation remains the responsibility of Problem Details.
+
+## 7. Separation from Result Mapping
+
+Result Mapping is a separate cross-cutting concern responsible for Application Result → HTTP Response.
+
+The Global Exception Handler is responsible for Exception reaching HTTP/framework boundary → Error-handling flow.
+
+The Global Exception Handler MUST NOT:
+
+- Replace Result Mapping.
+- Duplicate Result Mapping logic.
+- Determine application Result success/failure.
+- Become a Result Mapper.
+- Introduce an Exception → Result → Result Mapping flow unless such a flow is explicitly required by the established application architecture.
+- Convert arbitrary exceptions into successful HTTP responses.
+
+## 8. Validation Integration
+
+Validation is a separate cross-cutting concern.
+
+The Global Exception Handler MUST NOT perform validation rules.
+
+It MAY handle validation exceptions/errors produced by the Validation capability and route them through Problem Details.
+
+The responsibility boundary MUST remain:
+
+- Validation: Validate input/data → Validation error
+- Global Exception Handler: Handle validation error → Problem Details
+- Problem Details: Standardized HTTP error representation
+
+## 9. Logging Integration
+
+Logging is a separate cross-cutting concern.
+
+The Global Exception Handler MAY integrate with the approved Logging capability for diagnostic information.
+
+It MUST NOT:
+
+- Implement logging infrastructure.
+- Create a custom logger.
+- Create a custom logging abstraction.
+- Configure the logging framework.
+- Duplicate Logging responsibilities.
+
+Diagnostic logging SHOULD be performed at an appropriate centralized boundary to avoid redundant multi-layer logging. Sensitive exception information MUST follow the Logging component's sensitive-data protection policy.
+
+## 10. Architectural Layer Placement
+
+The Global Exception Handler is a Technical/Infrastructure HTTP cross-cutting concern. Its implementation, configuration, and framework integration MUST belong to the Infrastructure boundary.
+
+The Domain layer MUST remain independent of the Global Exception Handler and HTTP exception-handling infrastructure.
+
+## 11. Hexagonal Architecture
+
+### Domain/Core
+
+The Domain MUST NOT depend on the Global Exception Handler, HTTP response types, Spring Web, Servlet APIs, Problem Details, or framework-specific exception-handling mechanisms. Domain exceptions MAY exist as part of the Domain's business error model, but the Domain MUST NOT know how its exceptions are converted into HTTP responses.
+
+### Inbound Ports
+
+Inbound Ports MUST NOT depend on the Global Exception Handler, HTTP response types, Problem Details, or framework-specific exception handling.
+
+### Outbound Ports
+
+Outbound Ports MUST NOT depend on the Global Exception Handler, HTTP response types, or framework-specific exception handling.
+
+### Application
+
+The Application layer MAY produce application exceptions. It MUST NOT construct framework-specific HTTP error responses.
+
+### Inbound Adapters / Presentation
+
+Inbound Adapters / Presentation MAY participate in the framework's exception-handling mechanism. Controllers/endpoints SHOULD NOT duplicate common exception-handling logic that is already handled globally.
+
+### Infrastructure
+
+Infrastructure provides and configures the Global Exception Handler and its framework integration.
+
+## 12. Centralization and Local Overrides
+
+Exception handling MUST be centralized for common exception categories. Controllers/endpoints MUST NOT duplicate common handling logic for exception categories supported by the Global Exception Handler.
+
+Local exception handling MAY still be used when an operation requires specific recovery behavior that cannot reasonably be handled by the global mechanism. The Global Exception Handler MUST NOT prevent legitimate local exception recovery.
+
+## 13. Configuration
+
+The component MUST provide externalized configuration where environment-specific behavior is required.
+
+Configuration MAY control environment-specific error disclosure behavior.
+
+Stack traces MUST NOT be exposed to clients in production by default.
+
+Internal diagnostic details MAY be available to the appropriate diagnostic/logging mechanism.
+
+Whether development environments expose additional diagnostic details is an implementation/configuration decision.
+
+Production configuration MUST prioritize safe error disclosure. Environment-specific behavior MUST NOT require source-code changes. The component MUST NOT introduce configuration for unrelated concerns.
+
+## 14. Dependencies
+
+Dependencies MUST be limited to those required for Java/Spring exception-handling integration, the established application exception model, integration with the approved Problem Details capability, and integration with the approved Logging capability where diagnostic logging is required.
+
+Dependencies MUST be managed through centralized dependency management or an approved BOM where applicable. Unnecessary dependencies MUST NOT be introduced. Dependency versions MUST NOT be hardcoded in the rule.
+
+## 15. Reliability and Performance
+
+Exception handling MUST NOT alter business rules, domain state, or business outcomes.
+
+The configuration SHOULD avoid expensive processing during error handling, unbounded error payloads, recursive exception handling, excessive diagnostic information, and unnecessary duplicate logging.
+
+If the exception-handling mechanism itself encounters an unexpected failure, it MUST have a safe fallback that does not expose sensitive internal information.
+
+## 16. Separation from Other Cross-Cutting Concerns
+
+The Global Exception Handler MUST NOT implement or assume responsibility for Problem Details construction, Result Mapping, Validation, Logging infrastructure, Metrics, Distributed tracing, Authentication, Authorization, Business audit logging, APM, or Business rules.
+
+It MAY integrate with these capabilities where required, but responsibility MUST remain separated.
+
+## 17. Prohibited Behavior
+
+- The component MUST NOT construct its own Problem Details representation.
+- The component MUST NOT create a custom HTTP error-response schema.
+- The component MUST NOT duplicate Result Mapping logic.
+- The component MUST NOT perform validation.
+- The component MUST NOT implement logging infrastructure.
+- The component MUST NOT implement distributed tracing.
+- The component MUST NOT implement metrics.
+- The component MUST NOT expose stack traces to clients in production by default.
+- The component MUST NOT expose secrets or unsafe internal exception details.
+- The component MUST NOT move HTTP-specific exception handling into the Domain.
+- The component MUST NOT generate business exceptions.
+- The component MUST NOT unnecessarily duplicate controller-level exception handling.
+
+## 18. Implementation Boundary
+
+The rule defines architectural behavior and constraints. The component MUST NOT dictate implementation details unless strictly required by the architectural standard.
+
+The following remain implementation details: exact Java class names, exact package structures, exact Spring annotations, exact configuration class names, exact exception-handler method signatures, exact Problem Details implementation, exact Logging implementation, and exact dependency versions.
+
+The Java/Spring implementation MUST provide the behavior defined by this rule using appropriate framework mechanisms.
+
+## 19. Acceptance Criteria
+
+- [ ] Exceptions that reach the HTTP/framework exception-handling boundary are centrally intercepted.
+- [ ] Known exception categories are handled according to the established application exception model.
+- [ ] Unexpected exceptions have a safe fallback handling path.
+- [ ] Exceptions handled by the Global Exception Handler use the approved Problem Details capability for standardized HTTP error representation.
+- [ ] The Global Exception Handler does not construct or duplicate Problem Details.
+- [ ] Validation is not implemented inside the Global Exception Handler.
+- [ ] Result Mapping responsibilities are not duplicated.
+- [ ] Logging infrastructure is not implemented inside the Global Exception Handler.
+- [ ] Sensitive internal exception information is not exposed to clients.
+- [ ] Stack traces are not exposed to clients in production by default.
+- [ ] The Domain layer and Ports remain independent of HTTP exception handling.
+- [ ] Controllers do not need to duplicate common global exception handling logic.
+- [ ] The Global Exception Handler is integrated through the standard Java/Spring framework mechanism.
+- [ ] Environment-specific error disclosure behavior can be externally configured where required.

package/assets/guardrails/technology/java-spring/logging.md

@@ -0,0 +1,215 @@
+# Logging Component Architectural Specification (Rule)
+
+## 1. Purpose
+
+The purpose of the Logging component is to standardize logging behavior and configuration across the Java/Spring application. It provides a stable, technology-neutral Logging Contract to enable Logging Provider pluggability while leveraging the mature Java logging ecosystem (defaulting to SLF4J as the Logging API / Facade) for structured, context-aware, and secure diagnostic telemetry.
+
+## 2. Applicability
+
+This rule applies when the Logging cross-cutting concern is developed as a reusable capability for the application.
+
+## 3. Component Responsibilities
+
+The component is responsible for providing:
+
+- **Contract/Abstraction:** A stable, technology-neutral Logging Contract to support Logging Provider pluggability without exposing underlying technology-specific types.
+
+- **Configuration:** Standardized configuration for the selected Logging Backend / Implementation to provide structured logging and standardized log levels.
+
+- **Framework Integration:** Integration with existing request, correlation, and tracing context so that available Trace ID, Span ID, and Correlation ID values can be included in the logging context.
+
+- **Security Integrations:** Configurable masking/redaction mechanisms applied before sensitive information is emitted to the Logging Backend / Implementation.
+
+- **Delegation:** The component MUST provide the stable Logging Contract and the provider integration mechanism required to select and configure an approved Logging Provider. SLF4J (Logging API / Facade) with an approved SLF4J-compatible implementation (Logging Backend / Implementation) MUST be the default configuration. The selected Logging Provider MUST be determined through the project's approved provider-selection and dependency-management mechanism. Runtime logging behavior MUST be configurable without requiring changes to application business logic.
+
+## 4. Required Functionality
+
+### 4.1 Structured Logging
+
+The component MUST configure the application to emit logs in a machine-readable structured format (e.g., JSON).
+
+### 4.2 Standard Log Levels
+
+The component MUST support and correctly configure the following standard levels: TRACE, DEBUG, INFO, WARN, and ERROR.
+
+Semantic usage guidance:
+
+- ERROR: failures requiring attention
+- WARN: abnormal but recoverable conditions
+- INFO: significant application events
+- DEBUG: diagnostic information
+- TRACE: highly detailed diagnostic information
+
+### 4.3 Standard Log Schema
+
+The component MUST define a standardized structured log schema. At a minimum, the schema MUST support the following fields where applicable:
+
+- timestamp
+- level
+- logger/source
+- message
+- application/service
+- environment
+- traceId, when available
+- spanId, when available
+- correlationId, when available
+- exception information, when applicable
+
+The component MUST NOT invent unnecessary mandatory fields.
+
+### 4.4 Contextual Logging
+
+Context propagation across execution boundaries such as HTTP, messaging, asynchronous execution, scheduled execution, or batch execution belongs to the appropriate context-propagation or tracing mechanism.
+
+The Logging component only consumes available context and includes it in log records. It MUST NOT implement distributed tracing.
+
+### 4.5 Exception Logging
+
+The component MUST support exception logging with stack traces, diagnostic context, and sensitive-data protection. Application code SHOULD avoid redundant logging of the same failure across multiple layers unless additional logging provides materially different diagnostic information.
+
+### 4.6 Timestamp and Timezone
+
+Log timestamps MUST use a consistent machine-readable representation. UTC SHOULD be used as the default timezone unless another organizational standard is explicitly defined.
+
+## 5. Dependencies
+
+### 5.1 Dependency Management
+
+Logging dependencies MUST be managed through centralized dependency management or an approved BOM. The component MUST NOT independently introduce conflicting versions of shared logging dependencies.
+
+### 5.2 Selected Provider Dependencies
+
+- The component MUST declare or provide the dependencies required by the selected Logging Provider, including its required Logging API / Facade and Logging Backend / Implementation, subject to the application's centralized dependency-management policy.
+- Alternative Logging Provider dependencies are included only when that Logging Provider is explicitly selected and approved.
+
+### 5.3 Conditional Dependencies
+
+The component MAY conditionally rely on:
+
+- **Structured logging encoder/support** when not provided natively
+- **Tracing/context integration** when tracing is enabled
+- **Payload interception dependencies** when Payload Logging is enabled
+- **AOP/interception dependencies** when Execution-Time Logging is enabled
+
+## 6. Configuration Requirements
+
+The component MUST provide externalized configuration mechanisms. Environments (Development, Test, Production) MUST be able to define different log levels and configurations without requiring application source-code changes.
+
+The default logging destination MUST be standard output. Destinations MAY be overridden through externalized configuration where permitted by the deployment/environment standard.
+
+## 7. Architectural Layer Placement
+
+The Logging Provider, Logging API / Facade integration, Logging Backend / Implementation, and logging configuration belong strictly to the Infrastructure boundary.
+
+The stable Logging Contract MUST be located at a dependency boundary that can be consumed by Application-facing code without creating a dependency on Infrastructure.
+
+It MUST NOT be part of the Domain model or business ports.
+
+It MUST NOT create a dependency from the Application layer into the Infrastructure layer.
+
+The Application, Presentation, Inbound Adapter, and Outbound Adapter layers MAY consume the stable, technology-neutral Logging Contract.
+
+## 8. Domain Dependency Restrictions
+
+Logging is a Technical/Infrastructure cross-cutting concern.
+
+The Domain layer MUST remain strictly independent of the Logging component, the Logging Contract, SLF4J, Logback, Spring logging infrastructure, another Logging API / Facade, or any concrete Logging Backend / Implementation.
+
+## 9. Hexagonal Architecture Position
+
+- Domain/Core MUST NOT depend on Logging, the Logging Contract, SLF4J, or concrete Logging Backend / Implementations.
+- Inbound Ports MUST remain technology-independent and MUST NOT depend on Logging infrastructure.
+- Outbound Ports MUST remain technology-independent and MUST NOT depend on Logging infrastructure.
+- Application Services MAY consume the technology-neutral Logging Contract.
+- Inbound Adapters MAY consume the technology-neutral Logging Contract.
+- Outbound Adapters MAY consume the technology-neutral Logging Contract.
+- Presentation MAY consume the technology-neutral Logging Contract.
+- Infrastructure configures/provides the concrete Logging Provider and Logging Backend / Implementation.
+
+## 10. Optional Features
+
+Optional features MUST NOT become mandatory dependencies of the core Logging capability.
+
+### 10.1 Payload Logging
+
+A framework integration (e.g., HTTP filter) that logs request/response payloads.
+
+If implemented, it MUST be explicitly enabled, disabled by default in production, and comply with the same sensitive-data protection requirements.
+
+### 10.2 Execution-Time Logging
+
+A framework integration (e.g., Spring AOP aspect) for diagnostic method duration logging.
+
+If implemented, it MUST be explicitly enabled and MUST NOT replace metrics or APM.
+
+## 11. Security Requirements
+
+The component MUST provide configurable masking/redaction for known sensitive fields and configured sensitive patterns.
+
+Applications MUST NOT intentionally log passwords, credentials, authentication tokens, API keys, or secrets.
+
+Payload Logging MUST comply with the same sensitive-data protection requirements.
+
+The component does not guarantee that arbitrary secrets can always be automatically detected.
+
+## 12. Reliability and Performance Requirements
+
+Logging MUST remain observational and MUST NOT alter business rules, domain state, business outcomes, or transaction behavior.
+
+Logging failures MUST NOT normally cause business operations or transactions to fail, unless an explicitly approved critical compliance or security policy requires otherwise.
+
+The configuration SHOULD avoid unbounded payloads, excessive logging volume, unnecessary high-cardinality fields, and unnecessary application-thread blocking.
+
+## 13. Separation from Other Cross-Cutting Concerns
+
+The Logging component MUST NOT implement:
+
+- distributed tracing
+- metrics
+- business audit logging
+- alerting
+- centralized log aggregation infrastructure
+- APM
+
+## 14. Prohibited Behavior
+
+- A custom logging abstraction MUST NOT be created merely because Logging is a cross-cutting concern. However, because Logging Provider substitution is required, a stable technology-neutral Logging Contract MAY be provided so application code does not depend directly on the Logging Provider or Logging API / Facade.
+
+- The Logging Contract MUST remain technology-neutral and MUST NOT expose SLF4J-specific types, Logback-specific types, or any other Logging Provider-specific types.
+
+- The component MUST NOT call the Logging Contract `AppLogger`, `AppLoggerImpl`, or `IAppLogger`.
+
+- The component MUST NOT invent a Logging Contract unless it is actually necessary for the Logging Provider pluggability requirement.
+
+- The component MUST NOT implement a custom logging framework.
+
+## 15. Implementation Boundary
+
+The rule defines architectural behavior and constraints.
+
+The component MUST NOT dictate implementation details unless strictly required by the architectural standard.
+
+The following remain implementation details configurable by the component:
+
+- exact interface/class names for the Logging Contract
+- exact configuration file names (e.g., `logback.xml` vs `logback-spring.xml`)
+- specific JSON encoder libraries
+- specific masking libraries
+- specific AOP libraries
+- specific MDC key names
+- specific async logging implementations
+
+## 16. Acceptance Criteria
+
+- [ ] A stable technology-neutral Logging Contract is available to application-facing layers where Logging Provider pluggability requires it.
+- [ ] The stable Logging Contract does not expose types specific to SLF4J, Logback, or any other concrete Logging Provider.
+- [ ] Application business logic does not directly depend on SLF4J, Logback, or another concrete Logging API / Facade or Logging Backend / Implementation.
+- [ ] SLF4J is the default Logging API / Facade, and an approved SLF4J-compatible implementation is the default Logging Backend / Implementation.
+- [ ] An alternative approved Logging Provider can be selected through the supported provider-selection and dependency-management mechanism.
+- [ ] Switching the Logging Provider does not require changes to application business logic.
+- [ ] Structured logging remains standardized regardless of the selected Logging Provider.
+- [ ] Domain, Inbound Ports, and Outbound Ports remain independent of all logging technology and infrastructure.
+- [ ] Trace ID, Span ID, and Correlation ID are included when available.
+- [ ] Sensitive information is masked according to the configured policy.
+- [ ] Optional Payload Logging and Execution-Time Logging remain independently configurable.
+- [ ] Log levels and configuration remain externally configurable.

package/assets/guardrails/technology/java-spring/modular-monolith.md

@@ -0,0 +1,77 @@
+# Modular Monolith Strategy
+
+## Overview
+
+The backend is structured as a **modular monolith**: a single deployable Spring Boot application internally divided into independent, cohesive modules that map to DDD bounded contexts.
+
+---
+
+## Module Boundaries
+
+Each module is a self-contained package that:
+- Owns its own domain model, use cases, ports, and adapters
+- Has its own database tables (no shared tables across modules)
+- Exposes a well-defined public API surface (application service interfaces)
+- Does not allow other modules to directly call its repository or domain internals
+
+```text
+com.company.project
+  ├── module_a/          ← Example Module A
+  ├── module_b/          ← Example Module B
+  ├── module_c/          ← Example Module C
+  └── shared/            ← Shared kernel (value objects, utilities, base types)
+```
+
+---
+
+## Inter-Module Communication Rules
+
+| Rule | Detail |
+|------|--------|
+| Allowed | Module A calls Module B's **application service interface** (port) |
+| Allowed | Module A fires a **domain/application event** that Module B listens to |
+| Allowed | Modules share **value types** via the `shared` kernel |
+| **Forbidden** | Module A directly calls Module B's repository |
+| **Forbidden** | Module A accesses Module B's domain entities directly |
+| **Forbidden** | Cross-module JPA joins in queries |
+
+### Preferred Inter-Module Integration Patterns
+
+1. **Direct service call**: Module A injects Module B's port interface (defined in Module B's application layer). Used for synchronous query needs (e.g., Module A queries Module B for specific details).
+2. **Application events (Spring Events)**: Used for fire-and-forget side effects (e.g., Action completed in Module A → Module B listens and triggers a side-effect). Spring's `ApplicationEventPublisher` is sufficient for MVP1 (in-process, synchronous).
+3. **Read-only ID references**: When Module A only needs to reference an entity from Module B, it stores the foreign ID and calls Module B's service to fetch details as needed.
+
+---
+
+## Shared Kernel (`shared` package)
+
+The shared kernel contains only:
+- Common value objects (e.g., `Money`, `EmailAddress`, `UserId`, `TenantId`)
+- Common base types (e.g., `AuditableEntity`, `DomainEvent`)
+- Utility classes (e.g., pagination types, response wrappers)
+- Cross-cutting annotations or constants
+
+The shared kernel must not contain business logic belonging to any specific module.
+
+---
+
+## Database Table Ownership
+
+Each module owns and manages its own tables via its own Flyway migration scripts.
+
+| Module | Table Prefix (suggested) |
+|--------|--------------------------|
+| module_a | `moda_*` |
+| module_b | `modb_*` |
+| module_c | `modc_*` |
+| shared | `shared_*` (if applicable) |
+
+---
+
+## Future Microservice Extraction
+
+The modular monolith is designed so that a module can be extracted to a standalone service by:
+1. Externalising the module's in-process application event bus to a message broker (e.g., Kafka, RabbitMQ, or Service Bus).
+2. Replacing the module's direct service call ports with HTTP/gRPC adapters.
+3. Moving the module's tables to a separate database instance.
+