# 아키텍처 개요 이 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//{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)