Files
clean-architecture-backend-…/docs/mongodb/repository-adaptation.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00

10 KiB

MongoDB Document Persistence Platform — Repository Adaptation Contract

Design source: docs/superpowers/specs/2026-08-11-mongodb-document-persistence-platform-design.md Stable plan: docs/superpowers/plans/2026-08-11-mongodb-document-persistence-platform-implementation-plan.md Advanced plan: docs/superpowers/plans/2026-08-11-mongodb-advanced-capabilities-expansion-plan.md

The design package declares its own module root (modules/mongodb) and root package (io.backend.skeleton.mongodb) as implementation assumptions, not as contract. This file is the single record of how that assumed layout was mapped onto this repository. Only paths, build DSL, and composition-root ownership changed. Public contracts, policy order, and error semantics are implemented exactly as specified.

1. Why the module layout differs

The design assumes 19 Stable Gradle projects under modules/mongodb/ and 12 Advanced projects under modules/mongodb-advanced/. This repository is a Clean Architecture template whose fail-closed registry (src/config/architecture/modules.json, enforced by src/settings.gradle and verifyCleanArchitectureDependencies) declares exactly 19 leaf identities. Creating 31 more Gradle projects would violate HARD-STOP #5 in AGENTS.md.

Therefore the design's 31 modules become package boundaries inside the registered leaf :adapter:outbound:persistence-mongo, following the precedent already set by docs/httpclient/repository-adaptation.md. The design's module dependency table (§6.3) is enforced by MongoModuleBoundaryTest as a closed edge matrix: every top-level package is declared with the packages it may import, the matrix is compared against the tree for exact equality, and every observed edge must appear in it. A forbidden edge fails the build the same way a missing Gradle dependency would, and so does a new package nobody registered.

This used to be a stronger claim than the test. The rules forbade a handful of reverse dependencies and said nothing about the rest, so edges outside the design's DAG existed and passed, among them geo → imperative. They are declared in the matrix now rather than removed — each is a real coupling the code relies on, and the point of recording them is that the next one is a decision instead of an accident.

2. Package mapping

Root package: io.backend.skeleton.mongodb → dev.caskeleton.adapter.outbound.mongo.

2.1 Stable modules

Design module Repository package
mongodb-core-api …outbound.mongo.api (+ .capability, .consistency, .error, .mapping, .observation, .profile, .schema)
mongodb-spring-data …outbound.mongo.mapping (+ .type), …outbound.mongo.failure
mongodb-imperative …outbound.mongo.imperative (+ .atomic, .bulk, .revision)
mongodb-query …outbound.mongo.query (+ .budget, .pagination)
mongodb-aggregation …outbound.mongo.aggregation
mongodb-transaction …outbound.mongo.transaction (+ .retry, .session)
mongodb-index-schema …outbound.mongo.schema (+ .index, .manifest, .model, .ttl, .validation)
mongodb-geospatial …outbound.mongo.geo
mongodb-migration-core …outbound.mongo.migration
mongodb-migration-flamingock …outbound.mongo.migration.flamingock
mongodb-observability …outbound.mongo.observation
mongodb-security …outbound.mongo.security (+ .admin), …outbound.mongo.nativecap
mongodb-spring-boot-starter …outbound.mongo.autoconfigure
mongodb-testkit-core …outbound.mongo.testkit.mapping, .compat, .performance (testkit source set)
mongodb-testkit-replicaset …outbound.mongo.testkit.rs (testkit source set)
mongodb-testkit-failover …outbound.mongo.testkit.failover (testkit source set)
mongodb-testkit-migration …outbound.mongo.testkit.migration (testkit source set)

…outbound.mongo.architecture has no design counterpart: it holds the @MongoOperation marker and the reusable ArchUnit rule set a fork applies to its own document/repository code.

2.2 Advanced modules

Design module Repository package
mongodb-sharding …outbound.mongo.advanced.sharding (+ .admin for the D4 shard plane)
mongodb-csfle …outbound.mongo.advanced.encryption.csfle
mongodb-queryable-encryption …outbound.mongo.advanced.encryption.qe
mongodb-tenancy-shared …outbound.mongo.advanced.tenancy.shared
mongodb-tenancy-database …outbound.mongo.advanced.tenancy.database
mongodb-testkit-sharded …outbound.mongo.testkit.sharded (testkit source set)

mongodb-timeseries, mongodb-search, mongodb-vector-search, mongodb-gridfs-compat and mongodb-testkit-atlas have no package any more: each was an operations interface with no implementation plus the descriptors that parametrised it, and was removed on 2026-09-25 (docs/capability-status.md).

