문제: src/ 최상위 폴더는 adapters application apps bootstrap contexts
contracts features platform presentation 9개다. layers.md 표,
frontend-application-foundation.md 목록, overview.md 그림, README 구조
그림은 src/platform을 한 번도 적지 않았고 apps·contexts는 금지 간선
설명에만 나왔다. 대신 없는 최상위 domain을 계층으로 그렸다.
contract-ownership.md의 배치 규칙에는 src/platform 선택지가 없었다.
layers.md는 "표와 규칙이 어긋날 수 없다"고 적었지만
.dependency-cruiser.json 규칙 31개 중 25개의 이름이 없었다.
게이트는 금지 간선만 막으므로, 허용되지만 틀린 자리(최상위 domain 신설,
제품 중립 primitive를 contracts에 두기)를 문서로 막을 수 없었다.
고른 방법: 리뷰의 (B)안. 문서를 코드에 맞추고 verify:documentation에
대조 검사를 더한다.
- layers.md: 9개 폴더 표(폴더 | 소유)를 정본으로 두고, 금지 간선 글머리
목록을 규칙 31개 표(규칙 이름 | 적용 대상 | 금지)로 바꾼다. domain은
기능 안의 계층으로 옮기고 "최상위 domain 폴더는 지금 없고, 만들면
domain-is-framework-neutral이 이미 적용된다"고 적는다. 보증 문장은
실제로 검사하는 범위로 줄인다. kernel 절과 배럴 절은 그대로 둔다.
- README·overview·foundation: layers.md 표의 설명을 한 글자도 바꾸지
않고 "`src/<폴더>` — <설명>" 목록으로 싣는다. 그림은 실제 import
방향(presentation -> application -> contracts -> platform,
apps -> contexts -> features)으로 다시 그린다.
- contract-ownership.md: src/platform 선택지와 contracts와의 차이,
platform-kernel-is-product-neutral을 적는다.
- verify-documentation-readiness.ts: 폴더 목록은 src/를 읽고, 규칙 목록은
.dependency-cruiser.json을 읽는다. layers.md 표에 행이 없는 폴더,
나머지 세 문서에서 설명이 다른 폴더, 네 문서가 적은 없는 최상위
src 폴더, layers.md에 없는 규칙 이름이 있으면 실패한다. 결과는
documentation-review.json의 sourceStructure로 남긴다(스키마는 필드
하나를 더한다).
버린 대안: (A) 문서만 고치기 — 규칙이나 폴더가 늘면 다시 어긋난다.
(C) layers.md를 .dependency-cruiser.json에서 생성 — 사람이 읽는 설명을
넣기 어렵다. 네 문서 모두에 규칙 31개를 싣는 것 — 같은 목록이 네 벌이
되어 어긋날 곳만 늘어난다. 규칙 표는 layers.md 한 곳에 둔다.
위험·한계:
- 검사는 규칙 이름이 있는지만 본다. 행의 설명이 규칙과 맞는지는 보지
않는다(문서에도 그렇게 적었다).
- 없는 폴더 검사는 "src/<이름>" 꼴만 잡는다. "domain"처럼 src/ 없이
계층 이름만 쓰는 것은 잡지 못한다.
- README·overview·foundation에는 같은 9줄이 복사되어 있다. 설명을 바꾸면
네 곳을 함께 고쳐야 하고, 검사가 그것을 강제한다.
- .dependency-cruiser.json 주석의 "like src/domain"(feature-domain 규칙)은
코드 주석이라 이번 범위 밖이다.
- 문서 drift 전반(경로·줄 번호, 14-05)은 다루지 않는다.
검증:
- RED: 새 검사를 기준 커밋(7a70cea)의 문서에 돌리면 FAIL_UNVERIFIED
(failed: source structure). layers.md는 규칙 25개가 없고, 네 문서
모두 9개 폴더를 설명하지 않는다고 나온다.
- GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED.
tests/unit/documentation-readiness.test.ts 6개 통과. 새 변이 3개:
규칙 이름 하나를 바꾸면, README에 `src/domain`을 넣으면, overview의
platform 설명을 바꾸면 각각 실패하고 원인 문서와 이름을 적는다.
- 회귀: tests/unit 전체(fixture-node-modules 제외, pnpm 설치를 띄운다)
173파일 2494개 통과. ci-artifact-contract의 "semantically invalid"
16개 통과. tsc(node, test) 통과, 바꾼 ts 파일 eslint 통과.
- 미실행: check:architecture(pnpm 필요, worktree에서 금지).
Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-03
5.9 KiB
Architecture overview
This Mermaid view is a repository-local implementation projection. The
PASS_SCOPED reviewer evidence applies to the canonical draw.io diagram named
in review-ledger.json, not automatically to edits in this file.
src/ has nine top-level folders. The descriptions match the table in
the layer contract, which also names every import rule:
src/bootstrap— the composition root: runtime configuration, concrete adapter construction and the React mountsrc/apps— deployable apps: eachapp-module.tsdeclares an app and its context budget;template-app.tsis the app this build producessrc/contexts— bounded contexts: eachcontext-module.tsdeclares its app, route root and feature budgetsrc/features— removable vertical slices (src/features/<id>/{domain,application,contracts,adapters,presentation}) and the installed-feature catalogs (src/features/*.ts)src/presentation— generic UI and the inbound adapter: routes, layouts, the design system, pages and providerssrc/adapters— reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and moresrc/application— generic use cases, ports, policies and view-modelssrc/contracts— shared vocabulary and registries read by several layers, the workers and the build and release scriptssrc/platform— product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence
Arrows point from the importing folder to the imported one. Every folder may
also import contracts and platform; only the main path is drawn.
flowchart LR
Bootstrap[bootstrap / composition root] --> Presentation[presentation]
Bootstrap --> Adapters[adapters]
Bootstrap --> Features[features]
Presentation --> Shell[app shell and route surfaces]
Shell --> Providers[session and theme providers]
Presentation -- app router only --> Apps[apps]
Apps --> Contexts[contexts]
Contexts --> Features
Features --> Application[application]
Presentation --> Application
Adapters --> Application
Application --> Contracts[contracts]
Contracts --> Platform[platform]
The enforced dependency rule points inward: presentation calls application use cases, adapters implement application ports, and only the composition root selects concrete adapters. Domain code lives inside each feature. Contract registries are the named source for routes, API operations, environment values, storage keys, errors, queries, telemetry, and release tokens. Installed feature contributions extend those registries without making the generic application or router import a concrete feature implementation.
In ports-and-adapters terms, presentation is the current inbound adapter and
adapters contains the current outbound implementations. The production
composition exposes an application input API to React while keeping concrete
output ports inside application closures:
flowchart LR
Driver[User, route, browser event] --> Inbound[React inbound adapter]
Inbound --> Input[Application input API]
Input --> UseCase[Use cases]
UseCase --> Output[Application output ports]
Output --> Outbound[HTTP, auth, storage, query, telemetry adapters]
Bootstrap2[Composition root] -. selects and injects .-> Input
Bootstrap2 -. selects and injects .-> Outbound
The executable route tree is mounted only after runtime configuration and
release-manifest coherence pass. ApplicationProvider receives the composed
application API; concrete session, storage, telemetry, diagnostics, and release
ports are not returned to feature pages. TanStack Query is isolated behind the
presentation query adapter, while its provider remains React infrastructure.
The module-augmented feature registry gives each installed feature a closed ID
and exact input type.
Route contracts/codecs, the route-input provider, and lazy runtime modules are
separate modules so feature pages do not import the router that loads them.
Expected application failures use the shared Result/AppFailure contract.
The architecture gate analyzes TS/TSX imports with its own graph (the rules
live in .dependency-cruiser.json; dependency-cruiser itself cannot parse
TypeScript 7 and does not run), rejects local JavaScript-family specifiers and executable
JavaScript-family files, and fails on unresolved imports, parse failures,
forbidden layer edges, or cycles. The remaining project-owned work includes
selecting and verifying real hosting, identity, telemetry, vulnerability and
signing providers, plus backend/provider/browser/operations evidence for each
selected optional capability; the repository does not fabricate that evidence.
Use the following
documents for implementation details and project integration work:
- Frontend platform capability review
- Frontend ports, adapters, and boundaries
- API contract, Schema, Mapper, and Server State
- Protobuf browser transports and REST Gateway
- Backend API and Server State handoff contract
- TypeScript, state, and data flow
- Routing, pages, and patterns
- Browser data capability completion ledger
- Browser file and origin storage
- Client cache and storage
- Realtime events, Web Push, and bounded polling
- Presigned transfer and Image CDN
- Server file capability infrastructure
- Frontend platform implementation roadmap