Part 2 of 1712% complete

2026-08-16•6 min read

Scaffold the multi-module build: Gradle 9, convention plugins, and architecture tests

Checkpoint tag: chapter-01-build-foundation — ./gradlew clean check passes on an empty application skeleton, and the first architecture rules are enforced.

What will be built

The complete repository skeleton: nine Gradle modules, an included build-logic build that supplies four convention plugins, a version catalog, a Java 25 toolchain, JUnit 5 test wiring, reproducible archives, two standing ArchUnit rules, and a GitHub Actions workflow. At the end of this chapter every application module compiles and boots nothing — deliberately. The point is that every later chapter only edits the module it owns.

Why it matters

In a single-module project, “the model layer must not depend on Spring AI” is a sentence in a README that rots within weeks. In a multi-module build it is a compile-time fact: domain-contracts literally does not have Spring AI on its classpath. Convention plugins matter for the same reason — without them, every module’s build file drifts into its own dialect of toolchain, test, and quality configuration, and the drift always shows up at the worst moment (CI green locally, red on main). ArchUnit exists for the boundaries Gradle cannot express — “web adapters must not touch repositories” is a package rule, not a dependency rule.

Prerequisites and starting point

Starting tag: none (empty repository). You need Docker not at all today; you need a JDK only if you disable Gradle’s toolchain auto-provisioning. Install Gradle once to generate the wrapper, or use the gradle wrapper bootstrap described below — after that, ./gradlew is the only entry point.

Architecture before and after

Before: an empty directory. After:

Concepts explained

Convention plugins (build-logic + includeBuild) are precompiled Kotlin DSL scripts that bundle your own defaults. Each module then says id("ops.spring-application") instead of repeating toolchain, compiler, and test config. Gradle resolves ops.* plugin IDs to the scripts in build-logic/src/main/kotlin.

BOMs vs. starters. A BOM (spring-boot-dependencies, spring-ai-bom) manages versions via platform(...); a starter pulls in functionality. Never pin a version that a BOM already manages — that is how half-upgraded classpaths happen.

Toolchains decouple “the JDK running Gradle” from “the JDK compiling and testing your code.” languageVersion = 25 on every module means a JDK 21 host still produces Java 25 bytecode via auto-provisioned toolchains.

Boot 4 starter names. Spring Boot 4 renamed its starters: spring-boot-starter-web is deprecated for spring-boot-starter-webmvc, OAuth starters moved under spring-boot-starter-security-*, and spring-boot-starter-test is slimmer (spring-boot-starter-test-classic restores the old bundle). This series uses the new names throughout.

Files added or changed

1
gradle.properties
2
settings.gradle.kts
3
build.gradle.kts
4
gradle/libs.versions.toml
5
build-logic/settings.gradle.kts
6
build-logic/build.gradle.kts
7
build-logic/src/main/kotlin/ops.java-library.gradle.kts
8
build-logic/src/main/kotlin/ops.kotlin-library.gradle.kts
9
build-logic/src/main/kotlin/ops.spring-application.gradle.kts
10
build-logic/src/main/kotlin/ops.quality.gradle.kts
11
domain-contracts/build.gradle.kts
12
operations-simulator/{build.gradle.kts, src/main/java/.../SimulatorApplication.java}
13
agent-api/{build.gradle.kts, src/main/java/.../AgentApiApplication.java}
14
knowledge-ingestion/{build.gradle.kts, src/main/java/.../IngestionApplication.java}
15
mcp-operations-server/{build.gradle.kts, src/main/kotlin/.../McpServerApplication.kt}
16
test-support/build.gradle.kts
17
evaluation-suite/build.gradle.kts
18
architecture-tests/{build.gradle.kts, src/test/java/.../BoundaryRulesTest.java}
19
.github/workflows/ci.yml

Implementation steps

gradle wrapper --gradle-version 9.7.1 in the repo root (or hand-create the wrapper files once), then never touch a global Gradle again.
Write settings.gradle.kts declaring includeBuild("build-logic") and the eight modules.
Write gradle/libs.versions.toml with every non-BOM-managed version.
Write the four convention plugins.
Write each module’s build.gradle.kts plus a minimal application entry point.
Write the first ArchUnit rules.
./gradlew clean check until green; commit; add CI.

