The barrel rule and layers.md said storage/indexeddb and storage/opfs are each removable on their own. The removal drill deletes the whole browser-file-storage bundle together; the sub-barrels exist so the Web Storage barrel survives it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
139 lines
7.5 KiB
Markdown
139 lines
7.5 KiB
Markdown
# Clean Architecture layer contract
|
|
|
|
The import direction is `domain <- application <- presentation`; concrete
|
|
adapters implement application-owned ports and are assembled only in
|
|
`src/bootstrap`.
|
|
|
|
| Layer | Owns | May depend on |
|
|
| --- | --- | --- |
|
|
| `domain` | framework-neutral models and pure policies | domain siblings |
|
|
| `application` | use cases, ports, orchestration, view-models | domain and application siblings |
|
|
| `presentation` | routes, components, user interaction and view state | application public API and shared UI |
|
|
| `adapters` | browser and third-party implementations of application ports | application ports and limited domain values |
|
|
| `features/<id>` | removable vertical domain/application/contracts/adapters/presentation slice | the same inward rule plus platform public boundaries |
|
|
| `bootstrap` | runtime configuration, adapter construction and React mount | all selected runtime modules |
|
|
|
|
The following edges are forbidden:
|
|
|
|
- domain to application, presentation, adapters, bootstrap, React, or browser globals
|
|
- application to presentation, concrete adapters, bootstrap, React, or browser globals
|
|
- `contracts` to application or features: contracts is the lower package and
|
|
owns the shared vocabulary both of them read
|
|
- presentation to concrete adapters, raw DTO schemas, or storage implementations
|
|
- generic presentation to the installed-feature registries: which features exist
|
|
is a product decision owned by `bootstrap`
|
|
- an adapter to presentation, bootstrap internals, or another concrete adapter
|
|
- feature domain/application to its presentation or outbound adapter, and
|
|
feature presentation to its outbound adapter
|
|
- a module presentation may import to a concrete adapter: files outside a
|
|
feature's layer folders (`src/features/*.ts`, `src/features/<id>/*.ts`),
|
|
`src/contexts` and `src/apps` (`feature-and-app-roots-do-not-reach-adapters`).
|
|
The graph checks one edge at a time, so a re-export there would carry an
|
|
adapter into presentation with every other rule passing. The one exception is
|
|
the type-only `src/features/feature-adapter-contribution.ts`
|
|
- presentation to `src/apps` or `src/contexts`, except
|
|
`src/presentation/routes/app-router.tsx`, which mounts the app's route tree
|
|
(`presentation-does-not-import-apps-or-contexts`)
|
|
|
|
## The adapter kernel
|
|
|
|
"Another concrete adapter" excludes the adapter kernel, which is shared on
|
|
purpose and is the only adapter code an adapter may reach across a group for:
|
|
|
|
- `src/adapters/platform/**` — the system clock, the shared abort primitive and
|
|
the bounded-capacity guard
|
|
- `src/adapters/browser-file-storage/result.ts` — the browser-data result and
|
|
failure constructors
|
|
- `src/adapters/cross-context-invalidation/index.ts` — the cross-context
|
|
invalidation transport and its types. Any adapter may import it; today
|
|
`query-cache` does
|
|
|
|
Each rule above is enforced by `check:architecture`, including the kernel
|
|
carve-out, so this table and the executable rules cannot drift apart.
|
|
|
|
Every exception is written in the rule itself (`.dependency-cruiser.json`): the
|
|
exempted path in `pathNot`, and the reason, owner and revisit condition in
|
|
`comment` (review 12-07). Besides the kernel, the exceptions are:
|
|
|
|
- the generic presentation modules that read the installed registries today
|
|
(`generic-presentation-does-not-compose-the-product`). The list names exact
|
|
files, so a new module that reads a registry fails the gate
|
|
- `src/presentation/adapters/query`, the TanStack Query binding
|
|
(`presentation-does-not-know-adapters`)
|
|
- `src/presentation/routes/app-router.tsx` importing the app
|
|
(`presentation-does-not-import-apps-or-contexts`)
|
|
- the design-system facades (`design-system-is-reached-through-its-index`)
|
|
|
|
## 어댑터 그룹의 공개 경계
|
|
|
|
각 어댑터 그룹의 공개 표면은 그 그룹의 `index.ts`다. 그룹 바깥
|
|
(`bootstrap`, `features`, `presentation`)은 배럴만 import한다.
|
|
`adapter-groups-are-reached-through-their-barrel` 규칙이 이를 강제하고,
|
|
`tests/fixtures/architecture/dependency-graph/barrel`이 거부와 허용을
|
|
각각 고정한다 — 규칙을 지우면 그 회귀 검사가 먼저 깨진다.
|
|
|
|
두 가지 예외가 있고 둘 다 의도된 것이다.
|
|
|
|
- **그룹 내부 파일끼리**는 파일 경로로 직접 import한다. 배럴은 바깥을 위한
|
|
문이지 내부 규율이 아니다.
|
|
- **어댑터 → 커널(`platform/**`)** 간선도 파일 경로를 유지한다. 커널은
|
|
런타임 합성물이 아니라 프리미티브이고, `check:adapter-inventory`가 네
|
|
소비자에게 `platform/abortable-operation.ts`로 해석되는 specifier를
|
|
직접 요구한다. 커널 배럴(`platform/index.ts`)은 bootstrap과 테스트를
|
|
위한 것이다.
|
|
|
|
`storage`는 최상위 배럴이 `indexeddb/`·`opfs/` 서브배럴을 재수출하지
|
|
않는다. 두 폴더는 browser-file-storage 번들의 런타임이다. 제거 드릴
|
|
(`test:browser-file-storage-removal`)은 그 번들 전체(`browser-file-storage`,
|
|
`browser-files`, `browser-transfer`, `cache-storage`, `storage/indexeddb`,
|
|
`storage/opfs`)를 함께 지운다. 최상위 `storage` 배럴(Web Storage)은 그 뒤에도
|
|
남아야 하므로 두 폴더를 재수출하지 않고, 그래서 각 서브배럴이 그 런타임의 공개
|
|
경계다.
|
|
규칙의 도착점 정규식은 이 두 서브배럴만 배럴로 인정한다. 다른 그룹의 2단계
|
|
`index.ts`(예: `http/internals/index.ts`)는 공개 배럴이 아니고, 그룹 바깥에서
|
|
import하면 실패한다(리뷰 12-07, `dependency-graph/barrel` fixture).
|
|
|
|
`service-worker/index.ts`는 `tsconfig.service-worker.json`의 `exclude`에
|
|
들어 있다. 그 설정이 그룹 폴더를 통째로 WebWorker lib로 컴파일하면서 페이지
|
|
realm 파일만 빼는 구조라, 배럴이 그 파일을 다시 끌어들이면 워커 타입체크가
|
|
`document`를 찾지 못한다. 배럴의 타입 커버리지는 `tsconfig.app.json`이
|
|
담당하고, 워커 진입점은 배럴을 쓰지 않는다.
|
|
|
|
`bootstrap` contains composition only. Business rules and page-specific
|
|
orchestration belong to domain/application.
|
|
|
|
The [ports, adapters, and feature-boundary contract](./frontend-ports-adapters-and-boundaries.md)
|
|
explains how `presentation` acts as the inbound adapter and how feature
|
|
application APIs augment the generic typed input registry. Concrete output
|
|
ports are composed in bootstrap and stay hidden behind the application facade.
|
|
Project-selected capabilities still implement the same output boundaries.
|
|
|
|
`check:architecture` writes the TypeScript-aware graph below. It reads the rules
|
|
from `.dependency-cruiser.json` but does not run dependency-cruiser, which cannot
|
|
parse TypeScript 7 and checked zero modules (review 12-05):
|
|
|
|
```json
|
|
{
|
|
"staticImportGraph": {
|
|
"analyzer": "babel-parser-node-resolver",
|
|
"modules": [],
|
|
"dependencies": [],
|
|
"unresolved": [],
|
|
"parseFailures": [],
|
|
"cycles": [],
|
|
"violations": [],
|
|
"summary": { "errors": 0 },
|
|
"fixtureChecks": { "passed": true, "checks": [], "failures": [] }
|
|
}
|
|
}
|
|
```
|
|
|
|
The graph scans TypeScript and TSX, including static, dynamic, type, CommonJS
|
|
and JSDoc import references. `import.meta.glob` is a parse failure: it loads
|
|
modules without naming one, so no edge rule could see them (review 12-06). It applies the path rules from
|
|
`.dependency-cruiser.json`, requires explicit TypeScript extensions for local
|
|
source imports, and fails closed on JavaScript-family source/specifiers,
|
|
unsupported rule shapes, unresolved imports, parse failures, error-severity
|
|
layer violations, or cycles. Regression fixtures prove the allowed resolver
|
|
path and each rejection class.
|