# Kickoff Java Project — Core Maven Modules

Core Maven modules scaffolded for every project. See `conventions.md` for JSpecify, starter renames, and known pitfalls.

Reference: Janus module POMs and source classes.

---

## common module (`<prefix>-common`)

Shared utilities, constants, annotations.

### POM dependencies

```xml
<dependency><groupId>org.jspecify</groupId><artifactId>jspecify</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-logging</artifactId></dependency>
<dependency><groupId>io.github.jaspeen</groupId><artifactId>ulid-java</artifactId></dependency>
<dependency><groupId>jakarta.annotation</groupId><artifactId>jakarta.annotation-api</artifactId></dependency>
<dependency><groupId>jakarta.validation</groupId><artifactId>jakarta.validation-api</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
```

### Source structure

- `src/main/java/<base-package>/common/package-info.java` — `@NullMarked`
- `src/test/java/<base-package>/common/` — at least one sample unit test

---

## model module (`<prefix>-model`)

Domain entities, repositories, Liquibase migrations.

### POM dependencies

```xml
<dependency><groupId>${project.groupId}</groupId><artifactId><prefix>-common</artifactId></dependency>
<!-- jOOQ -->
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-jooq</artifactId></dependency>
<!-- OR Hibernate -->
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-jpa</artifactId></dependency>

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId></dependency>
<dependency><groupId>org.springframework.data</groupId><artifactId>spring-data-commons</artifactId></dependency>
<dependency><groupId>org.postgresql</groupId><artifactId>postgresql</artifactId><scope>runtime</scope></dependency>
<dependency><groupId>software.amazon.jdbc</groupId><artifactId>aws-advanced-jdbc-wrapper</artifactId></dependency>
<dependency><groupId>software.amazon.awssdk</groupId><artifactId>rds</artifactId></dependency>
<dependency><groupId>software.amazon.awssdk</groupId><artifactId>sso</artifactId></dependency>
<dependency><groupId>software.amazon.awssdk</groupId><artifactId>ssooidc</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-liquibase</artifactId></dependency>
<dependency><groupId>io.github.jaspeen</groupId><artifactId>ulid-java</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
<dependency><groupId>org.testcontainers</groupId><artifactId>testcontainers-postgresql</artifactId><scope>test</scope></dependency>
```

### jOOQ codegen plugin (if jOOQ)

```xml
<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>build-helper-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>add-generated-sources</id>
            <goals><goal>add-source</goal></goals>
            <phase>generate-sources</phase>
            <configuration>
                <sources><source>target/generated-sources/jooq</source></sources>
            </configuration>
        </execution>
    </executions>
</plugin>
<plugin>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers-jooq-codegen-maven-plugin</artifactId>
    <dependencies>
        <dependency><groupId>org.testcontainers</groupId><artifactId>testcontainers</artifactId><version>${testcontainers.version}</version></dependency>
        <dependency><groupId>org.testcontainers</groupId><artifactId>testcontainers-jdbc</artifactId><version>${testcontainers.version}</version></dependency>
        <dependency><groupId>org.testcontainers</groupId><artifactId>testcontainers-postgresql</artifactId><version>${testcontainers.version}</version></dependency>
        <dependency><groupId>org.postgresql</groupId><artifactId>postgresql</artifactId><version>${postgresql.version}</version></dependency>
    </dependencies>
    <executions>
        <execution>
            <id>generate-jooq-sources</id>
            <goals><goal>generate</goal></goals>
            <phase>generate-sources</phase>
            <configuration>
                <skip>${skip.jooq.codegen}</skip>
                <database>
                    <type>POSTGRES</type>
                    <containerImage>postgres:17.5</containerImage>
                </database>
                <liquibase>
                    <changeLogPath>db/changelog/db.changelog-master.yaml</changeLogPath>
                    <changeLogDirectory>src/main/resources</changeLogDirectory>
                </liquibase>
                <jooq>
                    <generator>
                        <database>
                            <inputSchema>public</inputSchema>
                            <includeForeignKeys>false</includeForeignKeys>
                        </database>
                        <generate>
                            <tables>true</tables><records>true</records>
                            <pojos>false</pojos><interfaces>false</interfaces>
                            <daos>false</daos><javaTimeTypes>true</javaTimeTypes>
                        </generate>
                        <target>
                            <packageName>co.humand.<project>.jooq</packageName>
                            <directory>target/generated-sources/jooq</directory>
                        </target>
                    </generator>
                </jooq>
            </configuration>
        </execution>
    </executions>
</plugin>
```