Complete code

gradle.properties

1
org.gradle.jvmargs=-Xmx2g -Dfile.encoding=UTF-8
2
org.gradle.parallel=true
3
org.gradle.caching=true
4
org.gradle.configuration-cache=true
5
org.gradle.warning.mode=all

settings.gradle.kts — the Foojay plugin is applied at top level so the Java 25 toolchain auto-provisions on machines that only have an older JDK:

1
plugins {
2
    // Auto-provision toolchains (e.g. JDK 25) when not installed locally
3
    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
4
}
5

6
rootProject.name = "ops-agent-platform"
7

8
includeBuild("build-logic")
9

10
include(
11
    "domain-contracts",
12
    "agent-api",
13
    "knowledge-ingestion",
14
    "mcp-operations-server",
15
    "operations-simulator",
16
    "test-support",
17
    "evaluation-suite",
18
    "architecture-tests",
19
)

gradle/libs.versions.toml

1
[versions]
2
springBoot = "4.1.1"
3
springAi = "2.0.1"
4
kotlin = "2.3.21"
5
testcontainers = "2.0.5"
6
archunit = "1.4.1"
7
awaitility = "4.3.0"
8
wiremock = "3.13.1"
9

10
[libraries]
11
spring-ai-bom = { module = "org.springframework.ai:spring-ai-bom", version.ref = "springAi" }
12
testcontainers-bom = { module = "org.testcontainers:testcontainers-bom", version.ref = "testcontainers" }
13
assertj = { module = "org.assertj:assertj-core" }
14
awaitility = { module = "org.awaitility:awaitility", version.ref = "awaitility" }
15
archunit-junit5 = { module = "com.tngtech.archunit:archunit-junit5", version.ref = "archunit" }
16
wiremock = { module = "org.wiremock:wiremock-standalone", version.ref = "wiremock" }
17
# Testcontainers 2.x renamed its artifacts — the bare `postgresql`/`junit-jupiter`
18
# names do not exist in the 2.0.5 BOM.
19
testcontainers-postgresql = { module = "org.testcontainers:testcontainers-postgresql" }
20
testcontainers-junit = { module = "org.testcontainers:testcontainers-junit-jupiter" }
21

22
[plugins]
23
spring-boot = { id = "org.springframework.boot", version.ref = "springBoot" }

Versions the Spring Boot BOM already manages (JUnit, AssertJ, Mockito, Jackson, Flyway, Testcontainers) intentionally have no [versions] entry — pinning them anyway is the classic source of a half-managed classpath.

build-logic/settings.gradle.kts

1
rootProject.name = "build-logic"
2

3
dependencyResolutionManagement {
4
    versionCatalogs {
5
        create("libs") {
6
            from(files("../gradle/libs.versions.toml"))
7
        }
8
    }
9
}

build-logic/build.gradle.kts — the plugin jars live on this classpath so id("org.springframework.boot") inside a convention script resolves without a plugin-portal lookup:

1
plugins {
2
    `kotlin-dsl`
3
}
4

5
repositories {
6
    mavenCentral()
7
    gradlePluginPortal()
8
}
9

10
dependencies {
11
    implementation("org.springframework.boot:spring-boot-gradle-plugin:4.1.1")
12
    implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:2.3.21")
13
    // kotlin-allopen carries the org.jetbrains.kotlin.plugin.spring plugin —
14
    // kotlin-gradle-plugin alone does not provide it.
15
    implementation("org.jetbrains.kotlin:kotlin-allopen:2.3.21")
16
}

build-logic/src/main/kotlin/ops.java-library.gradle.kts

1
plugins {
2
    `java-library`   // java-library, not java — api/implementation separation matters here
3
    jacoco
4
    id("ops.quality")
5
}
6

7
group = "in.o612.eng.opsagent"
8

9
repositories {
10
    mavenCentral()
11
}
12

13
java {
14
    toolchain {
15
        languageVersion = JavaLanguageVersion.of(25)
16
    }
17
}
18

19
tasks.withType<JavaCompile>().configureEach {
20
    options.encoding = "UTF-8"
21
    options.compilerArgs.addAll(listOf("-parameters"))
22
    options.release.set(25)
23
}
24

