Files
tech-log-frontend/docs/architecture/layers.md
T
DongHyeonka c80320dfc7 chore: sync the frontend template from ebea300 to af3d8e6
Carries 359 template commits, tag v0.2.0 plus one documentation commit: the
generator-built feature index with its app, bounded-context and feature
declarations, the src/platform kernel and scale tooling, the 2026-09-24 src
review fixes, and the 2026-09-25 maturity review round with its CHANGELOG
[보안]/[계약] rows. 691 of the 824 template paths are applied, 85 of them
merged with product changes; 127 are not carried.

Product identity is unchanged: name, version 0.1.0, routes, design and the
TechLog domain.

Three decisions worth naming. TechLog stays composed directly, as the last
two syncs recorded; its directory carries a NOT_INSTALLED marker that says so,
and every installed-* composer takes the template's projection with TechLog
added on top. The reference sample is no longer installed: the template now
installs a feature only through feature-module.ts and context-routes.ts,
which load the screens this product deleted, so its three operations, six
schemas and one topic leave the registries, recorded as registry change
evidence. And AppRouter mounts the platform and TechLog routes only; the
template's bounded-context route gateway waits for a generator-installed
feature.

Required fixes: readSubject on the BFF session owner (without it every HTTP
Studio session would close as integration-failed), zod through the facade in
nine TechLog files, noUnusedLocals, and public/config.json written out to
match the local profile. Derived baselines were recomputed after reproducing
both sides' values: CI contract 101 commands / 106 references / 141
artifacts, gate shape c9adcf85; registry approval 2dc6c3a3; the runtime
config schema baseline equals the schema at 8210d48.

Verified here: types, lint, architecture, adapter inventory, CI contract,
i18n, design system, diagnostics, browser security, dev release manifest,
TechLog contract and build pass; 220 component, 155 integration, 15
contract, 418 TechLog, 43 reference-feature, 18 recipe and 46
release-coherence tests pass, and 2381 of 2383 unit tests. Reproduced at
8210d48 first and unchanged: check:registries (byte-identical),
test:runtime-schema, verify:documentation. Brought by the template and
escalated rather than suppressed: check:request-fanout on TechLog's cursor
pagination, check:remediation-ledger (fails upstream too), the shared-chunk
hash test, and the registry-dependent sample removal and second-feature
tests. Playwright suites were not run.

Full record, the five open questions and the follow-ups in
docs/operations/template-sync-2026-09-29.md.

(cherry picked from commit b2170cf265dea45dc9cc05d3c61e627e97f31cdb)
2026-11-12 08:28:54 +09:00

7.5 KiB

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 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):

{
  "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.