### Liquibase

- `src/main/resources/db/changelog/db.changelog-master.yaml` with `includeAll: path: changes/`
- `src/main/resources/db/changelog/changes/` — one initial migration (placeholder SQL)

### Entity convention

```java
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class SampleEntity {
    private long id;
    private long instanceId;
    private String name;
    @Nullable private String description;
    private Instant createdAt;
    private Instant updatedAt;
}
```

### Repository pattern (jOOQ)

```java
public interface SampleEntityRepository {
    Optional<SampleEntity> findById(long id);
}
```

```java
@Repository
@RequiredArgsConstructor
public class SampleEntityRepositoryImpl implements SampleEntityRepository {
    private final DSLContext dslContext;

    @Override
    public Optional<SampleEntity> findById(long id) {
        // jOOQ DSL query
    }
}
```

### Source structure

- `src/main/java/<base-package>/model/package-info.java` — `@NullMarked` (top-level only)
- `src/test/java/` — at least one sample unit test

---

## core module (`<prefix>-core`)

Business logic services, exceptions, caching.

### POM dependencies

```xml
<dependency><groupId>${project.groupId}</groupId><artifactId><prefix>-common</artifactId></dependency>
<dependency><groupId>${project.groupId}</groupId><artifactId><prefix>-model</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-cache</artifactId></dependency>
<!-- If Trace=Yes -->
<dependency><groupId>com.datadoghq</groupId><artifactId>dd-trace-api</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
```

### Service pattern

```java
@Service
@RequiredArgsConstructor
public class SampleService {
    private final SampleEntityRepository sampleEntityRepository;

    @Transactional(readOnly = true)
    public SampleEntity findById(long id) {
        return sampleEntityRepository.findById(id)
                .orElseThrow(() -> new SampleNotFoundException("Sample not found: " + id));
    }
}
```

If **Redis = Yes**: add `@Cacheable(value = CacheNames.X, key = "#id")` on read methods, `@CacheEvict` on writes.

If **Trace = Yes**: add `@Trace` on service methods.

### Exception pattern

```java
public class SampleNotFoundException extends RuntimeException {
    public SampleNotFoundException(String message) {
        super(message);
    }
}
```

```java
public enum ExceptionCodes {
    ENTITY_NOT_FOUND,
    VALIDATION_ERROR
}
```

### Source structure

- `src/main/java/<base-package>/core/package-info.java` — `@NullMarked`
- `src/test/java/` — at least one sample unit test

---

## webapp module (`<prefix>-webapp`)

Spring Boot application entry point, controllers, security config, test infrastructure.

### POM dependencies

```xml
<!-- Module deps -->
<dependency><groupId>${project.groupId}</groupId><artifactId><prefix>-common</artifactId></dependency>
<dependency><groupId>${project.groupId}</groupId><artifactId><prefix>-model</artifactId></dependency>
<dependency><groupId>${project.groupId}</groupId><artifactId><prefix>-core</artifactId></dependency>
<dependency><groupId>${project.groupId}</groupId><artifactId><prefix>-security</artifactId></dependency>
<!-- If Kafka=Yes -->
<dependency><groupId>${project.groupId}</groupId><artifactId><prefix>-kafka</artifactId></dependency>

<!-- Spring Boot -->
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-webmvc</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-actuator</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-security</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-security-oauth2-resource-server</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId></dependency>
<!-- If Redis=Yes -->
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-data-redis</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-cache</artifactId></dependency>

<dependency><groupId>io.micrometer</groupId><artifactId>micrometer-registry-statsd</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-logging</artifactId></dependency>
<dependency><groupId>co.humand.commons</groupId><artifactId>logging</artifactId></dependency>
<dependency><groupId>co.humand.commons.security</groupId><artifactId>authentication</artifactId></dependency>
<!-- If Swagger=Yes -->
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId></dependency>
<dependency><groupId>commons-io</groupId><artifactId>commons-io</artifactId></dependency>

<!-- Test -->
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-restclient</artifactId><scope>test</scope></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-resttestclient</artifactId><scope>test</scope></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-testcontainers</artifactId><scope>test</scope></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-security-test</artifactId><scope>test</scope></dependency>
<dependency><groupId>org.testcontainers</groupId><artifactId>testcontainers-junit-jupiter</artifactId><scope>test</scope></dependency>
<dependency><groupId>org.testcontainers</groupId><artifactId>testcontainers-postgresql</artifactId><scope>test</scope></dependency>
<!-- If Kafka=Yes -->
<dependency><groupId>org.testcontainers</groupId><artifactId>testcontainers-kafka</artifactId><scope>test</scope></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-kafka-test</artifactId><scope>test</scope></dependency>
<dependency><groupId>org.awaitility</groupId><artifactId>awaitility</artifactId><scope>test</scope></dependency>
```

