# 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-core` or `domain-core` port. A class that implements one is an outbound adapter and belongs in an `adapter/outbound/*` leaf, however its dependencies are configured — `CompositionRootBoundaryArchitectureTest` enforces this, with no exceptions. - Raising a startup failure with `throw new IllegalStateException(...)`. Use `StartupFailures` (`adapter:outbound:support`, package `support.startup`: `envValidation` / `profileMismatch` / `requiredAdapterDisabled` / `migrationFailed`), so the failure carries its sysexits exit code and structured log fields — `StartupFailureContractArchitectureTest` enforces this. - Answering "is this production?" locally. `dev.caskeleton.shared.runtime.RuntimeEnvironment` owns the profile vocabulary for the whole repository. - Depending on `org.testcontainers` from `src/test`. Real-service tests belong to `src/integrationTest`; see `docs/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`, BOOT-006 / BOOT-007). 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's `config/module-defaults/*.yml`. JPA (startup guards, Flyway strategy, lock decorator, readiness and full-off handling in `JpaActivationEnvironmentPostProcessor`) is `adapter:outbound:persistence-jpa`; Redis (readiness) is `adapter:outbound:cache-redis`; notification is `composition:notification-platform`. Every capability is a commented `runtimeOnly` line in `build.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 covers `dev.caskeleton.bootstrap` only; web (`WebAdapterAutoConfiguration`, `WebSecurityAutoConfiguration`) and support (`OutboundSupportConfig`) arrive through their own `AutoConfiguration.imports`. What stays in `autoconfigure//` is application composition over application-core ports that names no module type: `operation` (the durable operation use cases and their `/operations` endpoints, on only when the operation store and the outbox append port exist), `common`. The outbox relay and the idempotency executor are `composition:outbox-relay` and `composition:idempotency`, selected by one `runtimeOnly` line each (the sample takes the idempotency one too). The runtime wiring both composition roots need — tracing, the metrics contract filters, domain-context propagation, user-principal pseudonymization (`PrivacySettings`) and the actuator chain — is `composition:service-runtime`, which the sample takes by the same line instead of carrying copies. - **`Settings` lives beside its capability**, not in `settings/`. The `settings/` package holds only settings that belong to no capability — `BootstrapSettings`, `LoggingSettings`, `RuntimeSafetySettings`. - **`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 only `StartupFailureExceptionReporter`. - **An environment-only guard is a `StartupRule` bean** (`support.startup`): it returns violations, and the one `StartupRuleRunner` raises them. A guard that needs another bean stays a bean. A capability's production secrets are the capability's: its module contributes a `RequiredProductionSecrets` bean, and `SecretSourceValidator` checks 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 `@Configuration` holds one assembly concern. Split when it passes roughly **eight `@Bean` methods**, or as soon as it assembles two unrelated port families — whichever comes first. - One `@ConfigurationProperties` class owns one capability namespace. - A capability that needs more than one configuration gets a root class holding its `enabled` condition, `@EnableConfigurationProperties`, and an `@Import` of the per-concern classes. Scan nothing: `@Import` from a gated root is what keeps `enabled=false` load-bearing rather than advisory. `cache-redis`'s `capability/RedisCapabilityConfig` is the reference example. Optional adapter capabilities that own reusable Spring composition publish their own root instead. Notification uses `adapter:outbound:notification`'s `NotificationPlatformAutoConfiguration` plus `composition:notification-platform`'s `NotificationApplicationCompositionAutoConfiguration`; JPA uses the package-private `PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig` and `startup.JpaStartupAutoConfiguration` from `adapter:outbound:persistence-jpa`, which is not in the default composition (`// runtimeOnly project(':adapter:outbound:persistence-jpa')` in `build.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 `*Util` bucket — `cache-redis`'s `capability/RedisKeys` is the reference. ## Test ```bash cd src ./gradlew :app-bootstrap:test ./gradlew verifyCleanArchitectureDependencies ```