05 — Project architecture, build and engineering practices

Historical. This research predates the implementation and is kept as written; for what the library does today, see features, architecture and benchmarks.

Phase 1 research. Status: proposal, nothing here is implemented yet. Spanish version: ../../es/research/05-project-architecture.md

This document covers the shape of the repository: which Gradle modules exist and what each one does, how the build is organised, how JPMS fits in, the quality tooling, how the bilingual documentation is produced, and how we version and protect the public API. Topics such as the annotation-processing mechanism, concurrency internals and the annotation API itself are covered by sibling research documents. This document only notes where they affect the module layout.

TL;DR

1. Module layout

1.1 What Resilience4j does, and what users dislike

Resilience4j 2.x publishes one artifact per pattern: resilience4j-circuitbreaker, -ratelimiter, -bulkhead, -retry, -timelimiter, -cache. It also publishes resilience4j-core, the aggregator resilience4j-all (which holds the Decorators builder), a resilience4j-bom, and a long tail of integrations (-micrometer, -reactor, -rxjava3, -kotlin, -spring-boot3, -spring6, -vertx, -feign, -retrofit, …) (README, BOM on Central).

Pain points that matter for our design:

1. Too many coordinates for a simple use case. A typical service ends up declaring 4–6 artifacts, or pulls -all, which defeats the modularity. Every pattern artifact depends on resilience4j-core anyway, so the split saves very little bytecode.
2. Annotations are tied to Spring AOP. @CircuitBreaker, @Retry and the rest live in resilience4j-annotations, but they only do something through the Spring (or Micronaut) aspect modules. Plain-Java users get no annotation support. This is exactly the gap this project targets.
3. Composition lives in a different artifact (Decorators in -all) from the patterns it composes.
4. Version alignment across many artifacts forces users onto the BOM.

Lesson: split by dependency boundary (does this code pull a third-party library, or run at a different time, such as compile time vs. runtime?), never by feature.

1.2 Proposed modules

All directory names are single words. Published artifactIds use the resilience4cata- prefix so they stay unambiguous on Maven Central (resilience4cata-core). In settings.gradle.kts the Gradle project stays :core, and the prefix is applied in the publishing convention plugin.

Notes on names:

• Avoid test as a project name. gradle test and :test already refer to the test task, so a project named test reads as :test:test and makes task selection confusing. testkit is unambiguous. JUnit, Micrometer and Gradle itself use the same name for this purpose.
• Name integration modules after what they integrate (micrometer, later opentelemetry), not after a generic concept (metrics). That keeps the one-word rule as integrations grow.
• Possible later modules, all single words: opentelemetry, reactor, kotlin, spring, quarkus (out of scope for now).

1.3 Should annotations be separate from core?

Both options are viable. This is a cheap decision to revisit before 1.0.

• Separate (recommended). core stays a pure programmatic library, usable with no annotations at all, the same way Failsafe is used. The processor depends only on the tiny annotations jar. If the API-design research settles on CLASS retention for codegen-only use, users can put annotations on compileOnly. The cost is one more coordinate, which the BOM hides.
• Merged. The user needs only core + processor. The cost is that the processor's processor path drags in all of core, and the annotation package becomes part of the runtime module's API surface.

Either way, packages must not be split between jars (JPMS forbids it). Annotations go in …​.annotation, the engine in …​.core and sub-packages.

1.4 Dependency graph

graph TD
  annotations["annotations<br/>(no deps)"]
  core["core<br/>(no deps)"]
  processor["processor"] -->|compile| annotations
  config --> core
  micrometer --> core
  micrometer -.-> mm[(micrometer-core)]
  testkit --> core
  bom -.constraints.-> annotations & core & processor & config & micrometer & testkit
  stress --> core
  benchmark --> core
  benchmark --> processor
  benchmark -.-> r4j[(resilience4j)]
  examples --> annotations
  examples --> core
  examples -->|annotationProcessor| processor

Rules, enforced by ArchUnit and by the build (see §4):

