@eltonssouza/development-utility-kit 1.0.0

package/dashboard/public/content/docs/stack-rules.en.md

@@ -0,0 +1,362 @@
+# Stack Rules
+
+Stack rules are **mandatory** across all projects managed by the harness. They cover minimum versions, code conventions, package structure, security, observability, and anti-patterns.
+
+Changing a rule requires an ADR approved by `tech-lead`. There is no "in this project it is different" without an ADR.
+
+## Mandatory versions
+
+| Technology | Minimum version | Notes |
+|---|---|---|
+| Java | 25+ (LTS) or 26 | Modernize legacy automatically. Records, sealed types, pattern matching. |
+| Spring Boot | 4.0.x+ | SecurityFilterChain, RestClient, WebClient, ProblemDetail (RFC 9457) |
+| Angular | 21+ | Standalone, Signals, OnPush, lazy loading, Signal Forms |
+| React Native | 0.84+ (latest) | New Architecture, TypeScript strict |
+| Expo SDK | 54+ | EAS Build, Expo Router |
+| Spring AI | latest | ChatClient, Advisors, function calling |
+| PostgreSQL | 17+ | UUID v7, JSONB, generated columns |
+| Redis | 7+ | Cache, session, rate limiting |
+
+Versions below the minimum are treated as a mandatory migration. The `migrator` agent is responsible for Java 8/11/17 → 25, Spring Boot 2/3 → 4, Angular 14-20 → 21.
+
+## Java / Spring Boot 4 conventions
+
+### DTOs
+
+- **`record` for immutable DTOs**. Never mutable classes with getters/setters.
+- **Separate req/res DTOs**. `CreateProductRequest` and `ProductResponse` are distinct types.
+- **Never expose JPA entity directly** in a controller. Always map to a record.
+
+```java
+public record CreateProductRequest(
+    @NotBlank @Size(max = 120) String name,
+    @NotNull @PositiveOrZero BigDecimal price,
+    @NotNull @PositiveOrZero Integer stock
+) {}
+
+public record ProductResponse(
+    UUID id,
+    String name,
+    BigDecimal price,
+    Integer stock,
+    OffsetDateTime createdAt
+) {
+    public static ProductResponse fromEntity(Product p) {
+        return new ProductResponse(p.getId(), p.getName(), p.getPrice(), p.getStock(), p.getCreatedAt());
+    }
+}
+```
+
+### Validation
+
+- **Bean Validation** (`@Valid`, `@NotBlank`, `@Email`, `@Positive`, `@PositiveOrZero`, `@Size`).
+- Compound validation via `@AssertTrue` in a record method.
+- Validation errors → ProblemDetail RFC 9457.
+
+### Error handling
+
+- Domain exceptions in `domain/` (e.g. `ProductNotFoundException`).
+- Central `@ControllerAdvice` in `web/` maps exception → `ProblemDetail`.
+
+```java
+@ControllerAdvice
+public class GlobalExceptionHandler {
+
+    @ExceptionHandler(ProductNotFoundException.class)
+    ProblemDetail handleNotFound(ProductNotFoundException ex, HttpServletRequest req) {
+        var pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
+        pd.setTitle("Product not found");
+        pd.setProperty("path", req.getRequestURI());
+        pd.setProperty("traceId", MDC.get("traceId"));
+        return pd;
+    }
+}
+```
+
+### APIs
+
+- **Versioned** `/api/v1/<resource>`. Bump to v2 only with a real breaking change.
+- **Pagination** via `Pageable` + a `PagedResponse<T>` wrapper with metadata (total, page, size).
+- **Semantic HTTP**: 201 + Location on POST, 204 on DELETE, 200 on GET/PUT, 422 on semantic validation, 409 on conflict.
+
+### Idempotency
+
+Idempotent POSTs receive an `Idempotency-Key` header. The key is cached in Redis with TTL.
+
+### Imports and types
+
+- **Full imports** (`java.util.UUID`), never `*`.
+- **No `var`** in signature/return. In a method body, `var` is fine when the type is obvious.
+
+### Tests
+
+- **JUnit 5 + Mockito** for unit. Tests in `src/test/java`.
+- **Testcontainers** for integration. **NEVER H2** — H2 lies about Postgres-specific types.
+- Descriptive naming: `should_return201_when_validProduct()` or `givenValidProduct_whenCreate_thenReturns201()`.
+- Testcontainers for real Postgres:
+
+```java
+@SpringBootTest
+@Testcontainers
+class ProductIntegrationTest {
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:17");
+
+    @DynamicPropertySource
+    static void props(DynamicPropertyRegistry r) {
+        r.add("spring.datasource.url", postgres::getJdbcUrl);
+        r.add("spring.datasource.username", postgres::getUsername);
+        r.add("spring.datasource.password", postgres::getPassword);
+    }
+    // ...
+}
+```
+
+### Migrations
+
+- **Flyway** (or Liquibase). Versioned: `V20260527_001__create_product.sql`.
+- **Indexes in the same migration** that creates the table. Every FK has an index on the N side.
+- **Reversible** whenever possible (upgrade + downgrade when supported).
+
+### Observability
+
+- **Structured JSON logs** (Logback + Logstash encoder).
+- **Correlation ID** via MDC (`traceId`, `spanId` — OpenTelemetry W3C).
+- **Micrometer + Prometheus metrics** (p50/p95/p99, error rate, throughput).
+- **Actuator health** with `/actuator/health/readiness` and `/actuator/health/liveness`.
+- **OpenTelemetry tracing** (W3C Trace Context).
+
+### Forbidden anti-patterns
+
+- `// TODO` committed → goes to `docs/brain/tech-debt.md`.
+- Token/password/PII in log → `gate-keeper` blocks.
+- Exposing JPA entity in controller.
+- `var` in public signature.
+- H2 in integration test.
+
+## Angular 21 conventions
+
+### SEPARATE FILES — NON-NEGOTIABLE
+
+Every component, directive, or pipe with a template uses **3 physical files**:
+
+```
+product-form/
+├── product-form.ts      logic (signals, methods)
+├── product-form.html    template (via templateUrl)
+└── product-form.scss    styles (via styleUrl or styleUrls)
+```
+
+**NEVER** inline `template:` or `styles:` in the `.ts`. No size exception, no "small component" exception, no "presentation only" exception. Violation = hard block — `code-reviewer` and `tech-lead` refuse the merge.
+
+```typescript
+// CORRECT
+@Component({
+  selector: 'app-product-form',
+  templateUrl: './product-form.html',
+  styleUrl: './product-form.scss',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [/* ... */],
+})
+export class ProductFormComponent { /* ... */ }
+```
+
+```typescript
+// FORBIDDEN
+@Component({
+  selector: 'app-product-form',
+  template: `<form>...</form>`,                     // ❌ HARD BLOCK
+  styles: [`form { color: red; }`],                 // ❌ HARD BLOCK
+})
+```
+
+### Angular 21 patterns
+
+- **Standalone components** — no NgModules.
+- **OnPush change detection** always.
+- **Signals** for local state. RxJS only for HTTP/stream.
+- **Lazy loading** mandatory for features.
+- **Typed HttpClient** + interceptors for auth, error, correlation ID.
+- **Never `any`** — use `unknown` + narrowing when needed.
+- **Signal Forms** (Angular 21) preferred over Reactive Forms for new forms.
+
+### Style
+
+- **ng-bootstrap** as default UI library (modal, tooltip, datepicker, typeahead, etc.).
+- **Design tokens** for color, spacing, typography.
+- **WCAG 2.1 AA a11y** minimum. jest-axe in component tests.
+
+### Tests
+
+- **Jest + Testing Library** for component.
+- **jest-axe** for component a11y.
+- **Playwright + @axe-core/playwright** for E2E.
+
+```typescript
+import { render, screen } from '@testing-library/angular';
+import { axe } from 'jest-axe';
+
+describe('ProductFormComponent', () => {
+  it('has no a11y violations', async () => {
+    const { container } = await render(ProductFormComponent);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+```
+
+## Package structure — Backend (DDD)
+
+```
+com.company.project
+├── domain/          model, repository ports, domain services, domain exceptions
+├── application/     use cases, record req/res DTOs, mappers
+├── infrastructure/  JPA adapters, messaging, security config, external clients
+└── web/             controllers, filters, @ControllerAdvice
+```
+
+**Role of each layer**:
+
+- **`domain/`** — business core. Knows nothing about Spring, JPA, HTTP. Models are pure objects with rules. Repository = port (interface).
+- **`application/`** — use cases. Orchestrates the domain via ports. DTOs live here.
+- **`infrastructure/`** — adapters. Implements the domain's ports via JPA, Redis, Kafka, REST clients.
+- **`web/`** — HTTP entry. Thin controllers call use cases.
+
+The dependency only points inward: `web → application → domain` and `infrastructure → domain`. **`domain/` depends on nobody**.
+
+## Angular structure — Frontend
+
+```
+src/app/
+├── core/       auth, http interceptors, guards, error handling
+├── shared/     reusable components, pipes, directives
+├── features/   lazy-loaded feature modules
+└── app.routes.ts
+```
+
+**Role of each folder**:
+
+- **`core/`** — app singletons: AuthService, HttpInterceptor, ErrorHandler. Imported once in `app.config.ts`.
+- **`shared/`** — reusable UI pieces (custom buttons, pipes). Standalone, stateless.
+- **`features/`** — features. Each feature is lazy: `features/products/products.routes.ts`.
+
+## Security (always applied)
+
+- **OAuth2 / OpenID Connect** with **stateless JWT**.
+- **RBAC** with `@PreAuthorize` on service or controller methods.
+- **CORS per domain** (never `*` in prod).
+- **Rate limiting** via Bucket4j (in-app) or API Gateway.
+- **Mandatory headers**: CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy.
+- **Never log** token, password, PII.
+
+```java
+@Configuration
+@EnableWebSecurity
+public class SecurityConfig {
+    @Bean
+    SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+        return http
+            .csrf(csrf -> csrf.disable())
+            .sessionManagement(sm -> sm.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .authorizeHttpRequests(a -> a
+                .requestMatchers("/api/v1/auth/**").permitAll()
+                .anyRequest().authenticated())
+            .oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()))
+            .headers(h -> h
+                .contentSecurityPolicy(csp -> csp.policyDirectives("default-src 'self'"))
+                .httpStrictTransportSecurity(hsts -> hsts.maxAgeInSeconds(31536000)))
+            .build();
+    }
+}
+```
+
+## Observability (every system in production)
+
+- **Logs**: structured JSON (Logback + Logstash encoder), correlation ID via MDC.
+- **Metrics**: Micrometer + Prometheus (`/actuator/prometheus`).
+- **Tracing**: OpenTelemetry (W3C Trace Context).
+- **Health**: Spring Actuator (`/actuator/health/readiness`, `/actuator/health/liveness`).
+
+## Database
+
+- **PostgreSQL 17+** as default.
+- **UUID v7** as PK (natural temporal ordering).
+- **TIMESTAMPTZ** for every timestamp (never `TIMESTAMP` without tz).
+- **NUMERIC(precision, scale)** for money — never `FLOAT`/`DOUBLE`.
+- **Flyway migrations** versioned + indexes in the same migration.
+- **Every FK has an index on the N side**.
+- **Partial indexes** when applicable (`WHERE deleted_at IS NULL`).
+- **Redis 7+** for distributed cache, session, rate limiting.
+- **MongoDB** only when flexible schema is a real requirement (rare).
+
+## Frontend — UI Components
+
+- **ng-bootstrap** = default library.
+- Ready components: modal, tooltip, datepicker, typeahead, pagination, accordion, tabs, alerts, toasts.
+- **WCAG 2.1 AA a11y** minimum. ARIA roles and labels on interactive elements.
+- **Design tokens** for color, spacing, typography. No hardcoded color in SCSS.
+
+## Infrastructure
+
+- **Docker**: multi-stage build, non-root user, HEALTHCHECK in the Dockerfile.
+
+```dockerfile
+FROM eclipse-temurin:25-jdk AS build
+WORKDIR /app
+COPY . .
+RUN ./mvnw -B package -DskipTests
+
+FROM eclipse-temurin:25-jre
+RUN useradd -r -u 1001 appuser
+USER appuser
+WORKDIR /app
+COPY --from=build /app/target/*.jar app.jar
+HEALTHCHECK --interval=30s --timeout=3s CMD curl -fsS http://localhost:8080/actuator/health/liveness || exit 1
+ENTRYPOINT ["java", "-jar", "app.jar"]
+```
+
+- **Compose**: full dev stack (app + Postgres + Redis + Mailhog + Prometheus + Grafana).
+- **CI/CD**: GitHub Actions or GitLab CI (build → test → scan → deploy).
+- **Secrets**: never in code — vault, env var, CI secret.
+
+## Credentials
+
+To access service VPS, N8N VPS, or API Keys, **always read from**:
+
+```
+C:\development\tools\credentials\vps.txt
+```
+
+Never ask the human if the file exists. Never commit the contents. Never log the value read.
+
+## Common anti-patterns (blocked in review)
+
+| Anti-pattern | Why blocked | Correct |
+|---|---|---|
+| Exposing JPA entity in controller | Leaks DB schema to client, hard to evolve | Map to record DTO |
+| `var` in method signature | Hurts API readability | Explicit type |
+| `// TODO` committed | Untraceable | Entry in `docs/brain/tech-debt.md` |
+| Secret in code | Credential leak | Env var or vault |
+| Inline Angular template | Violates file separation | 3 physical files |
+| H2 in integration test | Lies about Postgres behavior | Real Postgres via Testcontainers |
+| CORS `*` in prod | CSRF/XSS vulnerability | Explicit allowlist |
+| `any` in TypeScript | Loses compiler guarantee | `unknown` + narrowing |
+| Table without index on FK | Performance degrades under load | Index in the same migration |
+| `FLOAT` for money | Floating-point imprecision | `NUMERIC(15, 2)` |
+| Skipping a11y test | Violates WCAG 2.1 AA | jest-axe mandatory |
+
+## General principles
+
+- **Clean Code + SOLID** applied through the code, without naming names.
+- **No premature abstraction**. Create an interface when there is a second real consumer.
+- **Every external call with explicit error handling** (timeout, retry, circuit breaker via Resilience4j).
+- **Never suggest a technology without justification**. Simplest solution = best.
+- **Never log token, password, PII**.
+
+## Cross-references
+
+- [Agents reference](agents-reference) — agents that enforce these rules (`backend-developer`, `frontend-developer`, `code-reviewer`, `tech-lead`)
+- [Quality gate](quality-gate) — thresholds that validate adherence to the rules
+- [Pipeline](pipeline) — where each rule is enforced in the flow
+- [Architecture overview](architecture-overview) — macro model
+- [Git Flow](git-flow) — branch and commit convention