### Build plugins

**spring-boot-maven-plugin:**

```xml
<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <mainClass>co.humand.<project>.webapp.Application</mainClass>
    </configuration>
    <executions><execution><goals><goal>repackage</goal></goals></execution></executions>
</plugin>
```

**maven-failsafe-plugin** (integration tests):

```xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-failsafe-plugin</artifactId>
    <configuration>
        <includes><include>**/*IntegrationTest.java</include></includes>
        <classesDirectory>${project.build.outputDirectory}</classesDirectory>
        <argLine>@{argLine} --enable-preview --enable-native-access=ALL-UNNAMED</argLine>
    </configuration>
    <executions>
        <execution><goals><goal>integration-test</goal><goal>verify</goal></goals></execution>
    </executions>
</plugin>
```

**build-helper-maven-plugin** (test-integration source):

```xml
<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>build-helper-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>add-integration-test-source</id>
            <goals><goal>add-test-source</goal></goals>
            <phase>generate-test-sources</phase>
            <configuration><sources><source>src/test-integration/java</source></sources></configuration>
        </execution>
        <execution>
            <id>add-integration-test-resource</id>
            <goals><goal>add-test-resource</goal></goals>
            <phase>generate-test-resources</phase>
            <configuration><resources><resource><directory>src/test-integration/resources</directory></resource></resources></configuration>
        </execution>
    </executions>
</plugin>
```

**JaCoCo** (merged coverage for unit + integration):

```xml
<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <configuration>
        <excludes>
            <exclude>**/co/humand/<project>/jooq/**</exclude>
            <exclude>**/co/humand/<project>/webapp/config/cache/**</exclude>
        </excludes>
    </configuration>
    <executions>
        <execution><id>default-prepare-agent</id><goals><goal>prepare-agent</goal></goals></execution>
        <execution>
            <id>prepare-agent-integration</id>
            <goals><goal>prepare-agent-integration</goal></goals>
            <configuration><destFile>${project.build.directory}/jacoco-it.exec</destFile></configuration>
        </execution>
        <execution>
            <id>merge-results</id><goals><goal>merge</goal></goals><phase>verify</phase>
            <configuration>
                <fileSets><fileSet><directory>${project.build.directory}</directory><includes><include>*.exec</include></includes></fileSet></fileSets>
                <destFile>${project.build.directory}/jacoco-merged.exec</destFile>
            </configuration>
        </execution>
        <execution>
            <id>report-merged</id><goals><goal>report</goal></goals><phase>verify</phase>
            <configuration>
                <dataFile>${project.build.directory}/jacoco-merged.exec</dataFile>
                <outputDirectory>${project.reporting.outputDirectory}/jacoco-merged</outputDirectory>
            </configuration>
        </execution>
        <execution>
            <id>check-coverage</id><goals><goal>check</goal></goals><phase>verify</phase>
            <configuration>
                <dataFile>${project.build.directory}/jacoco-merged.exec</dataFile>
                <rules><rule><element>BUNDLE</element><limits>
                    <limit><counter>INSTRUCTION</counter><value>COVEREDRATIO</value><minimum>0.00</minimum></limit>
                    <limit><counter>BRANCH</counter><value>COVEREDRATIO</value><minimum>0.00</minimum></limit>
                </limits></rule></rules>
            </configuration>
        </execution>
    </executions>
</plugin>
```

Initial thresholds: `0.00` (0%). Increase as tests are added.

### Application.java

