Files
clean-architecture-backend-…/docs/superpowers/specs/2026-09-19-fileserver-composition-decomposition.md
T

4.5 KiB

Fileserver Composition Decomposition

Goal

Close the remaining BOOT-007 drift in app-bootstrap. Redis already follows the documented composition threshold, but Fileserver still has three configurations above the repository rule:

  • FileserverPlatformAutoConfiguration: 24 @Bean methods;
  • FileserverStorageConfiguration: 18 @Bean methods;
  • FileserverServiceConfiguration: 12 @Bean methods.

The refactor changes composition ownership only. Bean identities, types, conditions, master-switch semantics and application behavior remain unchanged.

Master-switch invariant

FileserverPlatformAutoConfiguration remains the only auto-configuration entry point and the only place carrying the app.fileserver-platform.enabled master condition.

All newly extracted classes are package-private @Configuration(proxyBeanMethods = false) children reachable only through imports below that gated root. None is component-scanned or registered in AutoConfiguration.imports.

FileserverStorageConfiguration and FileserverServiceConfiguration remain as zero-bean package-private aggregators so existing composition references remain stable while their internal concerns split.

Platform split

FileserverPlatformAutoConfiguration retains only the strictly gated settings binder and imports:

  • FileserverCorePolicyConfiguration
    • FileserverWebProperties
    • TransferExecutorProperties
    • UploadPolicy
    • DownloadPolicy
    • HttpRangeResolver
    • ConditionalRequestEvaluator
    • ContentDispositionFactory
  • FileserverWebAssemblyConfiguration
    • request context/problem factories
    • raw/multipart request mappers
    • MVC conditional/download response helpers
    • zero-copy eligibility
  • FileserverNginxConfiguration
    • delegation properties
    • internal URI mapper
    • download strategy
  • FileserverProtocolConfiguration
    • TUS properties/parser/checksum verifier under the existing TUS condition
    • draft12 properties under the existing draft condition
  • FileserverObservabilityConfiguration
    • keyed SafeFileFingerprint under the existing consumer condition
    • Micrometer FileserverMetricsPort under the existing metrics condition

Storage split

FileserverStorageConfiguration becomes an aggregator importing:

  • FileserverLocalStorageCoreConfiguration
    • local storage properties
    • schema activation
    • local probe
    • blocking content store
  • FileserverStorageGatewayConfiguration
    • upload, upload-content, download, copy, cleanup and zero-copy gateways
  • FileserverStorageOperationsConfiguration
    • storage health
    • orphan scan
    • usage probe
    • reconciliation probe
  • FileserverVerificationConfiguration
    • filename policy
    • file state machine
    • verification content reader
    • verification service

Service split

FileserverServiceConfiguration becomes an aggregator importing:

  • FileserverUploadServiceConfiguration
    • identifier factory
    • transfer admission properties/controller
    • upload/finalize/single-shot services
    • writer lease coordinator
  • FileserverDownloadLifecycleConfiguration
    • download application service
    • lifecycle service
  • FileserverMaintenanceServiceConfiguration
    • cleanup service
    • reconciliation service
    • admin service under the existing admin condition

Compatibility gates

  • master switch off creates none of the child graph;
  • master switch on preserves existing bean names/types;
  • TUS, draft12, metrics/fingerprint and admin sub-feature conditions remain unchanged;
  • existing FileserverPlatformAutoConfiguration tests continue to compose through the root;
  • integration composition continues to import only FileserverPlatformAutoConfiguration;
  • no new public type is introduced;
  • no configuration in this slice exceeds the documented roughly-eight-bean threshold.

Verified result

  • FileserverPlatformAutoConfiguration now declares 1 bean and remains the only Fileserver @AutoConfiguration entry point;
  • storage and service legacy configuration names remain zero-bean aggregators;
  • extracted concern configurations are package-private and absent from AutoConfiguration.imports;
  • every Fileserver production configuration declares at most 7 @Bean methods;
  • FileserverCompositionArchitectureTest permanently enforces the <= 8 rule and is pinned by ArchRuleDiscoveryContractTest;
  • focused Fileserver auto-configuration/runtime tests: PASS;
  • FileserverCompositionIntegrationTest against real PostgreSQL and filesystem: PASS with process-local TESTCONTAINERS_RYUK_DISABLED=true on this remote host;
  • app-bootstrap Spotless, full TEST, full ARCHITECTURE and full SYSTEM regressions: PASS;
  • git diff --check: PASS.