문제: 프론트 문서 체계는 백엔드와 다르다. 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에서 돌렸다.
98 lines
6.6 KiB
Markdown
98 lines
6.6 KiB
Markdown
# 아키텍처 개요
|
|
|
|
이 Mermaid 그림은 repo 안에서 구현을 옮겨 그린 투영(projection)이다.
|
|
`PASS_SCOPED` 리뷰 증거는 `review-ledger.json`이 가리키는 정본 draw.io
|
|
도식에 적용된다. 이 파일을 고친 내용에 저절로 적용되지는 않는다.
|
|
|
|
`src/`에는 최상위 폴더가 아홉 개 있다. 설명은 [계층 계약](./layers.md)의
|
|
표와 같다. 그 문서는 모든 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할 수 있다. 그림에는 주 경로만 그렸다.
|
|
|
|
```mermaid
|
|
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 안에 둔다:
|
|
|
|
```mermaid
|
|
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는 그 증거를 지어내지 않는다. 구현 세부와
|
|
프로젝트 통합 작업은 아래 문서를 본다:
|
|
|
|
- [프론트엔드 platform capability 리뷰](../design/2026-07-26-frontend-platform-capability-review-design.md)
|
|
- [프론트엔드 port, adapter, 경계](../design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md)
|
|
- [API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
|
|
- [Protobuf 브라우저 전송과 REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
|
|
- [백엔드 API와 Server State 인계 계약](./backend-api-and-server-state-contract.md)
|
|
- [TypeScript, 상태, 데이터 흐름](../design/2026-07-26-typescript-state-and-data-flow-design.md)
|
|
- [라우팅, 페이지, 패턴](../design/2026-07-26-routing-pages-and-patterns-design.md)
|
|
- [브라우저 데이터 capability 완료 장부(ledger)](../design/2026-07-30-browser-data-capability-completion-ledger-design.md)
|
|
- [브라우저 파일과 origin 저장소](../design/2026-07-27-browser-file-and-origin-storage-design.md)
|
|
- [클라이언트 캐시와 저장소](../design/2026-07-28-client-cache-and-storage-design.md)
|
|
- [Realtime 이벤트, Web Push, 상한을 둔 polling](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)
|
|
- [Presigned 전송과 Image CDN](../design/2026-07-30-presigned-transfer-and-image-cdn-design.md)
|
|
- [서버 파일 capability 인프라](../design/2026-07-28-server-file-capability-infrastructure-design.md)
|
|
- [프론트엔드 platform 구현 로드맵](../design/2026-07-26-frontend-platform-implementation-roadmap-design.md)
|