```java
@SpringBootApplication(scanBasePackages = "co.humand.<project>")
@Import(SecurityConfiguration.class)
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
```

### WebSecurityConfiguration

Copy from Janus `WebSecurityConfiguration`. Key structure:
- `@Configuration @EnableWebSecurity @EnableMethodSecurity`
- `SecurityFilterChain` bean: CSRF disabled, CORS with defaults, OAuth2 resource server with JWT, permit actuator/swagger/OPTIONS, authenticated for rest, `BearerTokenAuthenticationFilter`, stateless sessions
- `JwtDecoder` bean using `SecurityConfigurationProperties`
- `CorsConfigurationSource` bean from `SecurityConfigurationProperties.Cors`

### Security classes (in webapp)

- **AuthenticatedUser** — record with JWT claims (`instanceId`, `userId`, `scope`, etc.)
- **JwtTokenConverter** — converts JWT to `JanusAuthenticationToken` with `AuthenticatedUser` as principal. Null-check all claims.
- **CustomAuthenticationEntryPoint** — returns 401 JSON error
- **JanusAuthenticationToken** (or `<Project>AuthenticationToken`) — extends `AbstractAuthenticationToken`

### HttpLoggingConfiguration

```java
@Configuration
class HttpLoggingConfiguration {
    @Bean
    PrincipalInfoExtractor principalInfoExtractor() {
        return authentication -> {
            if (authentication != null && authentication.getPrincipal() instanceof AuthenticatedUser user) {
                return new PrincipalInfo(user.userId(), user.instanceId());
            }
            return PrincipalInfo.ANONYMOUS;
        };
    }

    @Bean
    FilterRegistrationBean<HttpIncomingLoggingFilter> httpLoggingFilterRegistration(
            HttpIncomingLoggingFilter httpIncomingLoggingFilter) {
        FilterRegistrationBean<HttpIncomingLoggingFilter> registration =
                new FilterRegistrationBean<>(httpIncomingLoggingFilter);
        registration.setEnabled(false);
        return registration;
    }
}
```

### OpenApiConfig (if Swagger=Yes)

```java
@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI openAPI(@Value("${server.servlet.context-path}") String contextPath) {
        return new OpenAPI()
                .servers(List.of(new Server().url(contextPath).description("Server URL")))
                .info(new Info().title("<Project> Service").version("v1.0.0"))
                .components(new Components()
                        .addSecuritySchemes("JWT", new SecurityScheme()
                                .type(SecurityScheme.Type.HTTP).scheme("bearer")
                                .bearerFormat("JWT").in(SecurityScheme.In.HEADER).name("Authorization")))
                .addSecurityItem(new SecurityRequirement().addList("JWT"));
    }
}
```

### GlobalExceptionHandler

```java
@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(SampleNotFoundException.class)
    public ResponseEntity<Map<String, String>> handle(SampleNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
                .body(Map.of("code", ExceptionCodes.ENTITY_NOT_FOUND.name(), "message", ex.getMessage()));
    }
}
```

### Controller pattern

**If Swagger=Yes** — API interface + controller:

```java
@Tag(name = "Sample")
public interface SampleApi {
    @Operation(summary = "Get sample by ID")
    @GetMapping("/{id}")
    @PreAuthorize("isAuthenticated()")
    ResponseEntity<SampleResponse> getById(@PathVariable long id, @AuthenticationPrincipal AuthenticatedUser user);
}
```

```java
@RestController
@RequestMapping("/sample")
@RequiredArgsConstructor
public class SampleController implements SampleApi {
    private final SampleService sampleService;

    @Override
    public ResponseEntity<SampleResponse> getById(long id, AuthenticatedUser user) {
        return ResponseEntity.ok(SampleResponse.from(sampleService.findById(id)));
    }
}
```

**If Swagger=No** — annotations directly on controller.

### Response DTO

```java
public record SampleResponse(long id, String name) {
    public static SampleResponse from(SampleEntity entity) {
        return new SampleResponse(entity.getId(), entity.getName());
    }
}
```

### application.yml