25
dependencies {
26
    // Test classpath versions come from the Boot BOM even on plain libraries:
27
    // one managed version universe for the whole build.
28
    testImplementation(platform("org.springframework.boot:spring-boot-dependencies:4.1.1"))
29
    testImplementation("org.junit.jupiter:junit-jupiter")
30
    testImplementation("org.assertj:assertj-core")
31
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
32
}
33

34
tasks.withType<Test>().configureEach {
35
    useJUnitPlatform()
36
    testLogging {
37
        events("passed", "failed", "skipped")
38
        showStandardStreams = false
39
    }
40
    finalizedBy(tasks.jacocoTestReport)
41
}
42

43
tasks.jacocoTestReport {
44
    dependsOn(tasks.test)
45
    reports {
46
        xml.required.set(true)
47
        html.required.set(true)
48
    }
49
}

build-logic/src/main/kotlin/ops.kotlin-library.gradle.kts

1
plugins {
2
    id("ops.java-library")
3
    id("org.jetbrains.kotlin.jvm")
4
    id("org.jetbrains.kotlin.plugin.spring")
5
}
6

7
kotlin {
8
    jvmToolchain(25)
9
}

build-logic/src/main/kotlin/ops.spring-application.gradle.kts

1
plugins {
2
    id("ops.java-library")
3
    id("org.springframework.boot")
4
}
5

6
dependencies {
7
    implementation(platform("org.springframework.boot:spring-boot-dependencies:4.1.1"))
8
    implementation("org.springframework.boot:spring-boot-starter-actuator")
9
    implementation("org.springframework.boot:spring-boot-starter-validation")
10
    testImplementation("org.springframework.boot:spring-boot-starter-test")
11
    testImplementation("org.springframework.boot:spring-boot-starter-webmvc-test")
12
}
13

14
// No mainClass wiring needed: Boot's resolveMainClassName task auto-detects
15
// the single @SpringBootApplication class in each module.

build-logic/src/main/kotlin/ops.quality.gradle.kts

1
// Reproducible archives. Deliberately NO failOnVersionConflict(): once
2
// spring-ai-bom sits next to spring-boot-dependencies, the two platforms
3
// legitimately disagree on transitive versions and Gradle's default
4
// resolution handles it. Drift is guarded by the version catalog +
5
// `./gradlew dependencyInsight` on review, not by a hard fail here.
6

7
tasks.withType<AbstractArchiveTask>().configureEach {
8
    isPreserveFileTimestamps = false
9
    isReproducibleFileOrder = true
10
}

domain-contracts/build.gradle.kts — framework-light on purpose: Jackson annotations for the JSON boundary types, nothing else.

1
plugins {
2
    id("ops.java-library")
3
}
4

5
dependencies {
6
    implementation(platform("org.springframework.boot:spring-boot-dependencies:4.1.1"))
7
    api("com.fasterxml.jackson.core:jackson-annotations")
8
}

operations-simulator/build.gradle.kts

1
plugins {
2
    id("ops.spring-application")
3
}
4

5
dependencies {
6
    implementation(project(":domain-contracts"))
7
    implementation("org.springframework.boot:spring-boot-starter-webmvc")
8
    implementation("org.springframework.boot:spring-boot-starter-jdbc")
9
    implementation("org.springframework.boot:spring-boot-starter-flyway")
10
    runtimeOnly("org.postgresql:postgresql")
11
}

operations-simulator/src/main/java/in/o612/eng/opsagent/simulator/SimulatorApplication.java

1
package in.o612.eng.opsagent.simulator;
2

3
import org.springframework.boot.SpringApplication;
4
import org.springframework.boot.autoconfigure.SpringBootApplication;
5

6
@SpringBootApplication
7
public class SimulatorApplication {
8

9
    public static void main(String[] args) {
10
        SpringApplication.run(SimulatorApplication.class, args);
11
    }
12
}

agent-api/build.gradle.kts

1
plugins {
2
    id("ops.spring-application")
3
}
4

5
dependencies {
6
    implementation(project(":domain-contracts"))
7
    implementation(platform(libs.spring.ai.bom))
8
    implementation("org.springframework.boot:spring-boot-starter-webmvc")
9
}

agent-api/src/main/java/in/o612/eng/opsagent/agent/AgentApiApplication.java