• core and annotations have no project or external dependencies.
• No module depends on processor at runtime. It is only ever on an annotationProcessor configuration.
• Code generated by processor depends only on core's exported API, plus annotations when retention is RUNTIME. That is the contract between the processor and the runtime. It should live in a dedicated exported package (for example …​.core.spi.generated) so it can evolve deliberately.
• Integrations (config, micrometer, …) depend on core, never on each other.

What a user writes:

dependencies {
    implementation(platform("io.github.<ns>:resilience4cata-bom:0.1.0"))
    implementation("io.github.<ns>:resilience4cata-core")
    implementation("io.github.<ns>:resilience4cata-annotations")
    annotationProcessor("io.github.<ns>:resilience4cata-processor")
}

1.5 Is "zero external dependencies in core" feasible?

Yes. Everything a resilience runtime needs is in the JDK 21 platform:

The only dependency worth considering is JSpecify (org.jspecify:jspecify). It contains annotations only, has no transitive dependencies, is about 4 KB, and is now used by Spring Framework 7 and Guava (jspecify.dev). Two options:

• compileOnly + requires static org.jspecify. Strictly zero runtime deps, but Kotlin consumers and IDEs lose nullness information unless they add the jar themselves.
• api + requires transitive org.jspecify. One tiny jar, full nullness information for consumers.

Recommendation: api, documented as "zero dependencies except the JSpecify annotations". This is what the Java ecosystem converged on in 2025. Keep the processor dependency-free too: avoid JavaPoet, or shade it. Several popular processors (Dagger, AutoValue) ship different JavaPoet versions on the same processor path, and conflicts there are painful.

2. Gradle (Kotlin DSL) for a multi-module library, 2025–2026

2.1 Repository layout

resilience4cata/
├── settings.gradle.kts
├── gradle.properties
├── gradle/
│   ├── libs.versions.toml
│   └── wrapper/
├── build-logic/                 # included build, NOT a subproject
│   ├── settings.gradle.kts
│   ├── build.gradle.kts         # `kotlin-dsl` plugin
│   └── src/main/kotlin/
│       ├── r4c.java-library.gradle.kts
│       ├── r4c.published.gradle.kts
│       ├── r4c.quality.gradle.kts
│       └── r4c.benchmark.gradle.kts
├── annotations/ core/ processor/ config/ micrometer/ testkit/ bom/
├── stress/ benchmark/ examples/
└── docs/                        # not part of the Gradle build

build-logic is the conventional name for the included build. It is not a subproject and is never published, but it does contain a hyphen. If the one-word rule should apply there as well, conventions is a clean alternative. The Gradle docs use build-logic in their samples (sharing build logic).

2.2 Settings

// settings.gradle.kts
pluginManagement {
    includeBuild("build-logic")
}
plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version "<latest>"
}
dependencyResolutionManagement {
    repositoriesMode = RepositoriesMode.FAIL_ON_PROJECT_REPOS
    repositories { mavenCentral() }
}
enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")
rootProject.name = "resilience4cata"
include("annotations", "core", "processor", "config", "micrometer",
        "testkit", "bom", "stress", "benchmark", "examples")

2.3 Convention plugins (no allprojects {} / subprojects {})

Gradle discourages cross-project configuration because it breaks project isolation and the configuration cache. Each module applies the conventions it needs instead (Gradle best practices, structuring builds):

// build-logic/src/main/kotlin/r4c.java-library.gradle.kts
plugins { `java-library` }

java {
    toolchain { languageVersion = JavaLanguageVersion.of(21) }
    withSourcesJar(); withJavadocJar()
}
tasks.withType<JavaCompile>().configureEach {
    options.release = 21
    options.compilerArgs.addAll(listOf("-Xlint:all", "-Werror", "-parameters"))
}
tasks.withType<Test>().configureEach { useJUnitPlatform() }

// core/build.gradle.kts
plugins {
    id("r4c.java-library")
    id("r4c.published")
    id("r4c.quality")
}
// no dependencies block: that's the point

