profile-java-server-architecture

name

profile-java-server-architecture

description

Opt-in profile. Opinionated Java server-side architecture conventions — Gradle on its latest stable version, latest stable Spring Boot, latest Java LTS, repositories return DTOs (never JPA entities) to upper layers, internal DTOs stay internal (API layer has its own request/response DTOs), and a strict Controller/Job → Facade → Service → Repository call chain with transactions owned by the facade. Only invoke when PROJECT_BRIEF.md's `## Profiles` section lists this skill by name. Do NOT auto-invoke on arbitrary Java or Spring work.

Profile — Java Server Architecture

Opinionated conventions for Java server-side projects (typically Spring Boot backends). Apply only when PROJECT_BRIEF.md → ## Profiles lists profile-java-server-architecture.

Precedence

PROJECT_BRIEF.md > this profile > model defaults. If the brief pins specific versions or contradicts any rule below, follow the brief and surface the conflict. If the brief is silent, this profile is authoritative.

Rules

1. Build: Gradle, latest stable

• Build tool is Gradle. No Maven, no mixed builds.
• Use the latest stable Gradle release at scaffold time. Pin it in gradle/wrapper/gradle-wrapper.properties.
• Prefer the Kotlin DSL (build.gradle.kts) for new projects for better IDE support. Groovy DSL is acceptable only when maintaining existing Groovy build scripts.
• Use a Gradle version catalog (gradle/libs.versions.toml) to centralize dependency versions — no hand-pinning scattered across build.gradle.kts.
• Ship the Gradle Wrapper (./gradlew) with the project. Never require a system-installed Gradle.

2. Spring Boot: latest stable

• Use the latest stable Spring Boot release at scaffold time.
• Declare the Spring Boot plugin in build.gradle.kts; let its BOM manage transitive versions. Do not hand-pin versions of libraries Spring Boot already manages.
• Use Spring Boot autoconfiguration and conventions — do not duplicate what a starter already provides.
• Prefer spring-boot-starter-* modules over raw spring-* dependencies.

3. Java: latest LTS

• Target the latest Java LTS at scaffold time. Non-LTS JDKs are not acceptable for production projects — their security support window is too short.
• Configure the Gradle toolchain so the build is reproducible across machines:

  java {
      toolchain {
          languageVersion = JavaLanguageVersion.of(<N>)
      }
  }
  

• Use modern language features where they improve clarity: records for immutable data carriers, pattern matching for instanceof and switch, text blocks, sealed types for closed hierarchies.

4. Repositories return DTOs, not JPA entities

Repositories MUST return DTOs (or projection interfaces) to upper layers. @Entity classes never leave the repository package.

• Read methods return a DTO, a projection interface, or a collection of either.
• Write methods accept DTOs (or primitive parameters), perform entity mapping internally, and return DTOs — or nothing — on the way out.
• Enforce structurally with an ArchUnit rule (or equivalent): entity classes must not be referenced outside the repository package.
• If profile-java-database-access is also active, both profiles reinforce this rule — they do not conflict.

5. Internal DTOs stay internal — the API layer owns its own DTOs

DTOs passed between service/domain layers MUST NOT be used as REST request or response bodies. The API layer has its own request and response DTOs, and a mapper at the controller boundary.

• Internal DTOs live in a service/domain package (e.g., com.example.foo.service.dto).
• API DTOs live in an API package (com.example.foo.api.dto or a dedicated module).
• Controllers — or a dedicated mapper invoked at the controller boundary — translate between API DTOs and internal DTOs. Hand-written mappers or MapStruct are both acceptable; pick one per project and stick with it.
• Never put API-shaping annotations (@Schema, @JsonProperty, @JsonIgnore, @JsonInclude) on internal DTOs. If you are reaching for those on an internal type, you are using the wrong type.
• Enforce structurally with an ArchUnit rule: controller/REST packages must not reference internal DTO types as request or response parameters.

Rationale:

• API stability — internal model evolution must not break API contracts.
• Information hiding — prevents accidental leakage of internal fields (audit metadata, internal ids, implementation concerns).
• Versioning — API DTOs can be versioned (v1, v2) without rippling changes through the service layer.

6. Layered architecture: Controller / Job → Facade → Service → Repository

The application follows a strict layered call pattern. Every layer has a single allowed caller set.

Entry points — Controllers and Jobs

• Controllers handle HTTP transport, authentication/authorization checks, and request-DTO validation.
• Jobs are any non-HTTP entry point: scheduled tasks (@Scheduled), message/event listeners (Kafka, SQS, RabbitMQ), queue consumers, startup runners, webhooks.
• Controllers and jobs MUST call facades only — never services, never repositories.

Facades — use-case orchestration and the transaction boundary

