Files
clean-architecture-frontend…/docs/architecture/frontend-application-foundation.md
T
DongHyeonka ece944d08b feat(bootstrap): 제품 세션 owner와 FE-REG-ENV 행을 제품 파일로 받는다 (1101/09-02)
문제
09-02(da1e128) 뒤에도 tech-log가 하는 일 두 가지는 템플릿 파일을 고쳐야
한다(리뷰 1101 README 14.4 "09-02 이식").
- 제품 설정 키의 FE-REG-ENV 행: tech-log는 템플릿 src/contracts/env.ts의
  ENV_REGISTRY에 TECH_LOG_STUDIO_SOURCE·TECH_LOG_PUBLIC_SOURCE 행을 직접
  넣었다(tech-log env.ts:63-70).
- 부트 전 BFF 세션 owner: 세션이 httpOnly 쿠키라 owner가 백엔드에 묻는다.
  tech-log는 템플릿 create-runtime-composition.ts에서 AUTH_MODE external이고
  Studio가 HTTP일 때 createRuntimeAdapters 전에 host 전역
  __CA_FRONTEND_AUTH_OWNER__에 owner를 넣는다(:2, :36-52,
  bff-session-owner.ts:188-194). composeProduct는 http가 생긴 뒤에 불리고
  http는 세션이 필요해서 이 일을 받을 수 없다.

고른 방법
- product-contracts.ts에 PRODUCT_ENV_REGISTRY를 빈 값으로 둔다. env.ts는
  PRODUCT_REST_AUTH_PROFILES·PRODUCT_RUNTIME_CONFIG_FIELDS와 같은 모양으로
  그 행을 ENV_REGISTRY에 합친다. 템플릿 키와 이름이 겹치면 모듈 로드 때
  throw한다. check:registries와 vite.config.ts가 같은 객체를 읽으므로 제품
  행도 같은 필드 검사를 받는다. 행을 더하기만 하면 additive라 기준선을
  고치지 않는다(실험: 제품 행 2개 → compatibility=additive PASS, 허용 밖
  classification → 실패).
- product-composition.ts에 composeProductSessionOwner(context)를 둔다.
  템플릿은 null을 돌려준다. 조립 루트가 세션을 고르기 전에, AUTH_MODE가
  external일 때만 부른다. 제품 owner가 host 전역보다 먼저다. null이면
  지금처럼 host 전역, 없으면 unavailable이다. demo 모드는 묻지 않는다.
  context는 config와 fetcher뿐이다(http 전이라 capability가 없다).

버린 대안
- owner를 composeProduct 반환값에 넣기: http가 세션을 쓰므로 순서가 꼬인다.
- 제품이 host 전역에 계속 넣게 두고 문서화: 부트 전 훅이 템플릿 파일
  (create-runtime-composition.ts)에 남는다.
- FE-REG-ENV 행을 PRODUCT_RUNTIME_CONFIG_FIELDS에서 자동으로 만들기: zod
  필드로는 classification·required를 알 수 없다.
- 행 타입·도우미를 product-contracts.ts가 env.ts에서 import: 순환 의존
  (no-circular-dependencies)이다. 타입 검사는 env.ts의 대입에서 한다.

위험·한계
- product-composition.ts에 export가 하나 늘었다. 이 파일을 이미 복사한
  제품은 composeProductSessionOwner를 더해야 한다. da1e128은 아직 main에
  없고 두 다운스트림 모두 받지 않았다.
- 제품 행을 as const 없이 쓰면 phase가 string으로 넓어져 tsc 오류가
  env.ts:78(템플릿 파일)에서 난다. 메시지에 키 이름은 나온다. product-
  contracts.ts 주석에 as const를 적었다.
- 제품 설정 키에 FE-REG-ENV 행이 있는지 요구하는 검사는 여전히 없다.
  템플릿 키도 RELEASE_ID·BUILD_ID는 행이 없어서 이 변경에서 넣지 않았다.
- 제품 owner가 throw하면 createRuntimeAdapters가 실패해 부트 실패
  화면이 된다. composeProduct와 같다.
- tech-log의 owner는 subject를 null로 돌려준다(템플릿 동작대로 매 변경
  fence). 이 변경과 무관하다.

검증
- RED: tests/unit/product-composition-fixture.test.ts 13건 중 3건 실패.
  FE-REG-ENV 행 없음, external 모드 세션이 authenticated가 아니라
  integration-failed, env 이름 충돌을 거절하지 않음.
- GREEN: 같은 파일 13/13, runtime-adapters-credential-order 7/7(mock에
  composeProductSessionOwner: () => null 추가).
- fixture는 vi.mock 대상이 제품 소유 두 파일(머리 주석 "Product-owned.")과
  설치 기능 seam 두 개뿐이고, tech-log가 고친 템플릿 파일 4개(env.ts,
  create-runtime-composition.ts, runtime-config-schema.ts,
  runtime-adapters.ts)는 대상이 아님을 이 파일의 소스를 읽어 확인한다.
- 회귀: tests/unit·contract·runtime-schema·integration 198 files 2861
  tests 통과(heavy lock 아래).
- tsc app·node·test 통과, 바꾼 파일 eslint 통과, check:registries PASS
  (compatibility=none, 재승인 불필요), verify:documentation PASS_SCOPED,
  check:adapter-inventory PASS.
- 초기 JS gzip 202,770 → 202,931 B(+161, 예산 204,800). 같은 방법(dist
  manifest의 초기 파일 26개, gzipSync 기본 레벨)으로 전·후를 쟀다.
- 미실행: check:architecture(pnpm 필요), test:component, e2e.
2026-11-03 20:23:14 +09:00

301 lines
13 KiB
Markdown

# 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](./layers.md), 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 returns `indexedDb` from the
product-owned `src/bootstrap/product-composition.ts`. Until it does, the feature
capabilities in `src/bootstrap/runtime-adapters.ts` fail the app typecheck, and
`composeFeatureAdapterInputs()` rejects the composition with
`feature <id> needs indexedDb, which the host did not provide`.
The same file is where a product adds any other capability (it augments
`FeaturePlatformCapabilities`) and the credential provider for a product auth
profile. The composition root keeps the order: scope fence, `ANONYMOUS`
profile, product provider, session, scope fence again
(`tests/unit/runtime-adapters-credential-order.test.ts`). A product that owns
the session itself (a BFF whose session is an httpOnly cookie) returns its
session owner from `composeProductSessionOwner` in the same file. It is asked
first, before `http` exists, only when `AUTH_MODE` is `external`, and it comes
before the host's `__CA_FRONTEND_AUTH_OWNER__`; `null` leaves the session to
that global. Product auth profiles, runtime-config keys and the keys'
FE-REG-ENV rows go in `src/contracts/product-contracts.ts`; each joins the
template's registry under the same checks
(`tests/unit/product-composition-fixture.test.ts`).
## 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`](./capability-consumer-experience.md).
Contract placement and the global-vs-owner-local audit are recorded in
[`contract-ownership.md`](./contract-ownership.md).
## Verification paths
Product-development verification, capability verification and release assurance
are intentionally separate. See
[`docs/testing/taxonomy.md`](../testing/taxonomy.md).
Host-level CI-runner tests belong to `tests/system`, not `tests/unit`.
Reusable capability consumer contracts belong to `tests/contract`.