# app-bootstrap — 애플리케이션 진입점과 조립 루트 ## 등록 정보 - 모듈 ID: `app-bootstrap` - Gradle 경로: `:app-bootstrap` - 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :app-bootstrap:test --console=plain` - 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `gradle/libs.versions.toml`이 정한다. - registry 정본: `gradle/modules.json`. 패키지 루트: `dev.caskeleton.bootstrap`. ## 책임 - Spring Boot 진입점(`CaSkeletonApplication`). - 런타임 설정과 로깅 시작. - 모듈을 가로지르는 마지막 배선. - 모든 모듈을 들여다보는 아키텍처 시험. ## 허용 - 이 모듈의 Gradle 의존성이 분명히 선언하고 아키텍처 registry가 허용한 런타임 leaf. 해석된 Gradle runtime 그래프가 런타임의 정본이다. 구성원 목록을 metadata에 다시 적지 않는다. - Spring Boot 시작·런타임 의존성. - 시험에서 ArchUnit. ## 금지 - 구체적인 업무 정책. - bootstrap 아래에 직접 쓴 controller, 유스케이스, repository 어댑터, mapper. controller는 `CONTROLLERS_LIVE_IN_INBOUND_ADAPTERS`가 빌드에서 막는다. - 업무 로직을 구현하는 설정 클래스. - `application-core`나 `domain-core` 포트를 구현하기. 포트를 구현하는 클래스는 의존성을 어떻게 설정했든 outbound 어댑터이고 `adapter/outbound/*` leaf에 둔다 — `CompositionRootBoundaryArchitectureTest`가 예외 없이 강제한다. - 기동 실패를 `throw new IllegalStateException(...)`으로 내기. `StartupFailures` (`adapter:outbound:support`, 패키지 `support.startup`: `envValidation` / `profileMismatch` / `requiredAdapterDisabled` / `migrationFailed`)를 써서 실패가 sysexits 종료 코드와 구조화된 로그 필드를 싣게 한다 — `StartupFailureContractArchitectureTest`가 강제한다. - 「운영 환경인가?」를 이 모듈 안에서 답하기. 저장소 전체의 profile 어휘는 `dev.caskeleton.shared.runtime.RuntimeEnvironment`가 가진다. - `src/test`에서 `org.testcontainers`에 의존하기. 실제 서비스를 쓰는 시험은 `src/integrationTest`에 둔다. `docs/testing/TESTING_STRATEGY.md`를 본다. ## 패키지 배치 아래 규칙은 그것이 없어서 이 모듈의 리뷰 대상이 된 어긋남이 생겼기 때문에 있다 (`docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`). capability의 절반은 `autoconfigure/` 아래, 절반은 패키지 루트에 있었다. `Settings` 클래스는 규칙 없이 `settings/` 패키지와 각 기능 패키지에 나뉘어 있었다. 그리고 같은 분해 문제를 같은 leaf에서 두 가지로 풀었다 — Notification은 작은 설정 아홉 개로, Redis는 376줄 클래스 하나로. - **capability의 조립은 그 capability 자신의 모듈에 있다.** 그 모듈의 `AutoConfiguration.imports`가 등록하고, 설정은 그 모듈의 `config/module-defaults/*.yml`에 둔다. JPA(기동 guard, Flyway 전략, lock decorator, readiness, `JpaActivationEnvironmentPostProcessor`의 완전히 끄기 처리)는 `adapter:outbound:persistence-jpa`, Redis(readiness)는 `adapter:outbound:cache-redis`, 알림은 `composition:notification-platform`이다. 모든 capability는 `build.gradle`에서 주석 처리한 `runtimeOnly` 한 줄이다. 기본 조립은 web, 관측, core들, support, identifier다. 이 leaf는 capability 목록을 두지 않는다: 스위치 registry도, capability 사이 의존 검증기도, 켜기 endpoint도 없다. component scan은 `dev.caskeleton.bootstrap`만 본다. web(`WebAdapterAutoConfiguration`, `WebSecurityAutoConfiguration`, `WebMethodSecurityAutoConfiguration`)과 support (`OutboundSupportConfig`)는 자기 `AutoConfiguration.imports`로 들어온다. `autoconfigure//`에 남는 것은 모든 애플리케이션에 필요한 애플리케이션 조립인 `common`(시계)뿐이다. outbox relay, 멱등성 executor, durable operation(유스케이스와 `/operations` endpoint. 2026-11-01 성숙도 리뷰 뒤로 bootstrap 밖)은 `composition:outbox-relay`, `composition:idempotency`, `composition:durable-operation`이다. 각각 `runtimeOnly` 한 줄로 고르고, 자기 포트가 생기기 전에는 아무것도 만들지 않는다. capability의 role → permission 대응은 `config/security.yml`이 아니라 그 capability의 `config/module-defaults` 파일에 담긴다. 모든 조립 루트에 필요한 런타임 배선 — tracing, metric 계약 filter, domain-context 전파, 사용자 principal 가명화(`PrivacySettings`), actuator chain — 은 `composition:service-runtime`이다. - **`Settings`는 `settings/`가 아니라 그 capability 옆에 둔다.** `settings/` 패키지는 어느 capability에도 속하지 않는 설정 — `BootstrapSettings`, `RuntimeSafetySettings` — 만 담는다. 이 설정은 `StrictSettingsBinder`로 엄격하게 바인딩하고 scan하지 않는다. 로깅에는 settings record가 없다. `logback-spring.xml`이 `app.logging.*`을 직접 읽고 `LoggingConfigurationRule`이 Logback이 쓸 수 없는 값을 거절한다. - **`runtime/`은 애플리케이션 자체에 대한 guard를 담는다** — 비밀 값, 숫자 한계, 오류 상세 노출, 여러 인스턴스 조율, runtime profile 검사(`RuntimeEnvironmentProfileValidator`). capability 설정에 대한 guard(JPA OSIV·DDL·pool·TLS·vendor guard, Mongo 연결 출처 규칙, GraphQL 배포 모드 규칙)는 그 capability의 모듈과 함께 나간다. 그래야 capability가 있을 때만 정확히 존재한다. - **기동 실패 어휘는 `adapter:outbound:support`에 있다**(`support.startup`: phase, 오류 코드, 예외, `StartupFailures`, `StartupValidationContext`, `StartupOrder`, `ReadinessGroup`, `RuntimeWarnings`). 그래서 capability 모듈은 이 leaf에 의존하지 않고 같은 방식으로 실패한다. `runtime/startup/`에는 `StartupFailureExceptionReporter`만 남는다. - **환경만 보는 guard는 `StartupRule` bean이다**(`support.startup`). 위반을 돌려주고, 유일한 `StartupRuleRunner`가 다른 singleton이 생기기 전에 그것을 올린다(`Environment`, bean factory, 정적 `RequiredProductionSecrets`의 `ObjectProvider`만 받는 `static` `@Bean` 메서드로 선언한다. 모든 profile에서 runner는 어떤 규칙을 돌리기 전에 규칙마다, 그리고 `RequiredProductionSecrets`마다 하나씩 만든다. 그중 하나가 만드는 다른 bean이 있으면 그 이름을 대며 기동을 실패시킨다. runtime 클래스에 `@Value`/`@Autowired`/`@Inject`/`@Resource` 멤버, `@PostConstruct`/`@PreDestroy` 콜백, `@ConfigurationProperties` 바인딩이 있는 것도 이름을 대며 실패시킨다 — 그런 것은 post-processor보다 먼저 만들어져 값이 비어 있게 된다). 다른 bean이 필요한 guard는 bean으로 남는다. capability의 운영 비밀 값은 그 capability의 것이다: 그 모듈이 `RequiredProductionSecrets` bean을 내놓고, `SecretSourceValidator`는 어떤 role이 있는지 모르는 채로 이름을 검사한다. ## 분해 기준 취향에 맡기지 않고 적어 둔다. 「충분히 길다고 느꼈다」가 같은 질문에 두 가지 답을 낳았기 때문이다. - `@Configuration` 하나는 조립 관심사 하나를 담는다. 대략 **`@Bean` 메서드 여덟 개**를 넘거나, 서로 관계없는 포트 묶음 둘을 조립하게 되면 — 둘 중 먼저 오는 때에 — 나눈다. - `@ConfigurationProperties` 클래스 하나는 capability namespace 하나를 가진다. - 설정이 둘 이상 필요한 capability는 루트 클래스를 둔다. 루트가 `enabled` 조건, `@EnableConfigurationProperties`, 관심사별 클래스의 `@Import`를 가진다. 아무것도 scan하지 않는다: 조건이 걸린 루트에서 `@Import`해야 `enabled=false`가 권고가 아니라 실제로 끄는 스위치가 된다. `cache-redis`의 `capability/RedisCapabilityConfig`가 참조 예다. 다시 쓸 Spring 조립을 가진 optional 어댑터 capability는 자기 루트를 내놓는다. 알림은 `adapter:outbound:notification`의 `NotificationPlatformAutoConfiguration`과 `composition:notification-platform`의 `NotificationApplicationCompositionAutoConfiguration`을 쓴다. JPA는 `adapter:outbound:persistence-jpa`의 package-private `PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig`, `startup.JpaStartupAutoConfiguration`을 쓰고, 이 모듈은 기본 조립에 없다(`build.gradle`의 `// runtimeOnly project(':adapter:outbound:persistence-jpa')`). Mongo도 같은 규칙을 따른다: persistence-mongo leaf가 MongoRootAutoConfiguration과 그 내부 health bridge를 가지고, bootstrap은 Mongo 전용 운영 health 설정을 가지지 않는다. - 나눈 capability의 공용 도우미는 `*Util` 바구니가 아니라 하는 일을 이름으로 단 자기 타입을 가진다 — `cache-redis`의 `capability/RedisKeys`가 참조 예다. ## 테스트 - `settings` 패키지: 설정 바인딩, 값 검증, 로깅 설정을 검증한다. 새 settings 클래스에는 바인딩·검증 테스트를 더한다. - 설정·런타임·Docker 규칙은 `.claude/rules/settings-and-runtime.md`다. ```bash ./gradlew :app-bootstrap:test ./gradlew verifyCleanArchitectureDependencies ```