Inside a precompiled script plugin, read the version catalog via the<VersionCatalogsExtension>().named("libs"), or use the common workaround that exposes libs type-safe accessors to build-logic.

2.4 Version catalog

gradle/libs.versions.toml is the single source of versions for libraries and plugins (docs). Sketch:

[versions]
junit = "6.0.+"          # pin exact in reality
assertj = "3.27.+"
jmh = "1.37"
errorprone = "2.+"
nullaway = "0.12.+"
jspecify = "1.0.0"
resilience4j = "2.3.0"

[libraries]
jspecify = { module = "org.jspecify:jspecify", version.ref = "jspecify" }
junit-bom = { module = "org.junit:junit-bom", version.ref = "junit" }
assertj = { module = "org.assertj:assertj-core", version.ref = "assertj" }
resilience4j-bom = { module = "io.github.resilience4j:resilience4j-bom", version.ref = "resilience4j" }

[plugins]
jmh = { id = "me.champeau.jmh", version = "0.7.2" }
maven-publish = { id = "com.vanniktech.maven.publish", version = "0.34.0" }
spotless = { id = "com.diffplug.spotless", version = "<latest>" }
errorprone = { id = "net.ltgt.errorprone", version = "<latest>" }
japicmp = { id = "me.champeau.gradle.japicmp", version = "<latest>" }

(Versions are illustrative. Pin exact versions when the build is written, and let Renovate or Dependabot keep them fresh.)

2.5 Toolchains and multi-JDK testing

• Compile with toolchain 21 and options.release = 21. release guarantees we never call an API newer than 21, even if the toolchain is newer. Toolchains auto-provision through the foojay resolver (toolchains).
• Test against other JDKs without recompiling by overriding the test launcher:

val testJdk = providers.gradleProperty("testJdk").map(String::toInt)
tasks.withType<Test>().configureEach {
    javaLauncher = testJdk.flatMap { v ->
        javaToolchains.launcherFor { languageVersion = JavaLanguageVersion.of(v) }
    }.orElse(javaToolchains.launcherFor(java.toolchain))
}

CI then runs ./gradlew check -PtestJdk=25. This catches real runtime differences, such as JDK 24's virtual-thread pinning change (JEP 491) and newer JIT behaviour.

2.6 Configuration cache, build cache, parallelism

Gradle 9 made the configuration cache the preferred execution mode, and it is planned as the default in Gradle 10 (9.0 release notes). Gradle 9.1 added a read-only mode for CI (9.1 notes). Start with it on from day 1. Retrofitting it is much harder.

# gradle.properties
org.gradle.configuration-cache=true
org.gradle.configuration-cache.problems=fail
org.gradle.caching=true
org.gradle.parallel=true

All plugins chosen here support the configuration cache. vanniktech added publishing support in 0.34.0.

2.7 Testing the annotation processor

Three layers:

