Files
clean-architecture-frontend…/docs/architecture/frontend-application-foundation.md
T
DongHyeonka 61baf96682 fix(docs): 입구 문서를 실제 src 폴더 9개와 규칙 이름에 맞추고 검사한다 (14-03)
문제: 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
2026-11-03 00:54:44 +09:00

12 KiB

Frontend Application Foundation

This repository is not treated as a minimal React project template and it is not an independent general-purpose SDK. Its architectural role is:

Frontend Application Foundation = Starter / Composition Skeleton + Reusable Capability Platform

The starter side owns bootstrap, routing, providers, project conventions and a removable reference feature. The capability side owns reusable technical problems such as HTTP execution, Server State, authentication boundaries, IndexedDB/OPFS, Cache Storage, realtime, browser RPC, transfer and diagnostics.

The cost of a sophisticated capability is acceptable only when product features do not have to understand that internal sophistication.

Hybrid architecture

src/ has nine top-level folders. The descriptions match the table in the layer contract, which also names every import rule.

Platform code is horizontal:

  • src/bootstrap — the composition root: runtime configuration, concrete adapter construction and the React mount
  • 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

Ownership declarations group features into deployable units:

  • 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

Product business code is vertical:

  • src/features — removable vertical slices (src/features/<id>/{domain,application,contracts,adapters,presentation}) and the installed-feature catalogs (src/features/*.ts)

Inside one feature:

  • features/<feature>/domain
  • features/<feature>/application
  • features/<feature>/contracts
  • features/<feature>/adapters
  • features/<feature>/presentation

The dependency model is:

Domain / Use case
        |
        | owns
        v
    Business port
        ^
        | implements / binds
        |
Feature-owned adapter binding
        |
        | generic type + mapper/codec + policy
        v
Reusable capability runtime
        |
        v
Browser / network / native API

A use case never imports a platform adapter. Generic binding happens in the feature adapter/composition seam.

Capability-specific typed bindings

Do not introduce one universal Repository<TKey, TValue> abstraction for HTTP, storage, realtime and transfer. Their lifecycle and failure semantics differ.

A reusable capability boundary is composed from:

  • generic input/output types,
  • feature-owned mapper or codec,
  • feature-selected policy,
  • one capability-specific runtime.

The HTTP reference path is the first concrete example. src/adapters/http/feature-http-binding.ts owns transport/outcome normalization. The reference feature contributes only:

  • operation ID,
  • route ID,
  • exact request input type,
  • exact success value type,
  • wire-to-domain mapper.

The feature gateway therefore does not reimplement timeout, cancellation, transport failure, authentication failure or contract-violation projection.

Storage, realtime and transfer may gain their own typed binders only after actual feature repetition demonstrates the need. They must not be forced through the HTTP abstraction.

Custom adapter escape hatch

A product feature uses a reusable capability when the capability preserves the business requirement.

If a platform contract would require changing or weakening the business model, the feature implements a custom outbound adapter behind the same application port. The architecture boundary remains stable; platform reuse is optional.

Feature installation

A feature owns its contract, runtime and adapter contributions.

Central installed catalogs are aggregation points only:

  • installed-product-manifest.ts: which product features are compiled/selected
  • installed-feature-contracts.ts: boot-time contract aggregation (routes, route runtime contracts, invalidation) from the feature declarations
  • installed-feature-adapters.ts: application-input loaders, one per active feature, run when the router enters the feature's routes (15-01)
  • installed-contract-contributions.ts: declared contract packages and the registry the HTTP executor resolves against, filled as features load
  • installed-feature-runtime-registries.ts: loads every runtime half and composes the V2 API registries and contract contributions; the platform overview route calls it before it renders, the boot never does
  • loaded-feature-runtimes.ts: the same registries as module constants (top- level await) for Node scripts, tests and registry governance; nothing under src may import it (boot-does-not-load-every-feature-runtime)

Feature-specific composition belongs under the feature itself. Central catalogs must not grow feature-specific branching logic.

Adapter contributions declare the platform capabilities they consume through needs. The generic contribution seam in src/features/feature-adapter-contribution.ts derives the context from that list, so an HTTP-only feature cannot reach IndexedDB and an IndexedDB-only feature does not receive the HTTP executor. It also binds featureId -> ApplicationFeatureInputs[featureId] at the contribution definition site instead of recovering that relationship with a final catalog cast.

A contribution becomes composable only through defineFeatureAdapterContribution(). That factory adds the private contribution brand required by composeFeatureAdapterInputs(); a raw object with the same visible fields is rejected by TypeScript and checked again at runtime. The negative type fixture invalid-direct-feature-composition.ts is part of FE-GATE-003 so this authority cannot be bypassed by calling the composer directly.

For IndexedDB-backed features, createIndexedDbRepositoryProvider() is the composition helper that maps feature-owned repository identities to typed IndexedDbRepositoryPort instances. It does not create a universal storage repository or move dataset/migration/lifecycle policy into the feature.

The repository now has two executable contribution shapes:

  • Reference feature: needs: ["http"]
  • Local Draft feature: needs: ["indexedDb"]

Local Draft is a compiled architecture consumer used to prove the second capability shape; it is not added to the default product manifest. Its browser-capability test composes the feature over the real createIndexedDbRuntime and native IndexedDB, proving that this seam is not limited to an in-memory contract fixture.

The bootstrap does not build indexedDb: IndexedDB is an opt-in reference runtime (productionComposition: false in config/recipes/frontend-capability-recipes.json). The composition example is recipes/frontend-capabilities/indexeddb-feature-capability.ts (createLocalDraftIndexedDbCapability, exercised by tests/recipes/indexeddb-feature-capability.test.ts). A product that installs a feature with needs: ["indexedDb"] copies it and adds indexedDb to the feature capabilities in src/bootstrap/runtime-adapters.ts. Until it does, that object fails the app typecheck, and composeFeatureAdapterInputs() rejects the composition with feature <id> needs indexedDb, which the host did not provide.

Presentation consumer surface

ApplicationProvider remains the composition root for presentation, but new consumers should not navigate a root ApplicationApi service locator.

Use the narrow hooks in src/presentation/providers/application-provider.tsx:

  • useApplicationSession
  • useApplicationPreferences
  • useApplicationDiagnostics
  • useApplicationRuntime
  • useApplicationRecovery
  • useApplicationFeature

useApplication exists only as a deprecated compatibility escape hatch.

Canonical imports

New feature code should use capability public entry points rather than deep runtime modules. For HTTP the canonical path is src/adapters/http/index.ts.

Compatibility re-exports may exist during a migration window, but they must be marked as compatibility/deprecated paths and should not expand into an unbounded public barrel.

Policy ownership

Duplication is judged by ownership, not by syntax percentage.

Small local validators can remain duplicated when locality improves auditing. Business or concurrency policy must have one owner. For example the reference create mutation keeps definition ID, idempotency requirement, duplicate policy and invalidation policy in one feature-owned definition and binds only scope and execute per usage site.

Runtime decomposition rule

Large runtime files are not split by line count.

Extract a boundary when it has its own state machine, lifecycle owner, failure model or compensation/recovery responsibility. Candidate seams include:

  • connection/open/upgrade lifecycle,
  • transaction ownership,
  • migration state machine,
  • reconnect/backoff and heartbeat,
  • subscription ownership,
  • retry/deadline/cancellation ownership,
  • settlement/reconciliation/cleanup.

A cohesive 2,000-line state machine can remain together. A 300-line file with multiple lifecycle owners is a better extraction candidate.

Current runtime boundary audit

The current large-runtime inventory was reviewed using that rule.

  • IndexedDB remains large, but connection, transaction, migration, maintenance and failure translation already have separate owners/modules.
  • resumable upload already separates runtime policy, checkpoint persistence, HTTP control-plane transport, part execution, cancellation and mutation locking.
  • realtime already separates reconnect policy/coordinator, event codec/consumer and stream coordination.
  • OPFS is separated into browser runtime, journal, byte-store, policy and worker protocol/runtime responsibilities.
  • HTTP V3 still owned retry eligibility/backoff inside the execution state machine, so that responsibility moved to src/adapters/http/http-retry-lifecycle.ts.

No other runtime is split merely because of its line count.

Consumer quality metrics

Before adding another abstraction, implement or model multiple real feature uses and measure:

  • feature-owned adapter LOC,
  • repeated platform glue,
  • number of platform-internal types exposed to the feature,
  • central catalog edits,
  • files changed for one normal query/command,
  • whether native browser/network APIs leak into the feature.

The target feature-development path is:

  1. domain type and invariant,
  2. use case,
  3. port,
  4. transport/storage schema plus mapper/codec,
  5. capability binding,
  6. presentation controller/page.

A product feature should not need to know the retry scheduler, abort ownership, effect-certainty machinery, transaction leases, reconnect coordinator, OPFS journal or provider lifecycle.

The executable REST and IndexedDB consumer baselines are recorded in capability-consumer-experience.md. Contract placement and the global-vs-owner-local audit are recorded in contract-ownership.md.

Verification paths

Product-development verification, capability verification and release assurance are intentionally separate. See docs/testing/taxonomy.md.

Host-level CI-runner tests belong to tests/system, not tests/unit. Reusable capability consumer contracts belong to tests/contract.