Files
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

6.6 KiB

아키텍처 개요

이 Mermaid 그림은 repo 안에서 구현을 옮겨 그린 투영(projection)이다. PASS_SCOPED 리뷰 증거는 review-ledger.json이 가리키는 정본 draw.io 도식에 적용된다. 이 파일을 고친 내용에 저절로 적용되지는 않는다.

src/에는 최상위 폴더가 아홉 개 있다. 설명은 계층 계약의 표와 같다. 그 문서는 모든 import 규칙도 적는다:

  • src/bootstrap — 조립 루트: 런타임 설정, 구체 adapter 생성, React 마운트
  • 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)
  • 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, 릴리스 정합성

화살표는 import하는 폴더에서 import되는 폴더로 향한다. 모든 폴더는 contracts와 platform도 import할 수 있다. 그림에는 주 경로만 그렸다.

flowchart LR
  Bootstrap[bootstrap / composition root] --> Presentation[presentation]
  Bootstrap --> Adapters[adapters]
  Bootstrap --> Features[features]
  Presentation --> Shell[app shell and route surfaces]
  Shell --> Providers[session and theme providers]
  Presentation -- app router only --> Apps[apps]
  Apps --> Contexts[contexts]
  Contexts --> Features
  Features --> Application[application]
  Presentation --> Application
  Adapters --> Application
  Application --> Contracts[contracts]
  Contracts --> Platform[platform]

강제되는 의존성 규칙은 안쪽을 향한다. presentation은 application use case를 부른다. adapter는 application port를 구현한다. 구체 adapter는 composition root만 고른다. domain 코드는 각 feature 안에 있다. contract registry는 라우트, API operation, 환경 값, 저장소 키, 오류, query, telemetry, release 토큰의 이름을 정하는 출처다. 설치된 feature contribution이 이 registry를 확장한다. 그래도 범용 application이나 router가 구체 feature 구현을 import하게 되지는 않는다.

ports-and-adapters 용어로 말하면 presentation이 지금의 inbound adapter이고, adapters에 지금의 outbound 구현이 있다. 운영 조립(production composition)은 React에 application input API를 내보인다. 구체 output port는 application closure 안에 둔다:

flowchart LR
  Driver[User, route, browser event] --> Inbound[React inbound adapter]
  Inbound --> Input[Application input API]
  Input --> UseCase[Use cases]
  UseCase --> Output[Application output ports]
  Output --> Outbound[HTTP, auth, storage, query, telemetry adapters]
  Bootstrap2[Composition root] -. selects and injects .-> Input
  Bootstrap2 -. selects and injects .-> Outbound

실행할 라우트 트리는 runtime 설정 검사와 release manifest 정합성 검사가 통과한 뒤에만 마운트된다. ApplicationProvider는 조립된 application API를 받는다. 구체 session·storage·telemetry·진단·release port는 feature 페이지에 돌려주지 않는다. TanStack Query는 presentation query adapter 뒤에 격리된다. 다만 그 provider는 React 인프라로 남는다. module augmentation으로 확장한 feature registry가 설치된 feature마다 닫힌 ID와 정확한 입력 타입을 준다.

라우트 contract·codec, route-input provider, lazy runtime 모듈은 서로 다른 모듈이다. 그래서 feature 페이지는 자신을 불러오는 router를 import하지 않는다. 예상된 application 실패는 공용 Result/AppFailure contract를 쓴다. architecture gate는 자체 그래프로 TS/TSX import를 분석한다(규칙은 .dependency-cruiser.json에 있다. dependency-cruiser 자체는 TypeScript 7을 파싱하지 못해 돌리지 않는다). gate는 로컬 JavaScript 계열 specifier와 실행 가능한 JavaScript 계열 파일을 거부한다. 해석되지 않은 import, 파싱 실패, 금지된 계층 간선, 순환이 있으면 실패한다. 프로젝트가 맡을 일이 남아 있다. 실제 hosting, identity, telemetry, 취약점 점검, 서명 provider를 고르고 검증하는 일이다. 그리고 고른 선택 capability마다 백엔드·provider·브라우저·운영 증거를 갖추는 일이다. 이 repo는 그 증거를 지어내지 않는다. 구현 세부와 프로젝트 통합 작업은 아래 문서를 본다: