22. Spring integration in its own module
Date: 2026-10-06
Status
Accepted. Startup-migration behavior superseded by ADR 0039; the module decision remains accepted.
Context
Spring Boot applications want a Bikesched node from their context — no builder code, handlers as
@JobHandler methods of beans — but core’s defining property is its two runtime dependencies (the
PostgreSQL driver and slf4j-api), enforced by AGENTS.md (“core stays free of concrete
libraries”). Spring also brings problems core should not carry: AOP-proxied handler beans,
auto-configuration ordering against the application’s DataSource, and lifecycle coupling
polling to the context.
Decision
The integration lives in its own module, bikesched-spring-boot-starter (package and JPMS module
org.bikesched.spring), the same pattern as bikesched-jackson, bikesched-annotations and
bikesched-micrometer: it depends on core and annotations (api) plus spring-boot-autoconfigure;
core keeps no Spring type. One artifact, not the Boot convention of a separate -autoconfigure
module: the auto-configuration classes live in org.bikesched.spring, so a later split is
transparent to users. Jackson, Micrometer and spring-tx/spring-jdbc stay optional
(compileOnly/requires static, guarded by nested @ConditionalOnClass configurations).
Consequences
- Applications that do not use Spring pay nothing; Spring upgrades touch only this module.
- The module is the project’s first dependency on a large framework: Boot version support (4.1
only) now has to be tracked, and Boot’s own modularization (e.g.
DataSourceAutoConfigurationmoving tospring-boot-jdbc) is absorbed here — auto-configuration ordering is by name, not by class, to keep the dependency optional. - Proxy-safe handler discovery required the additive
JobHandlers.scan(Class)/bindToAPI inbikesched-annotationsrather than Spring-specific reflection in this module, so the validation logic exists once. - Design details (discovery via a collecting
BeanPostProcessor, fail-fast migration, the<application-name>-<host>default node name) are specified indocs/specs/bikesched-spring-boot-starter.mdand documented indocs/spring.md.