Skip to content

3.2 Starters

Sprint: Sprint 03 - Platform Starters and Event Contracts
Feature ID: 3.2
Subtasks: 3.2.1, 3.2.2, 3.2.3, 3.2.4, 3.2.5, 3.2.6, 3.2.7

Objective

Deliver "Starters" within Sprint 03 - Platform Starters and Event Contracts.

Dependencies

Aggregated from the subtasks below (prerequisite task IDs and enablers):

  • 2.1.1
  • 2.1.2
  • 2.1.3
  • 2.3.2
  • 2.3.3
  • 2.4.1
  • 2.5.1
  • 3.2.2
  • 3.2.6

Subtasks

3.2.1 starter-api

  • ID: 3.2.1
  • Title: Implement GlobalExceptionHandler and ApiResult wiring
  • Description: @RestControllerAdvice GlobalExceptionHandler mapping each PlatformException subtype to its HTTP status and ApiResult.failure(...), populating ApiMeta from CorrelationContextHolder and the request path; map MethodArgumentNotValidException/ ConstraintViolationException to 400; fall back to 500 INTERNAL_ERROR without leaking stack traces. Conditional on web; property telco.platform.api.enabled (default true).
  • Business Purpose: Uniform RFC-7807-aligned error responses everywhere (NFR-14, ADR-015).
  • Inputs: PLATFORM-SPEC Section 9.1.
  • Outputs: starter-api autoconfig + handler.
  • Acceptance Criteria:
  • ResourceNotFoundException -> 404 with ApiResult.failure and a populated ApiMeta.
  • A bean-validation failure -> 400; an unmapped exception -> 500 with no stack trace in the body.
  • Dependencies: 2.1.1, 2.1.2, 2.1.3
  • Complexity: M

3.2.2 starter-mediator

  • ID: 3.2.2
  • Title: Implement MediatorAutoConfiguration and Spring HandlerRegistry
  • Description: MediatorAutoConfiguration providing a Spring HandlerRegistry (resolving CommandHandler/QueryHandler/EventHandler beans), the Mediator bean (InProcessMediator), and behavior beans: Performance/Logging/Authorization always-on; Validation @ConditionalOnBean(Validator.class); Transaction @ConditionalOnBean(PlatformTransactionManager) with a SpringTransactionRunner. Order config AFTER Hibernate/DataSource/Transaction/Validation autoconfig. Default CurrentUserProvider @ConditionalOnMissingBean. Props telco.platform.mediator.* (e.g. performance.slow-threshold-ms default 500).
  • Business Purpose: Turn the pure mediator into a wired Spring dispatch pipeline.
  • Inputs: PLATFORM-SPEC Section 9.2.
  • Outputs: starter-mediator autoconfig.
  • Acceptance Criteria:
  • Context test: a registered CommandHandler bean is invoked via Mediator.send; behaviors run in pipeline order; Transaction behavior present only when a transaction manager exists.
  • Dependencies: 2.3.2, 2.3.3
  • Complexity: L

3.2.3 starter-security

  • ID: 3.2.3
  • Title: Implement JWT/gateway-trust security autoconfiguration
  • Description: JwtProperties (telco.platform.security.jwt.*); JwtService (validate + parse claims, optional issue helper); JwtAuthFilter (OncePerRequestFilter): when telco.platform.security.gateway-trust.enabled, trust X-User-Id/X-User-Roles; otherwise validate the Bearer JWT. Populate UserContextHolder and Spring SecurityContext; provide a CurrentUserProvider bean (overrides mediator default). SecurityAutoConfiguration conditional on telco.platform.security.enabled and security/web classes.
  • Business Purpose: Gateway-behind-trust authentication and identity propagation (NFR-05, FR-IAM-03).
  • Inputs: PLATFORM-SPEC Section 9.3, ADR-011.
  • Outputs: starter-security autoconfig + filter + JwtService.
  • Acceptance Criteria:
  • With gateway-trust on, a request carrying X-User-Id/X-User-Roles populates UserContext.
  • With gateway-trust off, a valid Bearer JWT authenticates and an invalid one is rejected.
  • Dependencies: 2.1.3
  • Complexity: L