1
package in.o612.eng.opsagent.agent;
2

3
import org.springframework.boot.SpringApplication;
4
import org.springframework.boot.autoconfigure.SpringBootApplication;
5

6
@SpringBootApplication
7
public class AgentApiApplication {
8

9
    public static void main(String[] args) {
10
        SpringApplication.run(AgentApiApplication.class, args);
11
    }
12
}

knowledge-ingestion mirrors operations-simulator minus the web starter (it is a command-line job): implementation("org.springframework.boot:spring-boot-jdbc") plus spring-boot-starter-flyway and the Postgres driver, with an IngestionApplication class identical in shape.

mcp-operations-server/build.gradle.kts — the Kotlin module. Note the plugins block: id("org.springframework.boot") cannot be applied directly in a project build file (the plugin marker isn’t on the project’s plugin classpath), so the Boot plugin arrives via ops.spring-application:

1
plugins {
2
    id("ops.kotlin-library")
3
    id("ops.spring-application")   // brings org.springframework.boot + BOM + test deps
4
}
5

6
dependencies {
7
    implementation(platform(libs.spring.ai.bom))
8
    implementation(project(":domain-contracts"))
9
    implementation("org.springframework.boot:spring-boot-starter-webmvc")
10
    implementation("org.springframework.ai:spring-ai-starter-mcp-server-webmvc")
11
    implementation("org.jetbrains.kotlin:kotlin-stdlib")
12
}

mcp-operations-server/src/main/kotlin/in/o612/eng/opsagent/mcp/McpServerApplication.kt — note the backticks: in is a Kotlin keyword, so every Kotlin package declaration in this project escapes it.

1
package `in`.o612.eng.opsagent.mcp
2

3
import org.springframework.boot.autoconfigure.SpringBootApplication
4
import org.springframework.boot.runApplication
5

6
@SpringBootApplication
7
class McpServerApplication
8

9
fun main(args: Array<String>) {
10
    runApplication<McpServerApplication>(*args)
11
}

test-support/build.gradle.kts — fixtures only; nothing here may reach a production classpath.

1
plugins {
2
    id("ops.java-library")
3
}
4

5
dependencies {
6
    implementation(platform("org.springframework.boot:spring-boot-dependencies:4.1.1"))
7
    // api(platform) carries the BOM to consumers' classpaths; the
8
    // testImplementation platform is needed separately — an api-scoped
9
    // platform does not constrain our own test classpath.
10
    api(platform(libs.testcontainers.bom))
11
    testImplementation(platform(libs.testcontainers.bom))
12
    api(libs.testcontainers.postgresql)
13
    api(libs.testcontainers.junit)
14
    api(libs.assertj)
15
    api(libs.awaitility)
16
    implementation("org.springframework.boot:spring-boot-starter-test")
17
}

evaluation-suite and architecture-tests start as ops.java-library shells; architecture-tests additionally depends on the modules it inspects:

1
plugins {
2
    id("ops.java-library")
3
}
4

5
dependencies {
6
    testImplementation(project(":domain-contracts"))
7
    testImplementation(project(":operations-simulator"))
8
    testImplementation(project(":agent-api"))
9
    testImplementation(project(":mcp-operations-server"))
10
    testImplementation(libs.archunit.junit5)
11
}

architecture-tests/src/test/java/in/o612/eng/opsagent/arch/BoundaryRulesTest.java — the two rules that must hold for the entire series:

1
package in.o612.eng.opsagent.arch;
2

3
import com.tngtech.archunit.junit.AnalyzeClasses;
4
import com.tngtech.archunit.junit.ArchTest;
5
import com.tngtech.archunit.lang.ArchRule;
6

7
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
8

9
@AnalyzeClasses(packages = "in.o612.eng.opsagent")
10
class BoundaryRulesTest {
11

12
    @ArchTest
13
    static final ArchRule contracts_must_not_depend_on_framework_or_ai =
14
        noClasses()
15
            .that().resideInAPackage("in.o612.eng.opsagent.contracts..")
16
            .should().dependOnClassesThat().resideInAnyPackage(
17
                "org.springframework.ai..",
18
                "jakarta.persistence..",
19
                "org.springframework.web..",
20
                "io.modelcontextprotocol..")
21
            .allowEmptyShould(true);
22

23
    @ArchTest
24
    static final ArchRule web_adapters_must_not_touch_repositories =
25
        noClasses()
26
            .that().resideInAPackage("..web..")
27
            .should().dependOnClassesThat().resideInAPackage("..persistence..")
28
            .allowEmptyShould(true);
29
}