1. Unit-level compile tests. Use Google compile-testing (Compiler.javac().withProcessors(new Processor()).compile(source), then assertThat(compilation).succeeded() / .hadErrorContaining(...) / .generatedSourceFile(...)). It is framework-agnostic and works from JUnit Jupiter. Only its CompilationRule is JUnit 4-specific. The alternative is a 50-line in-house harness over javax.tools.JavaCompiler + an in-memory JavaFileManager, which avoids the Guava/Truth dependency (test scope only, so this matters little). Test diagnostics as carefully as the happy path: invalid configuration must fail at compile time with a precise message on the offending element. That is a selling point over runtime-only validation.
2. End-to-end. The examples module (and the processor's own src/integrationTest) is compiled with the real processor on the processor path. Its tests execute the generated code.
3. Gradle integration. The Gradle TestKit is meant for testing Gradle plugins. We only need it if we ever ship a Gradle plugin. For the processor, use it narrowly to verify incremental annotation processing: the processor must declare itself in META-INF/gradle/incremental.annotation.processors (isolating if each generated file comes from exactly one annotated type, aggregating otherwise). Otherwise every user build loses incremental compilation (docs). A small TestKit test can assert that touching one source file does not trigger a full recompile.

2.8 JMH

Use me.champeau.jmh (0.7.2 on the Plugin Portal at the time of writing) in benchmark. Practices:

• Benchmarks live in src/jmh/java. Keep them out of check because they are slow. Run them on demand and in a scheduled CI job on a dedicated runner, not on shared GitHub runners, whose noise makes their numbers unreliable.
• Compare like for like: same policy configurations in us and in Resilience4j, plus a no-policy baseline. Report thrpt and avgt with -prof gc (allocation rate per op is a headline metric), at 1, 4 and N threads (@Threads, @Group for mixed read/write contention).
• Publish raw JSON results (resultFormat = "JSON") and render them in the docs.

2.9 Publishing to Maven Central

• Sonatype shut down OSSRH on 30 June 2025. New publishing goes through the Central Portal (central.sonatype.com) (Sonatype notice).
• Use com.vanniktech.maven.publish (0.34.0 or later). It targets the Central Portal, generates the POM metadata Central requires (name, description, URL, license, developers, SCM), adds sources/javadoc jars, signs, and supports the configuration cache (releases).

// build-logic/src/main/kotlin/r4c.published.gradle.kts
plugins { id("com.vanniktech.maven.publish") }
mavenPublishing {
    publishToMavenCentral(automaticRelease = false)
    signAllPublications()
    coordinates("io.github.<ns>", "resilience4cata-${project.name}", version.toString())
    pom { /* name, description, url, licenses, developers, scm */ }
}

• Namespace: verify io.github.<github-user> (instant through GitHub) or a domain you own via DNS TXT record. Choose before the first release, because it is permanent.
• Signing in CI: pass ORG_GRADLE_PROJECT_signingInMemoryKey, …KeyPassword, ORG_GRADLE_PROJECT_mavenCentralUsername and …Password (a Portal user token) as GitHub secrets. No keyring files.
• BOM: the bom module applies java-platform and declares api(project(":core")) and the other published modules as constraints. Gradle module metadata (.module) is published alongside the POM.
• Release workflow: tag vX.Y.Z, then CI publishes, then a manual "Publish" click in the Portal at first (automaticRelease = false). Switch to automatic once the pipeline is trusted.

3. JPMS

3.1 One module-info.java per published module

// core/src/main/java/module-info.java
module io.github.ns.resilience4cata.core {
    requires static jdk.jfr;
    requires transitive org.jspecify;           // if JSpecify is `api`
    exports io.github.ns.resilience4cata.core;
    exports io.github.ns.resilience4cata.core.spi;
    exports io.github.ns.resilience4cata.core.spi.generated; // contract for generated code
    // ...core.internal is NOT exported
    uses io.github.ns.resilience4cata.core.spi.EventListenerProvider;
}

// processor/src/main/java/module-info.java
module io.github.ns.resilience4cata.processor {
    requires java.compiler;
    requires io.github.ns.resilience4cata.annotations;
    provides javax.annotation.processing.Processor
        with io.github.ns.resilience4cata.processor.ResilienceProcessor;
}

Also ship META-INF/services/javax.annotation.processing.Processor in processor. Most builds (Gradle, Maven, IDEs) put processors on a classpath-style processor path, where provides is ignored and the service file is what counts.

Benefits: real encapsulation of internal packages (stronger than naming conventions), jlink compatibility, and an ArchUnit-like guarantee checked by javac itself. Gradle infers the module path automatically when a module-info.java is present (Java modules in Gradle).

3.2 How annotation processors interact with JPMS

• The processor runs at compile time in the user's compiler, from the processor path (-processorpath) or the processor module path (--processor-module-path). It is never on the user's runtime module path. In Gradle it goes on the annotationProcessor configuration.
• Generated code lives in the user's module and packages. Filer.createSourceFile writes into the module being compiled. So the user's module-info.java must requires io.github.ns.resilience4cata.core (and …annotations when retention is RUNTIME). Document this, and have the processor emit a clear error when a module is being compiled (Elements.getModuleOf(...) is not unnamed) and the required module is missing from its module-info.
• Codegen needs no opens. Generated classes sit in the same package as the annotated class and call it directly, with no deep reflection. Reflection or bytecode-based approaches do require the user to opens packages or hand over a MethodHandles.Lookup. That is another argument for APT, which the mechanism research covers in depth.
• Split packages are forbidden. That is why annotations, core and generated code each need distinct packages. Generated code shares a package with user code, and that is fine because both are in the user's module.
• Tests: whitebox unit tests run patched into the module (Gradle handles --patch-module). Blackbox tests can go in a separate source set with their own module-info.java to test exactly what consumers see.

4. Quality tooling

CI sketch

# .github/workflows/ci.yml (illustrative)
jobs:
  build:
    strategy:
      matrix:
        test-jdk: [21, 25]
        os: [ubuntu-latest]
        include:
          - { test-jdk: 25, os: windows-latest }
          - { test-jdk: 25, os: macos-latest }
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with: { distribution: temurin, java-version: "21\n${{ matrix.test-jdk }}" }
      - uses: gradle/actions/setup-gradle@v4    # caching + wrapper validation
      - run: ./gradlew check -PtestJdk=${{ matrix.test-jdk }}

Further jobs: japicmp (on PRs, from 1.0 onward), nightly stress + benchmark (dedicated runner), release on tags, and the Gradle dependency-submission action for Dependabot alerts. Also consider JDK early-access builds (26-ea) as continue-on-error.

Supported versions: 21 and 25 are both LTS. 21 is the baseline. 25 is the forward-compatibility target.

5. Documentation module

5.1 Current state

The repo already contains docs/ with a Docsify v4 shell (index.html, README.md, .nojekyll). It is ready for GitHub Pages and has no build step. Docsify renders Markdown in the browser at view time.

5.2 Options compared

5.3 Recommendation

1. docs is not a Gradle module. It has no Java sources and nothing for Gradle to compile or publish. Making it a Gradle project would only add configuration time. Keep docs/ as a plain directory. It is still a "module" in the IntelliJ sense (docs.iml), which is fine. The only Gradle touch-points are tasks in other modules that feed the site: an aggregated javadoc copied into docs/api/ at release time, and benchmark JSON results.
2. Source layout: language first, identical structure under each locale.

docs/
├── index.html            # Docsify shell
├── README.md             # landing page / language chooser
├── _navbar.md            # EN | ES switcher
├── en/
│   ├── README.md
│   ├── _sidebar.md
│   ├── guide/ …
│   └── research/05-project-architecture.md
└── es/
    ├── README.md
    ├── _sidebar.md
    ├── guide/ …
    └── research/05-project-architecture.md

3. Keep Docsify for phase 1, since it already exists and needs no build. Keep the Markdown tool-neutral: standard CommonMark/GFM plus Mermaid fences, no Docsify-only syntax. Then a later move to Zensical, Docusaurus or Starlight is a config change, not a rewrite. Re-evaluate at 1.0, when versioned docs become necessary.
4. Translation discipline: English is the source of truth. Every PR touching docs/en/** must touch docs/es/**, or carry a translation-pending label. A tiny CI script can check that both trees contain the same file set. Code and identifiers stay in English in both languages.

6. Versioning, API stability and compatibility checks

6.1 Versioning

• SemVer. 0.y.z while incubating, where breaking changes are allowed on minor bumps and listed in the changelog. 1.0.0 comes once the annotation API and the generated-code contract are stable.
• A single version for all modules (the BOM implies it). Keep it in gradle.properties (version=0.1.0-SNAPSHOT).
• Write CHANGELOG.md in "Keep a Changelog" style. Release notes are bilingual on the docs site; English alone is fine in the changelog.

6.2 Stability markers

Define our own markers in annotations, so no API Guardian dependency is needed (JUnit uses @API(status = EXPERIMENTAL) from apiguardian, which would be an extra dependency):

@Documented
@Retention(RetentionPolicy.CLASS)
@Target({TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE, ANNOTATION_TYPE})
public @interface Experimental { String since() default ""; }

@Documented
@Retention(RetentionPolicy.CLASS)
@Target({TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE})
public @interface Internal { }

• @Experimental: public but may change in any minor release, and excluded from compatibility checks.
• @Internal + …internal packages (not exported by JPMS): never part of the API. They exist only for cross-package needs within our modules.
• The generated-code contract (core.spi.generated) is special. Code compiled by processor version N must keep working on core N. Document the rule "processor and core versions must match" and enforce it: generated code can embed the processor version, and core can check it once at class-init and fail fast with a clear message. The BOM makes matching easy.

6.3 Compatibility checks

Plan: wire japicmp in the r4c.published convention as part of check. Keep it informational in 0.x, and failing from 1.0 onward for every published module except processor. For the processor, the "API" is the annotations plus the generated code, which examples tests cover.

7. Open questions for the other research tracks

1. Annotation retention (CLASS vs. RUNTIME) determines whether annotations can be compileOnly, and whether it must be merged with core (§1.3).
2. If the mechanism research picks a runtime fallback (proxies or bytecode), it needs a separate module (for example proxy or agent) so that core stays dependency-free and codegen-only users don't pay for it.
3. External config format: will Properties + env be enough for config, or will users expect YAML? Anything beyond Properties means an optional dependency, so a separate module or an SPI.
4. Group id / namespace on Central (io.github.<user> vs. a domain) and the root Java package / JPMS module name.

Sources

• Resilience4j repository and README: https://github.com/resilience4j/resilience4j
• Resilience4j BOM on Central: https://central.sonatype.com/artifact/io.github.resilience4j/resilience4j-bom
• Gradle 9.0 release notes (configuration cache preferred): https://docs.gradle.org/9.0.0/release-notes.html
• Gradle 9.1 release notes (read-only configuration cache): https://docs.gradle.org/9.1.0/release-notes.html
• Gradle: sharing build logic / convention plugins: https://docs.gradle.org/current/userguide/sharing_build_logic_between_subprojects.html
• Gradle best practices: https://docs.gradle.org/current/userguide/best_practices.html
• Gradle version catalogs: https://docs.gradle.org/current/userguide/version_catalogs.html
• Gradle toolchains: https://docs.gradle.org/current/userguide/toolchains.html
• Gradle incremental annotation processing: https://docs.gradle.org/current/userguide/java_plugin.html#sec:incremental_annotation_processing
• Gradle Java modules: https://docs.gradle.org/current/userguide/java_library_plugin.html#sec:java_library_modular
• Gradle TestKit: https://docs.gradle.org/current/userguide/test_kit.html
• Google compile-testing: https://github.com/google/compile-testing
• JMH Gradle plugin: https://github.com/melix/jmh-gradle-plugin, https://plugins.gradle.org/plugin/me.champeau.jmh
• vanniktech gradle-maven-publish-plugin: https://github.com/vanniktech/gradle-maven-publish-plugin
• Sonatype OSSRH sunset: https://central.sonatype.org/news/20250326_ossrh_sunset/
• JSpecify: https://jspecify.dev/
• NullAway JSpecify support: https://github.com/uber/NullAway/wiki/JSpecify-Support
• JUnit 6 announcement (InfoQ): https://www.infoq.com/news/2025/10/junit6-java17-kotlin
• jqwik and release notes: https://jqwik.net/, https://jqwik.net/release-notes.html
• jcstress: https://github.com/openjdk/jcstress
• ArchUnit: https://www.archunit.org/
• JEP 491 (virtual threads without pinning): https://openjdk.org/jeps/491
• Material for MkDocs maintenance mode: https://duerrenberger.dev/blog/2025/11/06/material-for-mkdocs-is-no-more-long-live-zensical, https://github.com/squidfunk/mkdocs-material/issues/8523
• Multi-language docs with Docsify: https://evilmartians.com/chronicles/easy-multi-language-multi-version-documentation-with-docsify-git-and-github-actions, https://github.com/palkan/docsify-namespaced
• japicmp: https://siom79.github.io/japicmp/
• Revapi: https://revapi.org/