The design's rule that a Stable module never depends on an Advanced one survives as an ArchUnit rule (stableNeverDependsOnAdvanced). Every Advanced entry point takes a MongoAdvancedCapabilityGuard and refuses construction unless its MongoAdvancedCapabilityFlags enable the matching capability. There is no configuration property behind the flags: the Advanced types are library API, and the adopter's adapter that constructs them builds the guard.

3. Other deliberate substitutions

Design assumption Repository reality Adaptation
Gradle Kotlin DSL under modules/mongodb* Groovy DSL, root build.gradle conventions, LockMode.STRICT locking Dependencies declared in src/adapter/outbound/persistence-mongo/build.gradle; gradle.lockfile regenerated.
mongodb-spring-boot-starter is a separate module the app depends on modules.json gives adapter-outbound-persistence-mongo an explicit project boundary; runtime membership is derived from resolved runtime classpaths rather than a per-leaf registry field The autoconfigure package stays inside the leaf and registers through the leaf's own META-INF/spring/…AutoConfiguration.imports. This differs from the httpclient precedent; dependency and runtime-membership gates decide whether the leaf is actually composed.
Spring Boot 4.1 / Spring Data MongoDB 5.1 baseline Repository baseline is Spring Boot 4.0.8 / Spring Data MongoDB 5.0.x The platform targets the Spring Data MongoDB API surface common to both; no 5.1-only type is referenced. The support matrix records the actual pinned versions.
MongoRetryScope lives in mongodb-transaction The mongodb-spring-data failure translator must classify retry scope, and it cannot depend on mongodb-transaction MongoRetryScope lives in …api.error (core-api), which both packages already depend on. Same values, same meaning, one legal position in the DAG.
mongodb-migration-flamingock depends on Flamingock Adding an unvetted external dependency is out of scope for this task, and the design itself requires the public contract not to depend on Flamingock types The adapter is provider-neutral: it consumes a platform-owned FlamingockChangeUnitView. Wiring an actual Flamingock distribution is a one-file change behind that view.
Testkit as its own Gradle module The design forbids production modules depending on the testkit A dedicated testkit source set whose output is on the test compile/runtime classpaths only. ArchUnit rule productionNeverDependsOnTestkit enforces the direction.
Per-task git commit AGENTS.md: commit policy is human-only Implementation is delivered unstaged; commits are the human's action. This is the only plan step intentionally not executed, and it is recorded here.
docs/mongodb/**, scripts/verify-mongodb-*.sh Repository already owns docs/ and scripts/ Created at the same repository-relative paths. The two gate scripts were later removed (2026-08-15); see §5.

4. What is unchanged from the design

  • D1 / D2 / D3 / D4 exposure planes and the ordered D3 admission sequence (§5).
  • Stable API V1 with apiStrict=true on the D1/D2 client generation; D3/D4 on separate generations.
  • MongoExecutionOutcome, including both ambiguous outcomes (WRITE_RESULT_UNKNOWN, TRANSACTION_COMMIT_UNKNOWN), and MongoFailureContext's permitted-field list.
  • The complete stable exception hierarchy and the label-before-code classification order.
  • The BSON representation manifest (UUID STANDARD, Decimal128, UTC instants, alias type metadata) and the document-size budget.
  • Update-operator-first writes, and optimistic revision as the precondition for whole-document replacement.
  • Transaction body retry and commit retry as separate loops: a new session per body attempt, and commit-only retry on unknown commit. The body is never replayed after a commit ambiguity.
  • Registered operation names and manifests for query, aggregation and index; no free-form JSON query and no unbounded pipeline.
  • Keyset pagination with an authenticated cursor and a unique tie-breaker requirement.
  • TTL as physical cleanup only, never the sole basis for access denial or business scheduling.
  • Manifest-owned index/validator state with an apply policy that never drops what it does not own.
  • Low-cardinality observation tags, command redaction, and the credential reference indirection.
  • The Stable release gate's evidence categories. The Advanced promotion requirements (actual-topology evidence) are a review obligation in ADR-MONGO-ADV-001; no class checks them.

5. Verification

The release-gate scripts scripts/verify-mongodb-platform.sh and scripts/verify-mongodb-advanced.sh are present and wrap the named Gradle lanes with no-skip evidence and promotion metadata. Use them when producing release/promotion evidence; the focused commands below remain useful for local diagnosis.

From src/:

./gradlew :adapter:outbound:persistence-mongo:check --console=plain
./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew :app-bootstrap:architectureTest --console=plain

The container-backed lanes the gate ran behind MONGODB_DOCKER=1 — mongoCompatibilityTest, mongoMigrationTest, mongoSecurityIntegrationTest, mongoReplicaSetTest, mongoFailoverTest, mongoPerformanceTest — are now invoked by name or not at all.