Files
clean-architecture-backend-…/docs/history/plans/2026-09-23-app-bootstrap-build-composition-plan.md
T
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.

고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
  :composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
  이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
  boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
  project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
  gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
  config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
  (getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
  훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
  rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
  src/를 붙인다. notification API surface의 application-notification 소스
  루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
  건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
  폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
  registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
  써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
  env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
  verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
  check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
  operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
  다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
  capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
  docs/upgrade/2026-11-relayout.md를 더한다.

위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.

검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.

BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
2026-11-11 22:15:42 +09:00

17 KiB
Raw Blame History

기록 · 계획서 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 확인 안 함
  • 작성일: 2026-09-23
  • 요약: app-bootstrap 빌드 조립을 정리하는 실행 계획이다.
  • 현재 정본: src/bootstrap/app/README.md

App Bootstrap Build Composition — implementation plan

Design authority: the 2026-09-23 "App Bootstrap Build Composition 설계 작업 문서". Review authority: docs/reviews/2026-09-18-techlead-review/ §00, §12, §13 and docs/reviews/2026-09-23-techlead-review-application-closure.md.

This plan is the §17 deliverable. It settles the three decisions the design document deliberately left open — what "selection" is mechanically, where the contract is enforced, and what a composition module is allowed to be — and then splits the work into the task units §17 names. It does not restate the design.

0. Measured baseline

Re-measured on the current tree rather than quoted (design §15 forbids reusing an old log).

The design document's named gate is green:

./gradlew verifyCleanArchitectureDependencies :adapter:outbound:persistence-jpa:test \
  :app-bootstrap:test :app-bootstrap:architectureTest --continue      # exit 0, 0 FAILED

:app-bootstrap:runtimeClasspath resolves 33 project edges. Every optional capability is among them, including the three the earlier pass lowered to runtimeOnly:

graphql  httpclient  persistence-mongo          <- runtimeOnly, still on the classpath
fileserver  notification  cache-redis  redis-runtime
messaging-spring-boot-starter + 16 further messaging leaves

This is the design document's §2.3 claim, confirmed: runtimeOnly moved these off the compile classpath and left them in the artifact. Nothing about the shipped jar changed.

1. Decision — selection is a Gradle edge, and the repository already has one

The design document asks for a mechanism without naming one. It does not need a new one: object storage is already in the target state, and docs/capability-status.md already documents it that way — WIRED no, "The leaf is not an app-bootstrap dependency … A fork that wants it adds the edge", with integrationTestImplementation project(':adapter:outbound:objectstorage') supplying it to the lane that proves it assembles.

So the work is not to invent Build Composition. It is to move the other capabilities to the shape one capability already has.

Selection = the presence of a project dependency in app-bootstrap/build.gradle. Not a Gradle property, not a feature variant, not a capability DSL. Reasons, in the order design §9 ranks them:

  • it is the existing Gradle model, and it is already how object storage works;
  • a property would make the shipped artifact depend on how the build was invoked, so two builds of the same commit could ship different jars — the opposite of what a composition contract is for;
  • the thing a fork edits is one line in one file, which is what a template should ask of an adopter.

Rejected alternative, recorded because it is the obvious one: -PcaCapabilities=fileserver,.... It reads well and it is worse — it moves the answer to "does this build ship Fileserver?" out of the repository and into the invocation, and no test can pin an invocation.

2. Decision — the contract is enforced by the verifier that already exists

Design §7.1 requires a RED test proving an unselected capability is absent from runtimeClasspath, and design §9 forbids adding a bespoke verifier for it.

Both are satisfiable at once. ca.dependency-policy already resolves a named configuration and fails on forbidden or missing coordinates (dependencyPolicy { absent … required … }, VerifyDependencyPolicyTask, wired into check). A project dependency resolves to a real ModuleVersionIdentifier — dev.caskeleton:<project name> — so an absence on runtimeClasspath is expressible today, with no new task, no new source set and no string scanning.

// app-bootstrap/build.gradle
dependencyPolicy {
    absent 'dev.caskeleton:fileserver',
            'Fileserver is an optional capability; the minimal composition does not ship it.'
}

That is the Phase 1 RED: it fails on the current tree, because the edge is there.

Two things this deliberately does not replace:

  • the Runtime Activation tests. Design §3.1 is the whole point — absent answers "is it in the artifact", the existing OFF-state guards answer "is it assembled". Neither is evidence for the other, and the plan keeps them in different files so they cannot be confused.
  • the boot artifact evidence design §7.5 asks for. runtimeClasspath is what bootJar packages, so the two agree by construction — but "by construction" is an argument, not a measurement. One bootJar content assertion is added once, in Step 7, as a check of the argument, not per capability.

3. Decision — what a composition module may contain

A composition:<capability> module exists only when a capability genuinely spans adapters that must not depend on each other. It contains cross-adapter wiring and nothing else: no business rule, no transport surface, no settings that a single leaf could own. If a capability turns out to be self-contained after the leaf-ownership pass, no composition module is created for it — the leaf is selected directly, exactly as object storage is.

This matters because the fileserver work in the 2026-09-23 closure §3-B.5 already found that the package which looked like one cross-adapter assembly was two assemblies merged. The same question is asked before each composition module is created, not after.

Registry: each new module gets a modules.json entry with explicit allowed_dependencies. settings.gradle includes registered projects automatically, so registration is inclusion. A composition module is not a composition root: it composes a capability, it does not run.

4. Task units

Ordered. A unit is done when its own focused command is green; no unit starts before the previous one is.

# Unit Done when
1 Fileserver Build Composition RED test :app-bootstrap:verifyDependencyPolicy fails naming dev.caskeleton:fileserver, and the failure text is the contract
2 Fileserver composition extraction the 4 cross-adapter configurations left in bootstrap by closure §3-B.5 move to composition:fileserver; bootstrap's fileserver edges are gone; unit 1 is green
3 Fileserver ON/OFF regression OFF-state and ON-state tests unchanged in meaning and green, from the source set that selects the composition
4 Notification composition extraction same shape, same three units collapsed into one because the pattern is proven
5 Persistence/JPA ownership review per-file verdict against design §11 Q1–Q4, recorded; only files that answer Q1 or Q2 move
6 Messaging / Redis residual ownership broker selection becomes a build edge; Redis keeps only the two application-wide files closure §3-B.5 already justified
7 Mongo / HTTP client / GraphQL actual optionalization runtimeOnly → absent; one bootJar assertion proves the classpath argument
8 Minimal + full composition certification minimal = :app-bootstrap main; full = the app-bootstrap systemTest source set selecting every capability. No new application module unless a source set proves insufficient
9 Registry / docs / comment alignment modules.json, capability-status.md WIRED column, and the "shipped so an operator can enable it" comments in app-bootstrap/build.gradle all say the same thing
10 Focused → repository-wide gates design §15 command, then ci, dependency locks, public-path snapshot, optional-platforms

Unit 8 uses a source set rather than a new module because app-bootstrap:integrationTest already does exactly this for object storage. Design §6.2 warns against forcing sample-portfolio to carry every capability, and this avoids it without adding a module.

5. What this plan does not do

Taken from design §10, repeated here because a plan that omits them invites them:

  • no mechanical removal of every dev.caskeleton.adapter.* import; ownership is argued per file
  • no new platform layer, no new build DSL, no per-capability verifier
  • no change to provider behaviour, no feature work, no unrelated test cleanup
  • no staging, commit or push — repository policy is human-only
  • no working-tree cleanup; the tree carries 36 tracked deletions and 54 untracked additions from the previous pass, and closure §5 records how they must be committed

6. Regression guard

Design §14's list is the non-negotiable set. Each unit's focused command includes whichever of these it can break:

JPA boundary gate                     :adapter:outbound:persistence-jpa:test
Redis composition unit isolation      :adapter:outbound:cache-redis:test
app-bootstrap architecture test       :app-bootstrap:architectureTest
runtime activation OFF guards         :app-bootstrap:test, :app-bootstrap:systemTest
configuration cache                   ci/integrationCheck/releaseCheck --dry-run --configuration-cache
gRPC operation-ledger CI caller       -p optional-platforms integrationCheck

Leaf ownership already moved for Redis and Fileserver (closure §3-B.5) is a floor, not a starting point: this work extends it and must not walk it back.

7. Progress — units 1 and 2

Unit 1 is done

app-bootstrap/build.gradle declares the contract as a dependencyPolicy absence on runtimeClasspath. It was checked for vacuity before it was trusted: a temporary required on the same coordinate passed, which is what proves dev.caskeleton:fileserver is the shape a project dependency actually resolves to. Without that probe an absent rule with a misspelled coordinate would have been green from the first day and meant nothing.

Unit 2 is done except for one measured blocker

Moved, in this order, because each step unblocked the next:

  1. RuntimeProfileSnapshot → adapter:outbound:support. It was the real coupling. A capability configuration that has a production-only rule had to ask app-bootstrap what the profile was, so the configuration could not leave app-bootstrap. BOOT-002 said "one composition-root owner"; it now says one owner for the repository, which is strictly stronger and is what lets a composition module ask the question at all.
  2. composition:fileserver-platform created and registered. Named for the capability rather than the directory: :composition:fileserver resolves to dev.caskeleton:fileserver, the same coordinate as adapter:outbound:fileserver, and Gradle silently substituted the module for itself. The messaging family already prefixes its leaves for this reason.
  3. The 13 cross-adapter configurations moved, with the auto-configuration and management-context registration files that name them. StartupFailures became CapabilityStartupValidationException, the same seam the Redis and Fileserver leaf moves used.
  4. app-bootstrap's fileserver edges removed; the lanes that verify the capability select it.
  5. BOOT-007 moved to the module it governs, with allowEmptyShould(false). Left where it was it would have analysed an empty package and passed for having nothing to check — and BOOT-012 caught the rule leaving the pinned set, which is that guard working rather than an obstacle.

Result: adapter:outbound:fileserver is off the minimal runtime classpath. Project edges on :app-bootstrap:runtimeClasspath went from 33 to 32.

The blocker, measured rather than estimated. application-fileserver is still there, and not through the composition. It arrives through three leaves every application needs, because the capability's code is inside them:

leaf fileserver files
adapter:inbound:web (web.fileserver.*) 62
adapter:outbound:persistence-jpa (persistence.fileserver.*) 25
adapter:outbound:identifier 1

So Fileserver was never only "assembled by the composition root". It is embedded in required leaves, and no composition module can express selecting it out until those 88 files move to leaves of their own. The coupling was measured and is one-directional and small — web.fileserver reaches web.{core, observability, auth} nine times, and exactly one non-fileserver web class (WebModuleBoundary) reaches back — so the split is tractable. It is unit 2b, and it is the next thing to do.

The contract line stays RED. Softening it to make the gate green would record the opposite of what was measured, and design §7.1 asks for this test to be RED before the structure changes, not after it is convenient.

Verification at this point

./gradlew verifyCleanArchitectureDependencies :adapter:outbound:persistence-jpa:test \
  :app-bootstrap:test :app-bootstrap:architectureTest \
  :composition:fileserver-platform:check :adapter:outbound:support:test --continue   # green

./gradlew ci --continue          # 1,276 tasks, exactly one failure:
                                 # :app-bootstrap:verifyDependencyPolicy, the intended RED

One failing task out of 1,276, and it is the one this unit deliberately left failing. Nothing else in the repository regressed.

8. Unit 2 is complete — the Fileserver vertical slice

The blocker recorded above was right about the cause and wrong about the size. application-fileserver arrived through three required leaves, and all three turned out to be clean extractions:

Extracted Into Why it was clean
1 file — the upload identifier factory adapter:outbound:fileserver It implements one Fileserver port and nothing else. One class is why every application that needed an identifier also resolved the Fileserver use cases.
25 files + 4 migrations adapter:outbound:persistence-fileserver (new leaf) The package imported application.fileserver, JPA, Hibernate, Spring Data and JDBC — and not one type from any other persistence.* package. No seam was needed.
62 files adapter:inbound:web-fileserver (new leaf) web.fileserver imports web.{core, auth, observability} nine times; exactly one non-fileserver class referenced it back, and only in a javadoc sentence.

The web platform's module map did not move. WebStableModule still declares the twelve fileserver modules and their edges, and WebBuildModel.platformSourceRoots() now returns two roots — which is what that method's plural has meant since it was written. A second copy of the map in the second leaf would have been a second answer to "is this edge declared", and the map is the one thing a platform must not have two of.

Result: :app-bootstrap:runtimeClasspath went from 33 project edges to 31, and the contract now names the whole capability rather than the part that was easy to remove:

absent 'dev.caskeleton:fileserver'
absent 'dev.caskeleton:application-fileserver'
absent 'dev.caskeleton:web-fileserver'
absent 'dev.caskeleton:persistence-fileserver'

What the repository's own guards caught

Every move was stopped first by a guard already in the tree, and every one was the same shape — a rule still pointing at something that had moved:

  • JpaModuleBoundaryTest: "a rule about a package that does not exist passes by finding nothing"
  • ArchRuleDiscoveryContractTest (BOOT-012): a rule leaving the pinned set is a decision, not a deletion
  • verifyJpaApiSurface / verifyJpaAdopterApiSurface: surface change promoted to a review decision
  • PersistenceEntityScanCoverageTest: an opt-in package that is no longer opt-in because it is no longer here

verifyJpaAdopterApiSurface was not widened by allowlist (design §28). Its scan excludes the directory that owns the implementation; there are two such leaves now, so the exclusion was corrected, and the baseline file still governs every other module's imports.

One regression this introduced and then removed

The new web leaf first declared spring-boot-starter-webflux. The web leaf's own build file says in a comment why it declares spring-webflux instead: the starter puts reactor-netty — a second embedded server — on the runtime classpath of an application that already has Tomcat. The new leaf now matches, and the lock files record the difference.

Verification

./gradlew ci verifyDependencyLocks --continue      # exit 0, 0 FAILED

Repository-wide, everything green, including :app-bootstrap:verifyDependencyPolicy — the RED that opened this unit.

Next

Unit 4, the Notification composition. Unit 3's ON/OFF regressions are covered by the tests that moved with the code (FileserverRuntimeAssemblyTest, FileserverPlatformAutoConfigurationTest in the composition module, FileserverCompositionIntegrationTest in app-bootstrap's integration lane) and all are green in the run above.