문제: 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.
114 lines
7.9 KiB
Markdown
114 lines
7.9 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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 "제거된 코드".
|