```yaml
humand:
  <project>:
    db:
      endpoint: <project>-db
      port: 5432
      database: <project>
      username: jooq  # or hibernate
      liquibase:
        username: liquibase
    security:
      jwt:
        secret: ""
        jwks-rsa-url: ""
  logging:
    http:
      tracing-header: x-request-id
      log-body: false
      max-body-length: 10000

server:
  port: 8080
  servlet:
    context-path: /api/v1/<project>
  shutdown: graceful

spring:
  application.name: <prefix>-webapp
  lifecycle:
    timeout-per-shutdown-phase: 15s
  datasource:
    type: org.springframework.jdbc.datasource.SimpleDriverDataSource
    url: "jdbc:aws-wrapper:postgresql://${humand.<project>.db.endpoint}:${humand.<project>.db.port}/${humand.<project>.db.database}"
    username: "${humand.<project>.db.username}"
    driver-class-name: software.amazon.jdbc.Driver
  jooq:  # if jOOQ
    sql-dialect: POSTGRES
  # jpa:  # if Hibernate
  #   hibernate.ddl-auto: validate
  #   open-in-view: false
  liquibase:
    user: "${humand.<project>.db.liquibase.username}"

management:
  server:
    port: 8081
  endpoints:
    web:
      exposure:
        include: "health,loggers,metrics"
  endpoint:
    health:
      show-components: always
    loggers:
      access: unrestricted

logging:
  level:
    root: info
    co.humand.<project>: debug
```

### Source structure

- `src/main/java/<base-package>/webapp/package-info.java` — `@NullMarked` (top-level only, subpackages inherit)
- `src/test/java/` — at least one sample unit test
- `src/test-integration/java/` — BaseIntegrationTest + ActuatorIntegrationTest
- **Do NOT add `package-info.java` in `src/test-integration/java/` for the same package as `src/test/java/`** — compiler treats both as one and will error

---

## Test Infrastructure (webapp)

### BaseIntegrationTest

Copy from Janus. Key elements:

```java
@SpringBootTest(classes = Application.class, webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
@AutoConfigureTestRestTemplate
@ActiveProfiles("test")
@Import({BaseTestConfiguration.class})
public abstract class BaseIntegrationTest {
    @LocalServerPort protected int port;
    @Value("${server.servlet.context-path}") protected String contextPath;
    @Autowired protected TestRestTemplate restTemplate;

    public record TestUser(long instanceId, long userId) {}

    protected String getBaseUrl() { ... }
    protected String generateJwt(TestUser user, String scope) { ... }
    protected String generateJwtWithClaims(JWTClaimsSet claims) { ... }
    protected <B> RequestBuilder<B> get/post/put/delete(String endpoint) { ... }

    protected class RequestBuilder<B> {
        public RequestBuilder<B> withUser(TestUser user) { ... }
        public RequestBuilder<B> withBody(B body) { ... }
        public RequestBuilder<B> withHeader(String name, String value) { ... }
        public <T> ResponseEntity<T> exchange(Class<T> responseType) { ... }
        public <T> ResponseEntity<T> exchange(ParameterizedTypeReference<T> responseType) { ... }
    }
}
```

**JWT generation**: RS256 with `signing-key.pem`, kid `"test-key"`. Expiration: `Instant.now().plus(Duration.ofMinutes(1))`.

**Imports**: `org.springframework.boot.resttestclient.TestRestTemplate`, `org.springframework.boot.resttestclient.autoconfigure.AutoConfigureTestRestTemplate`

### BaseTestConfiguration

```java
@Import({SecurityConfiguration.class, TestContainersConfiguration.class})
// If Kafka=Yes: also import KafkaDLTTestListenerConfig.class
public class BaseTestConfiguration {
    // Add @Bean @Primary mocks for external dependencies as needed
}
```

### TestContainersConfiguration

```java
@TestConfiguration(proxyBeanMethods = false)
public class TestContainersConfiguration {

    @Bean
    @ServiceConnection
    @ConditionalOnProperty(name = "testcontainers.postgres.enabled", havingValue = "true", matchIfMissing = true)
    PostgreSQLContainer postgresContainer() {
        return new PostgreSQLContainer(DockerImageName.parse("postgres:17.7"));
    }

    // If Kafka=Yes:
    @Bean
    @ServiceConnection(name = "kafka")
    @ConditionalOnProperty(name = "testcontainers.kafka.enabled", havingValue = "true")
    ConfluentKafkaContainer kafkaContainer() {
        return new ConfluentKafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:7.8.0"));
    }

    @Bean
    @ConditionalOnProperty(name = "testcontainers.kafka.enabled", havingValue = "true")
    DynamicPropertyRegistrar kafkaPropertiesRegistrar(final ConfluentKafkaContainer kafkaContainer) {
        return registry -> registry.add("spring.kafka.bootstrap-servers", kafkaContainer::getBootstrapServers);
    }
}
```