3.2.4 starter-outbox

  • ID: 3.2.4
  • Title: Implement JDBC outbox store, serializer, and migration
  • Description: JdbcOutboxStore (spring-jdbc), JacksonEventSerializer, OutboxAutoConfiguration wiring DefaultOutboxService. Flyway migration under db/migration/platform/ (V900+) creating a Debezium-friendly outbox table (id uuid, aggregate_type, aggregate_id, event_type, payload jsonb, headers jsonb, trace_id, correlation_id, created_at timestamptz, status) indexed on (status, created_at). Optional disabled relay scheduler. Props telco.platform.outbox.*.
  • Business Purpose: Persist event intent atomically with domain writes (ARC-05).
  • Inputs: PLATFORM-SPEC Sections 9.4, 10.
  • Outputs: starter-outbox autoconfig, JDBC store, Flyway migration.
  • Acceptance Criteria:
  • Testcontainers Postgres: OutboxService.publish writes a row with status NEW; the migration creates the table and index with CREATE TABLE IF NOT EXISTS.
  • Dependencies: 2.4.1
  • Complexity: M

3.2.5 starter-inbox

  • ID: 3.2.5
  • Title: Implement JDBC inbox store, behavior wiring, and migration
  • Description: JdbcInboxStore (spring-jdbc), InboxAutoConfiguration wiring DefaultInboxService and contributing InboxBehavior as a PipelineBehavior bean. Flyway migration creating an inbox table (message_id, handler, processed_at, primary key (message_id, handler)). Props telco.platform.inbox.*.
  • Business Purpose: Idempotent consumption guard available to every service via the mediator.
  • Inputs: PLATFORM-SPEC Sections 9.5, 10.
  • Outputs: starter-inbox autoconfig, JDBC store, Flyway migration.
  • Acceptance Criteria:
  • Testcontainers Postgres: first markProcessed returns true, a duplicate returns false; InboxBehavior is registered as a behavior bean.
  • Dependencies: 2.5.1, 3.2.2
  • Complexity: M

3.2.6 starter-observability

  • ID: 3.2.6
  • Title: Implement correlation filter and tracing customizer
  • Description: CorrelationFilter (OncePerRequestFilter): read or generate X-Correlation-Id, set CorrelationContextHolder + MDC (traceId, correlationId), echo the header on the response, and clear on completion. ObservabilityAutoConfiguration registers the filter (conditional on web) and a Micrometer tracing customizer (conditional on micrometer classes) exporting OTLP to the collector. Props telco.platform.observability.* (e.g. correlation.enabled default true).
  • Business Purpose: Every request carries traceId/correlationId into logs and traces (NFR-07/08/13).
  • Inputs: PLATFORM-SPEC Section 9.6, ADR-012.
  • Outputs: starter-observability autoconfig + filter.
  • Acceptance Criteria:
  • A request without X-Correlation-Id gets one generated and echoed on the response; MDC keys are populated during handling and cleared after.
  • Dependencies: 2.1.3
  • Complexity: M

3.2.7 Logback structured-JSON and PII masking

  • ID: 3.2.7
  • Title: Provide shared logback-spring JSON config with PII masking
  • Description: Ship a shared logback-spring.xml (in starter-observability or a logging starter) emitting structured JSON with MDC trace/correlation fields, and a masking converter that redacts PII (TCKN, card number, MSISDN, email) per ADR-021.
  • Business Purpose: Centralized structured logging to Loki with no PII leakage (NFR-08, ADR-021).
  • Inputs: ADR-012, ADR-021.
  • Outputs: Shared logback config + masking converter + unit test.
  • Acceptance Criteria:
  • Log output is valid JSON containing traceId/correlationId; a logged TCKN/card number appears masked (unit test asserts the raw value is absent).
  • Dependencies: 3.2.6
  • Complexity: M

Acceptance Criteria

Each subtask above carries its own objective, testable acceptance criteria. This feature is complete when every subtask's acceptance criteria are met.

Deliverables

  • starter-api autoconfig + handler.
  • starter-mediator autoconfig.
  • starter-security autoconfig + filter + JwtService.
  • starter-outbox autoconfig, JDBC store, Flyway migration.
  • starter-inbox autoconfig, JDBC store, Flyway migration.
  • starter-observability autoconfig + filter.
  • Shared logback config + masking converter + unit test.

Definition of Done

  • All subtasks (3.2.1, 3.2.2, 3.2.3, 3.2.4, 3.2.5, 3.2.6, 3.2.7) completed and their acceptance criteria verified.
  • All listed dependencies satisfied.
  • Build and tests green per the global conventions in ../README.md (Section 3).