문제
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.
301 lines
13 KiB
Markdown
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`.
|