### TestJwksController

```java
@RestController
@Profile("test")
public class TestJwksController {
    @GetMapping(path = "/.well-known/jwks.json", produces = MediaType.APPLICATION_JSON_VALUE)
    public Resource getJwks() {
        return new ClassPathResource("static/jwks.json");
    }
}
```

Copy `signing-key.pem` and `static/jwks.json` from Janus `src/test-integration/resources/`.

### ActuatorIntegrationTest (mandatory)

```java
class ActuatorIntegrationTest extends BaseIntegrationTest {
    @Value("${local.management.port}")
    private int managementPort;

    @Test
    void actuatorHealthReturnsUp() throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("http://localhost:" + managementPort + "/actuator/health"))
                .GET()
                .build();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        assertThat(response.statusCode()).isEqualTo(200);
        assertThat(response.body()).contains("UP");
    }
}
```

Uses `java.net.http.HttpClient`, NOT `TestRestTemplate`, because management port is separate.

### application-test.yml

```yaml
humand:
  <project>:
    security:
      cors:
        allowed-origins: ['*']
        allowed-headers: ['*']
      jwt:
        secret: test-secret
        jwks-rsa-url: http://localhost:${server.port}/api/v1/<project>/.well-known/jwks.json
    cache:
      enabled: false  # if Redis=Yes
    db:
      username: jooq
      liquibase:
        username: liquibase

spring:
  application.name: <prefix>-webapp-test
  autoconfigure:
    exclude:  # if Redis=Yes
      - org.springframework.boot.data.redis.autoconfigure.DataRedisAutoConfiguration
      - org.springframework.boot.data.redis.autoconfigure.DataRedisRepositoriesAutoConfiguration
  datasource:
    url: jdbc:tc:postgresql:17.5:///<project>
    driver-class-name: org.testcontainers.jdbc.ContainerDatabaseDriver
  liquibase:
    drop-first: true
    enabled: true
    change-log: classpath:db/changelog/db.changelog-master.yaml
  jooq:
    sql-dialect: POSTGRES

server:
  port: 8999
  shutdown: immediate

management:
  server:
    port: 0
  endpoints:
    web:
      exposure:
        include: health

testcontainers:
  postgres:
    enabled: true
  kafka:  # if Kafka=Yes
    enabled: true
```

---

## jacoco-aggregate module (`<prefix>-jacoco-aggregate`)

Aggregates JaCoCo coverage across all modules.

### POM

```xml
<packaging>pom</packaging>
<dependencies>
    <dependency><groupId>${project.groupId}</groupId><artifactId><prefix>-common</artifactId></dependency>
    <dependency><groupId>${project.groupId}</groupId><artifactId><prefix>-model</artifactId></dependency>
    <dependency><groupId>${project.groupId}</groupId><artifactId><prefix>-core</artifactId></dependency>
    <dependency><groupId>${project.groupId}</groupId><artifactId><prefix>-security</artifactId></dependency>
    <!-- If Kafka=Yes -->
    <dependency><groupId>${project.groupId}</groupId><artifactId><prefix>-kafka</artifactId></dependency>
    <dependency><groupId>${project.groupId}</groupId><artifactId><prefix>-webapp</artifactId></dependency>
</dependencies>
<build>
    <plugins>
        <plugin>
            <groupId>org.jacoco</groupId>
            <artifactId>jacoco-maven-plugin</artifactId>
            <executions>
                <execution>
                    <id>default-report</id>
                    <goals><goal>report</goal></goals>
                </execution>
                <execution>
                    <id>report-aggregate</id>
                    <goals><goal>report-aggregate</goal></goals>
                    <phase>prepare-package</phase>
                    <configuration>
                        <dataFileIncludes><dataFileInclude>target/*.exec</dataFileInclude></dataFileIncludes>
                        <includeCurrentProject>false</includeCurrentProject>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
```