.github/workflows/ci.yml

1
name: ci
2
on:
3
  push:
4
  pull_request:
5
jobs:
6
  check:
7
    runs-on: ubuntu-latest
8
    steps:
9
      - uses: actions/checkout@v4
10
      - uses: actions/setup-java@v4
11
        with:
12
          distribution: temurin
13
          java-version: "25"
14
      - uses: gradle/actions/setup-gradle@v4
15
      - run: ./gradlew clean check
16
        env:
17
          CI: true

Commands to build and run

1
gradle wrapper --gradle-version 9.7.1   # once, to bootstrap
2
./gradlew clean check                   # compile, test, arch rules, coverage
3
./gradlew :operations-simulator:bootJar # produces an empty-but-real boot jar

Expected: BUILD SUCCESSFUL with a handful of no tests found-adjacent output for modules that only contain a main class. Nothing contacts an external service.

Verification note: this scaffold was built and checked against the pinned versions — ./gradlew clean check green on Gradle 9.7.1 with a provisioned JDK 25 toolchain, and both Java and Kotlin bootJars resolve their main classes automatically.

Failure-injection lab

The architecture tests should fail when the boundary is violated — prove it once now so you trust them later:

Add import jakarta.persistence.Entity; to any class under in.o612.eng.opsagent.contracts (you will need a temporary implementation dep, which is itself instructive — the dependency has to exist on the classpath before the rule can even see it).
./gradlew :architecture-tests:test → contracts_must_not_depend_on_framework_or_ai fails with the violating class listed.
Remove it. Green again.

The more interesting lesson: a rule can only guard what is on the classpath. Reviewers should still look at new dependencies {} blocks; ArchUnit is the second line, not the first.

Security considerations

A single version catalog is the dependency chokepoint — no module may pin its own version of a BOM-managed artifact. (We tried failOnVersionConflict() in ops.quality during verification; it fails multi-BOM builds, so the guard is the catalog plus review, not a resolution flag.)
Reproducible archives make sha256sum comparisons between CI runs meaningful — a prerequisite for any dependency-verification story later.
No secrets, no credentials, no network calls in the default build; the wrapper checksum is verified by gradle/actions/setup-gradle in CI.

Troubleshooting

KotlinJvmTarget mismatch: both the Java toolchain (25) and jvmToolchain(25) must agree; if you change one, change both.
ops.spring-application not found: includeBuild("build-logic") must precede include(...) resolution; check settings.gradle.kts.
Toolchain cannot resolve Java 25: set org.gradle.java.installations.paths or enable auto-download via the toolchain resolver plugin.

Checkpoint verification checklist

./gradlew clean check is green from a clean checkout.
./gradlew projects lists all eight modules plus build-logic.
Both ArchUnit rules pass and demonstrably fail when violated.
domain-contracts has no Spring AI, JPA, or web dependency.
CI workflow runs the same single command you ran locally.

Commit message and Git tag

1
chore: scaffold ops-agent-platform multi-module build
2

3
Gradle 9.7.1 wrapper, version catalog, four convention plugins,
4
Java 25 toolchains, JUnit 5 + JaCoCo, first ArchUnit boundary
5
rules, and CI.

git tag chapter-01-build-foundation

What comes next

Chapter 2 puts the first real behavior behind operations-simulator: the service catalog, incidents, idempotent creation, and the fault modes every later resilience test leans on.

Project State Ledger — `chapter-01-build-foundation`

Build: Gradle 9.7.1, Java 25 toolchain, in.o612.eng.opsagent group, convention plugins ops.java-library / ops.kotlin-library / ops.spring-application / ops.quality
Modules: all eight exist; four applications have main classes only
Enforced rules: contracts isolation; web↛persistence
Known limitation: Kotlin module compiles but has no MCP tools yet; Boot 4 starter names (spring-boot-starter-webmvc etc.) used throughout
Next: chapter-02-operations-simulator

JavaSpring BootKotlinTesting