Skip to content

3.4 Service Template and Reference Service

Sprint: Sprint 03 - Platform Starters and Event Contracts
Feature ID: 3.4
Subtasks: 3.4.1, 3.4.2, 3.4.3

Objective

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

Dependencies

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

  • 3.2.1
  • 3.2.2
  • 3.2.3
  • 3.2.6
  • 3.2.4
  • 3.2.5
  • 3.2.7
  • 3.3.1
  • 3.4.1

Subtasks

3.4.1 Service template

  • ID: 3.4.1
  • Title: Create the standard service template (ADR-017)
  • Description: microservices/service-template with the standard layout (api, application, domain, infrastructure), pom.xml inheriting the BOM and depending only on starters, a CLAUDE.md declaring Architecture Mode: CQRS + MEDIATOR, an application.yml (port, datasource, Flyway locations including classpath:db/migration/platform, OTLP exporter), a Dockerfile, a sample command/query/handler, and a controller returning ApiResult.
  • Business Purpose: One-command basis for every domain service; enforces ADR-017 structure.
  • Inputs: ADR-017, ADR-018, PLATFORM-SPEC.
  • Outputs: microservices/service-template skeleton.
  • Acceptance Criteria:
  • The template builds; its sample endpoint returns ApiResult via the mediator; it depends on no platform-core module directly.
  • Dependencies: 3.2.1, 3.2.2, 3.2.3, 3.2.6
  • Complexity: M

3.4.2 Reference service end-to-end

  • ID: 3.4.2
  • Title: Build reference-service proving the full stack
  • Description: microservices/reference-service derived from the template with a real entity (DemoItem), Flyway migration, a create command publishing a demo-item.created.v1 event via the outbox, list/get queries, and integration tests using Testcontainers (Postgres + Kafka).
  • Business Purpose: Living proof that mediator, outbox, inbox, security, observability, and Flyway all work together; the canonical example for domain teams.
  • Inputs: 3.2.x, 3.3.1.
  • Outputs: reference-service with migrations, handlers, outbox publish, integration tests.
  • Acceptance Criteria:
  • Integration test: POST creates an item, persists it, writes an outbox row, and returns ApiResult; the list query returns it. Build and tests green.
  • Dependencies: 3.2.4, 3.2.5, 3.2.7, 3.3.1, 3.4.1
  • Complexity: L

3.4.3 Starter integration (context-wiring) tests

  • ID: 3.4.3
  • Title: Add ApplicationContextRunner wiring tests per starter
  • Description: For each starter, add ApplicationContextRunner tests asserting beans are created under the expected conditions and absent when disabled (BL-02 in the roadmap backlog).
  • Business Purpose: Verify autoconfiguration behavior beyond mere compilation.
  • Inputs: roadmap BL-02.
  • Outputs: Context-wiring test per starter.
  • Acceptance Criteria:
  • Each starter has a passing test asserting bean presence/absence per @ConditionalOn....
  • Dependencies: 3.2.1, 3.2.2, 3.2.3, 3.2.4, 3.2.5, 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

  • microservices/service-template skeleton.
  • reference-service with migrations, handlers, outbox publish, integration tests.
  • Context-wiring test per starter.

Definition of Done

  • All subtasks (3.4.1, 3.4.2, 3.4.3) completed and their acceptance criteria verified.
  • All listed dependencies satisfied.
  • Build and tests green per the global conventions in ../README.md (Section 3).