문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.
고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
(sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
(유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.
위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
샘플 경로는 이력이라 두었다.
검증(desktop, 트리 0525e14e, ~/t1-layout-logs/):
- ./gradlew :ci --warning-mode=fail rc=0 (502 executed, 83 from cache)
- :verifyStrictLaneStages --dry-run rc=0
- :app-bootstrap:documentContractTest rc=0
- -p build-logic check rc=0
- :verifyDependencyLocks rc=0
- python3 scripts/check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.2
BREAKING CHANGE: src/sample-portfolio, src/Dockerfile.sample, 샘플 태스크와 job이 없어진다. 샘플을 고쳐 쓰던 파생 서비스는 병합 때 수정 대 삭제 충돌이 난다. docs/upgrade/2026-11-maturity-review.md B-49.
8.3 KiB
8.3 KiB
app-bootstrap — application entry point & composition root
Registered identity
- Module ID:
app-bootstrap - Gradle path:
:app-bootstrap - Focused test (derived from Gradle path):
./gradlew :app-bootstrap:test --console=plain - Runtime baseline: Java 21; repository framework baseline: Spring Boot 4.0.0.
- Registry SSOT:
src/config/architecture/modules.json.
Package root: dev.caskeleton.bootstrap.
Responsibility
- Spring Boot entrypoint (
CaSkeletonApplication). - Runtime settings and logging bootstrap.
- Final cross-module wiring.
- Architecture tests that inspect all modules.
Allowed
- Runtime leaves explicitly declared by this module's Gradle dependencies and permitted by the architecture registry. The resolved Gradle runtime graph is the runtime SSOT; do not duplicate a membership list in metadata.
- Spring Boot startup/runtime dependencies.
- ArchUnit in tests.
Forbidden
- Concrete business policy.
- Controllers, use cases, repository adapters, or mappers authored directly under bootstrap.
- Settings classes that implement business logic.
- Implementing an
application-coreordomain-coreport. A class that implements one is an outbound adapter and belongs in anadapter/outbound/*leaf, however its dependencies are configured —CompositionRootBoundaryArchitectureTestenforces this, with no exceptions. - Raising a startup failure with
throw new IllegalStateException(...). UseStartupFailures(adapter:outbound:support, packagesupport.startup:envValidation/profileMismatch/requiredAdapterDisabled/migrationFailed), so the failure carries its sysexits exit code and structured log fields —StartupFailureContractArchitectureTestenforces this. - Answering "is this production?" locally.
dev.caskeleton.shared.runtime.RuntimeEnvironmentowns the profile vocabulary for the whole repository. - Depending on
org.testcontainersfromsrc/test. Real-service tests belong tosrc/integrationTest; seedocs/testing/TESTING_STRATEGY.md.
Package layout
The rules below exist because their absence is what produced the drift this module was reviewed for
(docs/reviews/2026-09-07-app-bootstrap-module-code-review.md). Half the
capabilities lived under autoconfigure/ and half at the package root; Settings classes were split
between a settings/ package and their feature packages with no stated rule; and the same
decomposition problem was solved two different ways in the same leaf — Notification as nine focused
configurations, Redis as one 376-line class.
- A capability's assembly lives in the capability's own module, registered by that module's
AutoConfiguration.imports, with its settings in the module'sconfig/module-defaults/*.yml. JPA (startup guards, Flyway strategy, lock decorator, readiness and full-off handling inJpaActivationEnvironmentPostProcessor) isadapter:outbound:persistence-jpa; Redis (readiness) isadapter:outbound:cache-redis; notification iscomposition:notification-platform. Every capability is a commentedruntimeOnlyline inbuild.gradle; the default composition is web, observability, the cores, support and identifier. This leaf keeps no list of capabilities: no switch registry, no cross-capability dependency validator, no activation endpoint. Component scan coversdev.caskeleton.bootstraponly; web (WebAdapterAutoConfiguration,WebSecurityAutoConfiguration,WebMethodSecurityAutoConfiguration) and support (OutboundSupportConfig) arrive through their ownAutoConfiguration.imports. What stays inautoconfigure/<name>/is application composition every application needs:common(the clock). The outbox relay, the idempotency executor and the durable operations (use cases and/operationsendpoints, 07-08) arecomposition:outbox-relay,composition:idempotencyandcomposition:durable-operation, selected by oneruntimeOnlyline each and building nothing until their ports exist. A capability's role→permission mapping ships in its ownconfig/module-defaultsfile, not inconfig/security.yml. The runtime wiring every composition root needs — tracing, the metrics contract filters, domain-context propagation, user-principal pseudonymization (PrivacySettings) and the actuator chain — iscomposition:service-runtime. <Capability>Settingslives beside its capability, not insettings/. Thesettings/package holds only settings that belong to no capability —BootstrapSettings,RuntimeSafetySettings— bound strictly withStrictSettingsBinder, never scanned. Logging has no settings record:logback-spring.xmlreadsapp.logging.*itself andLoggingConfigurationRulerefuses values Logback cannot use.runtime/holds guards about the application itself — secrets, numeric bounds, error-detail exposure, multi-instance coordination, the runtime-profile check (RuntimeEnvironmentProfileValidator). A guard about a capability's settings (the JPA OSIV/DDL/pool/TLS/vendor guards, the Mongo connection-source rule, the GraphQL deployment-mode rule) ships with that capability's module, so it exists exactly when the capability does.- The startup failure vocabulary lives in
adapter:outbound:support(support.startup: phases, error codes, exceptions,StartupFailures,StartupValidationContext,StartupOrder,ReadinessGroup,RuntimeWarnings), so capability modules fail the same way without depending on this leaf.runtime/startup/keeps onlyStartupFailureExceptionReporter. - An environment-only guard is a
StartupRulebean (support.startup): it returns violations, and the oneStartupRuleRunnerraises them before any other singleton exists (declare it with astatic@Beanmethod that takes only theEnvironment, the bean factory or anObjectProviderof staticRequiredProductionSecrets; in every profile the runner creates each rule and eachRequiredProductionSecretsbefore any rule runs, and fails the boot naming any other bean one of them creates, and naming any whose runtime class has an@Value/@Autowired/@Inject/@Resourcemember, a@PostConstruct/@PreDestroycallback or a@ConfigurationPropertiesbinding — those are created before the post-processors and would stay unset). A guard that needs another bean stays a bean. A capability's production secrets are the capability's: its module contributes aRequiredProductionSecretsbean, andSecretSourceValidatorchecks the names without knowing which roles exist.
Decomposition threshold
State it rather than leaving it to taste, because "it felt long enough" is what produced two different answers for the same question.
- One
@Configurationholds one assembly concern. Split when it passes roughly eight@Beanmethods, or as soon as it assembles two unrelated port families — whichever comes first. - One
@ConfigurationPropertiesclass owns one capability namespace. - A capability that needs more than one configuration gets a root class holding its
enabledcondition,@EnableConfigurationProperties, and an@Importof the per-concern classes. Scan nothing:@Importfrom a gated root is what keepsenabled=falseload-bearing rather than advisory.cache-redis'scapability/RedisCapabilityConfigis the reference example. Optional adapter capabilities that own reusable Spring composition publish their own root instead. Notification usesadapter:outbound:notification'sNotificationPlatformAutoConfigurationpluscomposition:notification-platform'sNotificationApplicationCompositionAutoConfiguration; JPA uses the package-privatePersistenceJpaAutoConfiguration,PersistenceJpaRuntimeConfigandstartup.JpaStartupAutoConfigurationfromadapter:outbound:persistence-jpa, which is not in the default composition (// runtimeOnly project(':adapter:outbound:persistence-jpa')inbuild.gradle). Mongo follows the same rule: the persistence-mongo leaf owns MongoRootAutoConfiguration and its internal health bridge; bootstrap owns no Mongo-specific production health configuration. - Shared helpers of a split capability get their own type named for what they are, not a
*Utilbucket —cache-redis'scapability/RedisKeysis the reference.
Test
cd src
./gradlew :app-bootstrap:test
./gradlew verifyCleanArchitectureDependencies