• Facades coordinate use-case-level operations. @Transactional is declared at the facade method level — facades own the transaction boundary.
• A facade method may call other facades and/or services of its own domain.
• Facades MUST NOT call repositories directly.
• Cross-domain operations (work that touches data or actions belonging to more than one domain) are orchestrated via facade-to-facade calls. A facade never reaches into another domain's services.
• Same-domain operations (work confined to the facade's own domain) may call the services of that domain directly — no intermediate facade required.

Services — domain-operation implementers

• A service operates on one main entity / domain. It implements the domain operations that facades compose into use cases.
• Services call repositories and may call other services within the same domain.
• Services MUST NOT declare @Transactional. If a service operation needs a new or different transaction, that is a signal to move the boundary — escalate to the facade rather than annotating the service.
• Services MUST NOT be called by controllers or jobs.

Repositories — persistence only

• Repositories hold the persistence-layer calls and return DTOs / projection interfaces per rule 4.
• Repositories are called only by services.

Transaction propagation

• @Transactional on a facade method uses Spring's default propagation (REQUIRED). Nested facade calls and service calls participate in the caller's transaction.
• Declare readOnly = true on facade methods that never write — it lets Hibernate and the JDBC driver skip dirty-checking and enables query-only optimizations.
• Do not use REQUIRES_NEW casually; it breaks the caller's atomicity. Reserve it for explicit cases (audit trail writes that must survive a rollback) and document why on the annotated method.

Structural enforcement (ArchUnit or equivalent)

• Controllers and jobs may depend only on facades. They must not import service or repository types.
• Facades may not depend on repositories.
• @Transactional may appear only on facade-layer types or methods.
• Services may not be called from controller / job / rest / api packages.

Rationale

• The facade layer is the use-case boundary ("do this user intent") and therefore the right transaction boundary.
• The service layer is the domain-operation boundary ("perform this operation on this entity"). Splitting them prevents controllers from accumulating coordination logic and keeps services reusable across use cases.
• The same-domain shortcut (facade → services directly) avoids wrapper facades that add no value for single-domain operations; the cross-domain rule prevents accidental coupling between domains.

Version discovery procedure (mandatory)

When this profile is first applied (typically during scaffolding, or when the brief's stack.versions is missing a required version), the agent MUST look up current versions via WebFetch — not from training data.

Use these sources:

• Gradle latest stable — WebFetch https://services.gradle.org/versions/current. The response is JSON; extract the version field.
• Spring Boot latest stable — WebFetch https://api.spring.io/projects/spring-boot/releases. Pick the latest entry whose current is true or whose version matches the stable pattern (no -SNAPSHOT, no -M/-RC suffixes).
• Java latest LTS — WebFetch https://endoflife.date/api/java.json. Pick the latest entry where lts is true and support is still active (eol date in the future or missing).

Record each fetched version in PROJECT_BRIEF.md → frontmatter stack.versions (e.g., {java: "21", gradle: "8.14.2", spring_boot: "3.3.2"}) AND in the ## Technologies prose section. Also record the fetch date alongside the prose so the decision is auditable.

If WebFetch is not available in the agent's tool set, or every source fetch fails, the agent MUST stop and ask the user for the versions. Do NOT guess from training data and do NOT invent a date — this rule is non-negotiable.

Version handling on subsequent runs

"Latest" is a scaffold-time decision, not a runtime mandate.

1. On later develop runs, the versions recorded in stack.versions take precedence. The word "latest" in this profile is not a trigger to upgrade mid-feature.
2. Upgrades are an explicit, scoped project — never a side effect of unrelated feature work.

If the brief's stack.versions is missing the relevant tools when develop runs, the analyst must stop and run the version-discovery procedure above (or ask the user) before any implementation work proceeds.

How each role applies this profile

• Analyst — propose repository-returns-DTO shapes, separate API vs internal DTOs, mapper placement, and layer-compliant call chains (Controller/Job → Facade → Service → Repository). For cross-domain work, explicitly route via facade-to-facade. Do not propose mid-feature Gradle / Spring Boot / Java upgrades.
• Challenger — severity guide:
  • Critical: controller or job calling a repository directly; facade calling a repository directly; @Transactional declared on a service or repository; deviation from the brief's pinned Gradle / Spring Boot / Java versions; proposal mixing in Maven or a non-LTS JDK.
  • Major: controller or job calling a service directly (bypasses the facade); cross-domain work done via facade → other-domain's service (should be facade-to-facade); entity leak past the repository package; internal DTO reused as an API request/response.
• Developer — implement to all rules. For each new endpoint, create its API DTOs in the API package and place the mapper at the controller boundary. Declare @Transactional only on facade methods; mark read-only where applicable. Add or update the ArchUnit rule when introducing a new package that should be covered by a layering constraint.
• QA — test controllers through API DTOs (MockMvc, WebTestClient). Test facades as the transaction boundary (integration tests that assert commit/rollback behavior). Test services with their main-entity scope using internal DTOs. If profile-java-database-access is also active, ensure repository-layer tests assert DTO return shapes. Do not cross layer boundaries in test code.

Non-goals

• Detailed coding style (formatter, imports, naming conventions) — belongs in the brief or a style-specific profile.
• Testing framework choice (JUnit vs. Spock) — follow the brief.
• Database-access rules (N+1 avoidance, parameterized queries, Hibernate as provider) — see profile-java-database-access.
• Observability, deployment, and secrets management — captured by define-deployment at scaffold time.
• Frontend concerns — this profile covers server-side only.