Files
clean-architecture-backend-…/docs/notification/module-mapping.md
T
DongHyeonka 630f9b860a docs(records): 설계서와 기록 문서를 docs/design·docs/history로 옮긴다
문제: docs/ 바로 아래에 매뉴얼·운영 문서와 쓴 때의 기록(계획서·설계서·
납품 패키지·증거·학습)이 같은 층에 섞여 있다. 기록이라는 표시도 없어
읽는 사람이 지금 동작을 설명하는 문서와 구분하지 못한다.

고른 방법: 2026-11-07 소유자가 승인한 수명 기준 분리를 따른다.
- docs/superpowers/specs → docs/design/
- docs/superpowers/plans → docs/history/plans/
- docs/superpowers/packages/* → docs/history/packages/*
- docs/{graphql,web,websocket}-superpowers-package
  → docs/history/packages/<같은 이름>/ (packages/graphql과 겹치지 않게
  원래 폴더 이름을 둔다)
- docs/evidence → docs/history/evidence/, docs/study → docs/history/study/
- git에 들어가 있던 __pycache__ .pyc를 지우고 .gitignore에 더한다.

옮긴 경로를 가리키는 줄을 같은 커밋에서 고쳤다: 살아 있는 문서의 인라인
경로, AGENTS.md·CLAUDE.md, 빌드 스크립트·테스트 주석, docs/README.md 위치
표, 파생 서비스용 docs/upgrade/2026-11-docs-records.md. 기록 본문은
고치지 않고, 이동으로 깨진 마크다운 상대 링크 32개의 대상만 고쳤다(lychee와
check-work-docs.py --links가 docs/** 전체를 본다). 이동만 따로 두면 그
커밋에서 링크 검사가 실패하므로 한 커밋으로 묶었다. 대부분 R100이라 이름
바뀜은 그대로 보인다.

위험·한계: 기록 본문과 docs/reviews/** 안의 인라인 코드 경로는 옛 경로로
남는다(기록은 고치지 않는다). 실험용 Flyway 파일
db/experimental-rls/V1__tenant_rls.sql의 주석은 체크섬이 바뀌므로 두었다.
납품 패키지 셋의 MANIFEST.sha256과 validate_*.py는 패키지 안 상대 경로라
이동 뒤에도 그대로다.

검증: python3 scripts/check-work-docs.py rc=0, --links(gates.md 범위 +
CLAUDE.md·AGENTS.md) 581개 파일 깨진 링크 0, --history docs/manual rc=0.
2026-11-07 12:15:45 +09:00

7.9 KiB

Notification Delivery Platform — module mapping

Source design: docs/design/2026-08-10-notification-platform-design.md

Source plan: docs/history/plans/2026-08-10-notification-platform-implementation-plan.md

Why a mapping exists

The plan was written against a hypothetical repository (modules/notification/**, root package io.backend.skeleton.notification, 31 Gradle projects). This repository is a fail-closed 19-leaf Clean Architecture template: src/settings.gradle rejects any registry that does not contain exactly the 19 modules in src/config/architecture/modules.json, and verifyCleanArchitectureDependencies rejects any project edge outside allowed_dependencies.

Creating 31 new Gradle projects would violate HARD-STOP #5 of AGENTS.md. The package README anticipates this and instructs the implementer to map dependency catalog and package/file paths onto the host repository's rules while preserving the public contracts and reliability semantics.

Every logical module of the plan is therefore implemented as a package inside the registered leaf that owns its responsibility. No public contract, evidence rule, or reliability semantic is dropped.

Logical module → registered leaf

Plan module Registered leaf Package
notification-core-api application-core dev.caskeleton.application.notification.platform.api
notification-content-api application-core …platform.api.content
notification-contact-api application-core …platform.contact
notification-template-api application-core …platform.template
notification-policy application-core …platform.policy
notification-provider-spi application-core …platform.provider
notification-callback-api application-core …platform.callback
notification-inbox-api application-core …platform.inbox
notification-admin-api application-core …platform.admin
notification-security (ports) application-core …platform.security
notification-observability (ports) application-core …platform.observation
notification-dispatch-runtime adapter:outbound:notification dev.caskeleton.adapter.outbound.notification.platform.dispatch
notification-security (AES-GCM/HMAC impl) adapter:outbound:notification …platform.security
notification-template-thymeleaf (reference renderer) adapter:outbound:notification …platform.template
notification-email-smtp adapter:outbound:notification …platform.provider.smtp
notification-email-ses adapter:outbound:notification …platform.provider.ses
notification-observability (Micrometer impl) adapter:outbound:notification …platform.observation
notification-admin-runtime adapter:outbound:notification …platform.admin
notification-spring-boot-starter adapter:outbound:notification …platform.autoconfigure
notification-persistence-jpa adapter:outbound:persistence-notification dev.caskeleton.adapter.outbound.persistence.notification.platform (store adapters), ….platform.entity (JPA rows), ….platform.repository (Spring Data interfaces and SQL text)
notification-inbox-jpa adapter:outbound:persistence-notification …persistence.notification.platform (JpaNotificationInbox, InboxCommitEventPublisher, InboxOutboxRecordFactory); row and repository in ….platform.entity / ….platform.repository
notification-callback-mvc adapter:inbound:web-notification dev.caskeleton.adapter.inbound.web.notification.platform.callback
notification-submission-mvc adapter:inbound:web-notification dev.caskeleton.adapter.inbound.web.notification.platform.submission
application composition (use cases, callback bridge, config/module-defaults/notification.yml) composition:notification-platform dev.caskeleton.composition.notification
notification-testkit test source sets of the owning leaves …platform.testkit

Dependency-direction consequences

The plan's module DAG (*-api → provider-spi/policy → runtime/adapters → starter) is preserved by the leaf DAG that the registry already enforces:

application-core (all *-api, provider SPI, policy, callback contracts)
        ↑                        ↑                      ↑
adapter:outbound:notification    adapter:outbound:persistence-notification    adapter:inbound:web-notification
        ↑                                    ↑ (runtimeOnly, with persistence-jpa)    ↑ (→ adapter:inbound:web)
        └──────────── composition:notification-platform ───────────────────────┘
                                   ↑
                             app-bootstrap (one line)

Two plan edges cannot be expressed as project edges in this repository, and are replaced by ports:

  1. notification-email-ses → httpclient platform. (The Twilio, FCM, APNs, Web Push and Webhook adapters that shared this edge were removed: none had an assembler.) adapter-outbound-notification is not allowed to depend on adapter-outbound-httpclient, and SES no longer needs it: the SES adapter sends through the AWS SDK v2 sesv2 client (owner decision 17), which signs requests itself. The adapter-local JDK HTTP gateway and SigV4 signer were deleted with that change. The client is built per profile with SDK retries off, no default credential chain (each request carries its profile's credential) and the profile's endpoint, which still passes the notification routability guard.
  2. notification-inbox-jpa → optional messaging outbox integration. adapter-outbound-persistence-notification may not depend on adapter-outbound-messaging; the inbox publishes through the existing persistence outbox tables plus the NotificationInboxSignalPort application port, and app-bootstrap binds the relay.

Commit policy

AGENTS.md pins commit policy to human-only. Step 5 (git add / git commit) of every plan task is therefore intentionally not executed by the agent; the working tree carries the change and the human owner commits.

Runtime reachability after the R1 adapter cleanup

The application R1 contract covered by NOTIF-ADR-005 is a separate question from the abandoned outbound implementation that had been built around it. The latter is gone: the notification leaf no longer contains top-level catalog/, provider/, or template/ R1 adapter packages. They had no production composition consumer and were proved only by their own fakes.

The useful rendering invariant from that experiment was not discarded. R2 platform.template.TemplateSlotPolicy now validates the final HTML against the reviewed tag and attribute subset in addition to escaping substituted values. Active script markup, event-handler attributes and non-HTTPS HTML links are refused.

R2 provider protocol packages remain because they implement the canonical platform SPI and have contract tests. Their presence does not make them shipped dispatch runtimes. Current composition reachability is SMTP and SES for dispatch, with SES also available for callback ingestion; the remaining provider packages are extension assets until a composition contributes a ProviderRuntimeAssembler with the settings and secret sources that family requires. See support-matrix.md for the explicit table.

R1 public types (NOTIF-ADR-005)

NOTIF-ADR-005 made ..notification.platform.. canonical. The R1 types directly under dev.caskeleton.application.notification had no production consumer and were removed on 2026-09-25, together with the ArchUnit rule that kept the two namespaces apart. What remains there is the simple notification port the adapter core implements — NotificationPort, Notification, NotificationChannel. The removed types and their last commit are listed in docs/capability-status.md under "제거된 코드".