donghyeon.kang/clean-architecture-backend-template

Files

T

DongHyeonkaandClaude Opus 5 0e61f86eb5 feat(jpa): implement the JPA relational persistence platform

Implements the Stable and Experimental JPA persistence platform designs
against real PostgreSQL, adapted to this repository's fail-closed 19-leaf
registry.

The design models the platform as 25 Gradle projects. `src/settings.gradle`
throws unless the registry holds exactly 19 leaves, so the plan's modules
become packages inside `:adapter:outbound:persistence-jpa` (starter in
`:app-bootstrap`, testkit in its own source set). The full mapping, the
renames this repository's naming gate required, and every deliberate
substitution are recorded in `docs/jpa/repository-adaptation.md`.

Seven Docker-backed lanes replace the plan's seven JVM test suites. Each
fails closed: a lane that discovers nothing, or a container that cannot
start, is an error rather than a skip.

Three defects the contracts found against a real server:

- `CommitFailureClassifier` treated only SQLSTATE 40003, class 08, and
  transport breaks as completion-unknown. A backend terminated mid-commit
  reports 57P01, and the commit record may already be in the WAL — so a
  possibly-committed transaction could be re-run. 57P01/57P02/57P03 now
  classify as completion-unknown.
- `SchemaTenantMigrationOrchestrator` recorded `MigrateResult`'s target
  version, which is empty for a tenant already current, reporting migrated
  tenants as unmigrated during a partial rollout. It now reads the applied
  version back from the tenant's schema history.
- `JpaStreamExecutor` checked only the declared return type for reactive
  publishers, and `RegisteredPostgreSqlCopyLoader` passed the COPY timeout
  to `SET`, which is parsed before parameter binding.

`JpaModuleBoundaryTest` enforces the plan's module map as package rules;
`verifyCleanArchitectureDependencies` governs edges between leaves and
cannot see these. Its first assertion is that the import is non-empty,
because every rule under it is a `noClasses()` rule and would pass
vacuously on an empty import.

Verified: 128 container tests across all seven lanes, 1183 unit tests,
`:adapter:outbound:persistence-jpa:check`, `:app-bootstrap:check`,
`verifyCleanArchitectureDependencies`, `verifyOneTypePerFile`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-14 14:06:18 +09:00

2.1 KiB

Raw Blame History

Experimental Promotion Checklist

ExperimentalPromotionGate evaluates this checklist. Every technical item, then the ADR.

Technical evidence

Compatibility — the Stable contract suite passes on the experimental target, twice, on two supported patch releases. One passing run is a coincidence.
Security — for tenancy features, cross-tenant read and write are both proven impossible, including through native SQL, bulk DML, getReference, and the second-level cache. A filter that covers only entity queries covers none of those.
Failure — connection reuse does not leak tenant context; a failover does not silently route a read-after-write to a stale replica; the commit-ambiguity scenarios still behave.
Migration — per-tenant migration is resumable after a partial failure, and rate-limited. With one schema per tenant, a run is N independent migrations and "it failed" is not an answer.
Performance — pool capacity, replica lag under load, and per-tenant memory are measured, not estimated. Database-per-tenant fails as a sum, not as an individual pool.

Decision

Reviewed ADR — recording what is being promised, the operational burden it carries, and what would cause it to be withdrawn.

The ADR is not a formality. The technical suites establish that something works; the ADR records that the platform should promise it, which is a different question with a different cost.

What does not count as evidence

The version being generally available.
The feature working in one environment.
A passing suite that skipped because Docker was unavailable.
A green lane whose assertions were relaxed to make it pass.

Outcomes

Decision	Meaning
`BLOCKED_TECHNICAL`	at least one suite has not passed
`BLOCKED_MISSING_ADR`	evidence is complete; no reviewed decision exists
`ELIGIBLE_FOR_STABLE_REVIEW`	both; Stable review may begin

The two blocked states are distinct because they need different work: one needs evidence, the other needs a decision.

2.1 KiB Raw Blame History