문제: 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
101 lines
5.9 KiB
Markdown
101 lines
5.9 KiB
Markdown
# 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](./layers.md), which also names every import rule:
|
|
|
|
- `src/bootstrap` — the composition root: runtime configuration, concrete adapter construction and the React mount
|
|
- `src/apps` — deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces
|
|
- `src/contexts` — bounded contexts: each `context-module.ts` declares its app, route root and feature budget
|
|
- `src/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 providers
|
|
- `src/adapters` — reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more
|
|
- `src/application` — generic use cases, ports, policies and view-models
|
|
- `src/contracts` — shared vocabulary and registries read by several layers, the workers and the build and release scripts
|
|
- `src/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.
|
|
|
|
```mermaid
|
|
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:
|
|
|
|
```mermaid
|
|
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-platform-capability-review.md)
|
|
- [Frontend ports, adapters, and boundaries](./frontend-ports-adapters-and-boundaries.md)
|
|
- [API contract, Schema, Mapper, and Server State](./api-contract-schema-mapper-and-server-state.md)
|
|
- [Protobuf browser transports and REST Gateway](./protobuf-browser-transport-and-rest-gateway.md)
|
|
- [Backend API and Server State handoff contract](./backend-api-and-server-state-contract.md)
|
|
- [TypeScript, state, and data flow](./typescript-state-and-data-flow.md)
|
|
- [Routing, pages, and patterns](./routing-pages-and-patterns.md)
|
|
- [Browser data capability completion ledger](./browser-data-capability-completion-ledger.md)
|
|
- [Browser file and origin storage](./browser-file-and-origin-storage.md)
|
|
- [Client cache and storage](./client-cache-and-storage.md)
|
|
- [Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md)
|
|
- [Presigned transfer and Image CDN](./presigned-transfer-and-image-cdn.md)
|
|
- [Server file capability infrastructure](./server-file-capability-infrastructure.md)
|
|
- [Frontend platform implementation roadmap](./frontend-platform-implementation-roadmap.md)
|