# 프론트엔드 애플리케이션 기반(Frontend Application Foundation) 이 repo를 최소한의 React 프로젝트 템플릿으로 보지 않는다. 독립된 범용 SDK도 아니다. 아키텍처에서 맡는 역할은 다음과 같다: > Frontend Application Foundation = 시작 골격(Starter / Composition Skeleton) + 재사용 capability 플랫폼(Reusable Capability Platform) 시작 골격 쪽은 bootstrap, 라우팅, provider, 프로젝트 규약, feature를 만들어 주는 `create:feature` 명령을 맡는다. 예시 feature는 싣지 않는다. capability 쪽은 재사용할 기술 문제를 맡는다. HTTP 실행, Server State, 인증 경계, IndexedDB/OPFS, Cache Storage, realtime, 브라우저 RPC, 전송(transfer), 진단 같은 것이다. 정교한 capability의 비용은 제품 feature가 그 내부의 정교함을 몰라도 될 때만 받아들일 수 있다. ## 하이브리드 아키텍처 `src/`에는 최상위 폴더가 아홉 개 있다. 설명은 [계층 계약](./layers.md)의 표와 같다. 그 문서는 모든 import 규칙도 적는다. platform 코드는 가로(수평)로 놓인다: - `src/bootstrap` — 조립 루트: 런타임 설정, 구체 adapter 생성, React 마운트 - `src/presentation` — 범용 UI와 inbound adapter: 라우트, 레이아웃, 디자인 시스템, 페이지, provider - `src/adapters` — application 포트를 구현하는 재사용 capability 런타임: HTTP, 인증, 저장소, query cache, telemetry, worker 등 - `src/application` — 범용 use case, 포트, 정책, view-model - `src/contracts` — 여러 계층·worker·빌드와 릴리스 스크립트가 같이 읽는 공용 어휘와 registry - `src/platform` — 어느 폴더든 쓸 수 있는 제품 중립 기본 요소: 예산, 실행 context, 복원력, telemetry 파이프라인, 오류 envelope, 릴리스 정합성 소유 선언이 feature를 배포 단위로 묶는다: - `src/apps` — 배포 단위 앱: 각 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다 - `src/contexts` — bounded context: 각 `context-module.ts`가 소속 앱, 라우트 루트, 기능 예산을 선언한다 제품 비즈니스 코드는 세로(수직)로 놓인다: - `src/features` — 지울 수 있는 수직 slice(`src/features//{domain,application,contracts,adapters,presentation}`)와 설치된 기능 목록(`src/features/*.ts`) feature 하나 안에는 다음이 있다: - `features//domain` - `features//application` - `features//contracts` - `features//adapters` - `features//presentation` 의존성 모델은 다음과 같다: 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 use case는 platform adapter를 절대 import하지 않는다. 범용 바인딩은 feature의 adapter·조립 이음매(seam)에서 일어난다. ## capability별 타입 바인딩 HTTP, storage, realtime, transfer를 하나의 범용 `Repository` 추상화로 묶지 않는다. 넷은 lifecycle과 실패의 의미가 서로 다르다. 재사용 capability 경계는 다음으로 조립한다: - 범용 입력·출력 타입, - feature가 소유한 mapper 또는 codec, - feature가 고른 정책, - capability 전용 runtime 하나. HTTP 경로가 첫 구체 예다. `src/adapters/http/feature-http-binding.ts`가 전송과 결과의 정규화를 맡는다. `create:feature`가 만든 feature가 내놓는 것은 다음뿐이다: - operation ID, - route ID, - 정확한 요청 입력 타입, - 정확한 성공 값 타입, - wire 형식을 domain으로 바꾸는 mapper. 그래서 feature gateway는 timeout, 취소, 전송 실패, 인증 실패, contract 위반 투영을 다시 구현하지 않는다. storage, realtime, transfer는 실제 feature에서 반복이 생겨 필요가 드러난 뒤에야 자기 타입 바인더를 가질 수 있다. 이 셋을 HTTP 추상화에 억지로 끼우면 안 된다. ## 직접 만드는 adapter라는 탈출구 제품 feature는 재사용 capability가 비즈니스 요구를 지켜 줄 때 그 capability를 쓴다. platform contract 때문에 비즈니스 모델을 바꾸거나 약하게 해야 한다면, feature는 같은 application port 뒤에 직접 만든 outbound adapter를 구현한다. 아키텍처 경계는 그대로다. platform 재사용은 선택이다. ## feature 설치 feature는 자기 contract, runtime, adapter contribution을 소유한다. 중앙의 설치 목록(catalog)은 모으는 지점일 뿐이다: - `installed-product-manifest.ts`: 어떤 제품 feature를 컴파일하고 고르는지 - `installed-feature-contracts.ts`: feature 선언에서 boot 시점 contract(라우트, 라우트 runtime contract, 무효화)를 모은다 - `installed-feature-adapters.ts`: 활성 feature마다 하나씩 있는 application-input loader. router가 그 feature의 라우트에 들어갈 때 실행된다(15-01) - `installed-contract-contributions.ts`: 선언된 contract 패키지와, HTTP executor가 해석할 때 쓰는 registry. feature가 로드될 때 채워진다 - `installed-feature-runtime-registries.ts`: 모든 runtime 쪽 절반을 불러와 contract contribution, 거기서 투영한 FE-REG-API 행, FE-REG-SCHEMA registry를 조립한다. platform 개요 페이지가 제목을 그린 뒤 이 파일을 부른다 (1103/15-01). boot는 절대 부르지 않는다 - `loaded-feature-runtimes.ts`: 같은 registry를 모듈 상수(top-level await)로 둔 것. Node 스크립트, 테스트, registry 관리(governance)가 쓴다. `src` 아래 어떤 코드도 이 파일을 import하면 안 된다 (`boot-does-not-load-every-feature-runtime`) feature 전용 조립은 그 feature 아래에 둔다. 중앙 목록에 feature별 분기 로직을 늘리면 안 된다. adapter contribution은 자기가 쓰는 platform capability를 `needs`로 선언한다. `src/features/feature-adapter-contribution.ts`의 범용 contribution 이음매가 그 목록에서 context를 만든다. 그래서 HTTP만 쓰는 feature는 IndexedDB에 닿지 못한다. IndexedDB만 쓰는 feature는 HTTP executor를 받지 않는다. 이 이음매는 `featureId -> ApplicationFeatureInputs[featureId]` 관계도 contribution을 정의하는 자리에서 묶는다. 마지막에 목록을 타입 캐스트해서 그 관계를 되찾지 않는다. contribution은 `defineFeatureAdapterContribution()`을 거쳐야만 조립할 수 있다. 이 factory는 `composeFeatureAdapterInputs()`가 요구하는 비공개 contribution brand를 붙인다. 겉으로 보이는 필드가 같은 날 객체는 TypeScript가 거부하고, runtime에서도 다시 검사한다. 음성 타입 fixture `invalid-direct-feature-composition.ts`가 FE-GATE-003에 들어 있다. 그래서 composer를 직접 불러 이 권한을 우회할 수 없다. IndexedDB를 쓰는 feature에서는 `createIndexedDbRepositoryProvider()`가 조립 헬퍼다. 이 헬퍼는 feature가 소유한 repository 식별자를 타입이 붙은 `IndexedDbRepositoryPort` 인스턴스에 연결한다. 범용 storage repository를 만들지 않는다. dataset·migration·lifecycle 정책을 feature로 옮기지도 않는다. 지금 repo에는 실행 가능한 contribution 모양이 둘 있다: - `create:feature`가 만드는 feature: `needs: ["http", "telemetry"]` - Local Draft consumer: `needs: ["indexedDb"]` Local Draft는 두 번째 capability 모양을 증명하는 테스트 fixture(`tests/fixtures/indexeddb-consumer`)다. 제품의 feature가 아니다. 그 browser-capability 테스트는 실제 `createIndexedDbRuntime`과 브라우저 자체 IndexedDB 위에서 feature를 조립한다. 이 이음매가 메모리 안 contract fixture에만 묶이지 않는다는 것을 이 테스트가 증명한다. bootstrap은 `indexedDb`를 만들지 않는다. IndexedDB는 골라야 켜지는(opt-in) 참조 runtime이다(`config/recipes/frontend-capability-recipes.json`의 `productionComposition: false`). 조립 예시는 `recipes/frontend-capabilities/indexeddb-feature-capability.ts`다 (`createLocalDraftIndexedDbCapability`. 이 함수는 `tests/recipes/indexeddb-feature-capability.test.ts`가 실행해 본다). `needs: ["indexedDb"]`인 feature를 설치하는 제품은 이 예시를 복사한다. 그리고 제품이 소유한 `src/bootstrap/product-composition.ts`에서 `indexedDb`를 돌려준다. 그 전까지는 `src/bootstrap/runtime-adapters.ts`의 feature capability가 앱 타입체크에서 실패한다. 그리고 `composeFeatureAdapterInputs()`가 `feature needs indexedDb, which the host did not provide`로 조립을 거부한다. 제품이 다른 capability를 더하는 곳도 같은 파일이다. 제품 인증 profile의 credential provider를 더하는 곳도 이 파일이다. capability의 타입은 제품이 소유한 `src/features/product-capabilities.ts`에 둔다 (`ProductFeaturePlatformCapabilities`. `FeaturePlatformCapabilities`가 이 타입을 확장한다). 그래서 feature를 보는 모든 타입체크 프로그램이 이 타입도 본다(`tests/unit/product-extension-typecheck.test.ts`). composition root는 다음 순서를 지킨다: scope fence, `ANONYMOUS` profile, 제품 provider, session, 다시 scope fence(`tests/unit/runtime-adapters-credential-order.test.ts`). session을 직접 소유하는 제품(session이 httpOnly 쿠키인 BFF)은 같은 파일의 `composeProductSessionOwner`에서 자기 session owner를 돌려준다. 이 함수는 `AUTH_MODE`가 `external`일 때만 불린다. 불릴 때는 `http`가 생기기 전에 가장 먼저 불리고, host의 `__CA_FRONTEND_AUTH_OWNER__`보다 앞선다. `null`을 돌려주면 session을 그 전역 값에 맡긴다. 이 함수의 context (`src/bootstrap/product-session-owner-context.ts`)에는 다음이 들어 있다: 교환 전체에 deadline 하나를 거는 `fetch`, 로그인 redirect에 쓸 페이지, 그 redirect에만 쓰는 페이지의 session storage, `readCookie`. 제품 인증 profile, runtime-config 키, 그 키의 FE-REG-ENV 행은 `src/contracts/product-contracts.ts`에 둔다. 각각 같은 검사를 거쳐 템플릿의 registry에 합류한다 (`tests/unit/product-composition-fixture.test.ts`). ## presentation 소비 표면 `ApplicationProvider`는 계속 presentation의 composition root다. 하지만 새 소비 코드는 루트 `ApplicationApi` service locator를 뒤져서 기능을 찾아가면 안 된다. `src/presentation/providers/application-provider.tsx`의 좁은 hook을 쓴다: - `useApplicationSession` - `useApplicationPreferences` - `useApplicationDiagnostics` - `useApplicationRuntime` - `useApplicationRecovery` - `useApplicationFeature` `useApplication`은 deprecated된 호환용 탈출구로만 남아 있다. ## 정식 import 경로 새 feature 코드는 깊은 runtime 모듈 대신 capability의 공개 진입점을 쓴다. HTTP의 정식 경로는 `src/adapters/http/index.ts`다. 옮기는 기간에는 호환용 재수출이 있을 수 있다. 하지만 그 경로에는 호환용· deprecated 경로라는 표시를 해야 한다. 그리고 끝없이 커지는 공개 barrel로 늘어나면 안 된다. ## 정책 소유 중복은 문법이 겹치는 비율이 아니라 소유로 판단한다. 가까이 두는 편이 감사하기 쉬우면 작은 로컬 검증기는 중복으로 남겨도 된다. 비즈니스 정책이나 동시성 정책은 owner가 하나여야 한다. 예를 들어 참조 create mutation은 정의 ID, 멱등성 요구, 중복 정책, 무효화 정책을 feature가 소유한 정의 하나에 둔다. 사용하는 자리마다 묶는 것은 `scope`와 `execute`뿐이다. ## runtime 분해 규칙 큰 runtime 파일을 줄 수로 나누지 않는다. 경계에 자기만의 상태 기계, lifecycle owner, 실패 모델, 보상·복구 책임이 있으면 그 경계를 떼어 낸다. 떼어 낼 후보 이음매는 다음과 같다: - 연결·열기·업그레이드 lifecycle, - 트랜잭션 소유, - migration 상태 기계, - 재연결·backoff와 heartbeat, - 구독 소유, - 재시도·deadline·취소 소유, - 정산(settlement)·조정(reconciliation)·정리(cleanup). 응집된 2,000줄짜리 상태 기계는 한데 둬도 된다. lifecycle owner가 여럿인 300줄짜리 파일이 더 나은 분리 후보다. ### 지금 runtime 경계 점검 지금 있는 큰 runtime 목록을 이 규칙으로 점검했다. - IndexedDB는 여전히 크다. 하지만 연결, 트랜잭션, migration, 유지보수, 실패 변환은 이미 owner·모듈이 따로 있다. - 이어 올리기(resumable upload)는 이미 runtime 정책, checkpoint 저장, HTTP 제어 평면 전송, 조각(part) 실행, 취소, mutation 잠금을 나눠 두었다. - realtime은 이미 재연결 정책·조정자, 이벤트 codec·소비자, 스트림 조정을 나눠 두었다. - OPFS는 브라우저 runtime, journal, byte-store, 정책, worker 프로토콜·runtime 책임으로 나뉘어 있다. - HTTP V3는 재시도 가능 여부와 backoff를 실행 상태 기계 안에서 여전히 소유하고 있었다. 그래서 그 책임을 `src/adapters/http/http-retry-lifecycle.ts`로 옮겼다. 다른 runtime은 줄 수만 보고 나누지 않았다. ## 소비 품질 지표 추상화를 하나 더 들이기 전에, 실제 feature 사용 사례 여럿을 구현하거나 모델링하고 다음을 잰다: - feature가 소유한 adapter LOC, - 반복되는 platform 접착 코드(glue), - feature에 드러나는 platform 내부 타입 수, - 중앙 목록 수정 횟수, - 평범한 query/command 하나에 바뀌는 파일 수, - 브라우저·네트워크 기본 API가 feature로 새어 나오는지. 목표로 하는 feature 개발 경로는 다음과 같다: 1. domain 타입과 불변식, 2. use case, 3. port, 4. 전송·저장 schema와 mapper/codec, 5. capability 바인딩, 6. presentation controller/page. 제품 feature는 재시도 스케줄러, abort 소유, 효과 확실성(effect-certainty) 장치, 트랜잭션 lease, 재연결 조정자, OPFS journal, provider lifecycle을 몰라도 돼야 한다. 실행 가능한 REST·IndexedDB 소비 기준선은 [`capability-consumer-experience.md`](./capability-consumer-experience.md)에 적혀 있다. contract를 어디에 둘지와, 전역에 둘지 owner 가까이 둘지 점검한 결과는 [`contract-ownership.md`](./contract-ownership.md)에 적혀 있다. ## 검증 경로 제품 개발 검증, capability 검증, release 보증은 일부러 나눠 두었다. [`docs/testing/taxonomy.md`](../testing/taxonomy.md)를 본다. host 수준 CI runner 테스트는 `tests/unit`이 아니라 `tests/system`에 둔다. 재사용 capability의 소비 contract는 `tests/contract`에 둔다.