Files
clean-architecture-frontend…/docs/architecture/frontend-application-foundation.md
DongHyeonka 7a9aefdf25 feat(docs): 문서 체계 검사를 verify:documentation에 더하고 입구 문서를 고친다
문제: 프론트 문서 체계는 백엔드와 다르다. docs/README.md는 "README와
입구 문서는 영어"라고 정해 두어 2026-11-07 소유자 결정(살아 있는
문서는 본문까지 한국어)과 반대이고, 기록의 머리 블록·언어·숫자 복사를
보는 검사가 없다. verify:documentation은 docs/README.md 1절이 링크한
문서의 경로만 본다.

고른 방법: 백엔드 scripts/check-docs.py의 규칙(language, head, number,
map, readme, style)을 같은 이름·문턱으로 TypeScript로 옮겨
scripts/lib/docs-system.ts에 두고 verify:documentation(FE-GATE-017)이
부르게 한다. 참조 검사는 지금 있는 것을 그대로 쓰고 대상만 살아 있는
문서 전부로 넓힌다. FE-GATE-017 job은 workflow_dispatch(documentation
단계)에서만 돌아서, PR에서 실패하도록 merge 단계 FE-GATE-005의
documentation-readiness 시험이 이 repo를 그대로 두고
verify:documentation을 한 번 돌린다.
- 버린 안: 새 게이트나 package script를 더하는 것. config/ci(정리
  3단계·CI 세션 범위)와 CI 계약의 개수·해시를 건드린다.
- 버린 안: check-docs.py를 그대로 복사하는 것. 프론트 CI 이미지와
  도구는 Node뿐이고, 참조 검사(짝 백엔드 pin, 지운 샘플, 생성 산출물)는
  이미 TS에 있다.
- 예외 목록 scripts/docs-system-exceptions.txt는 줄기만 한다(줄마다
  FROZEN 지문). 이 커밋의 줄은 아직 옮기지 않은 문서의 기준선이고 뒤
  번역 커밋들이 지운다.
- docs/README.md를 모든 문서 폴더를 덮는 지도와 수명·언어·머리 블록·
  검사 규칙으로 다시 쓰고, 루트 README.md를 docs-system.md 6.1절의 필수
  절 순서로 한국어로 다시 쓴다. README의 src 폴더 설명은 layers.md 표와
  글자가 같아야 하므로 layers.md·overview.md·foundation.md를 같이 옮긴다.
- README 「복사한 뒤 지워도 되는 것」을 읽는 정규식과, 문서를 바꿔 넣는
  테스트의 기대 문자열을 새 한국어 문장으로 고친다. 검사기는 기록
  폴더 이름을 적지만 지운 사본에서도 통과하므로
  deletable-history-documents 테스트의 검사 대상에서 뺀다(그 이유를
  테스트와 검사기 시험에 적었다).

위험: 파생 서비스가 이 변경을 받으면 자기 살아 있는 문서가 영어일 때
verify:documentation이 실패한다. CHANGELOG에 「먼저 할 일」로 적는다.
review-evidence.md는 다른 작업 공간의 경로를 적은 사본이라 참조·숫자
검사에서 뺐다(HISTORY_HOLDERS).

검증: tests/unit/docs-system.test.ts(조건마다 실패 입력),
documentation-readiness·template-feature-removal-documents·
deletable-history-documents 시험, verify:documentation을 desktop에서 돌렸다.
2026-11-08 21:57:39 +09:00

15 KiB

프론트엔드 애플리케이션 기반(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/에는 최상위 폴더가 아홉 개 있다. 설명은 계층 계약의 표와 같다. 그 문서는 모든 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/<id>/{domain,application,contracts,adapters,presentation})와 설치된 기능 목록(src/features/*.ts)

feature 하나 안에는 다음이 있다:

  • features/<feature>/domain
  • features/<feature>/application
  • features/<feature>/contracts
  • features/<feature>/adapters
  • features/<feature>/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<TKey, TValue> 추상화로 묶지 않는다. 넷은 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 <id> 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에 적혀 있다. contract를 어디에 둘지와, 전역에 둘지 owner 가까이 둘지 점검한 결과는 contract-ownership.md에 적혀 있다.

검증 경로

제품 개발 검증, capability 검증, release 보증은 일부러 나눠 두었다. docs/testing/taxonomy.md를 본다.

host 수준 CI runner 테스트는 tests/unit이 아니라 tests/system에 둔다. 재사용 capability의 소비 contract는 tests/contract에 둔다.