ADR-0028: 아케이드 미니게임을 별도 레포 + Vercel 정적 배포로 두고, 앱 쉘이 cross-origin iframe + postMessage 브리지로 통합한다
- Status: Accepted
- Date: 2026-11-11
- 관련: HMH-10761 (이번 작업 티켓) · 게임 레포 koreanproptech/howmuchhome-arcade · 소스 mini-arcade(github.com/y9260000/mini-arcade)
Context
3D 미니게임 20여 종을 apps/app 의 /arcade 로 들여온다. 각 게임은 상대경로로 자기완결된 정적 HTML/JS
파일이다 — *.html 하나가 한 게임이고, Three.js·cannon-es 를 CDN(cdn.jsdelivr.net) 에서 ES module 로
import 하며, 공용 로직은 common.js, 에셋은 thumbs/·sounds/ 상대경로. 게임 로직은 전부 <canvas> 위
Three.js 렌더 루프다.
목표는 단순 이식이 아니다:
- 이 위에 서버 연동(랭킹, 실시간 대결) 을 얹는다. 백엔드는 이 레포가 이미 쓰는 Supabase(채팅 이관·
supabase-auth·커스텀 JWT) 가 유력하고, 대결은 실시간 네트워크를 지향한다. - 이 페이지는 native-app 안 웹뷰로 띄울 가능성이 높다(
apps/app은 이미 일부 경로가 네이티브 웹뷰로 쓰임 — ADR-0026). - 게임은 당분간 자주 업데이트되고, 비개발자(git·Vercel 사용 가능)가 직접 올린다.
마지막 제약이 호스팅 결정을 가른다: 게임을 모노레포(howmuchhome-web) 안에 두면 게임 콘텐츠 커밋마다
GitHub Actions·Vercel 트리거가 불필요하게 돌고(대부분 affected 아님으로 중단되지만 노이즈·큐 점유),
develop 히스토리가 게임 바이너리로 오염되며, 게임 한 줄 수정도 PR/CI/배포 파이프라인을 거친다.
그때 몰랐던/확정 안 된 것: 실시간 대결의 정확한 네트워크 모델, native 웹뷰에서 외부 CDN·중첩 iframe 로드의 신뢰성.
검토한 대안
| 대안 | 채택 안 한 이유 |
|---|---|
| A. 게임을 React/JSX 로 포팅 | 캔버스 게임은 React 트리 밖에서 도는 게 정상이라 포팅 이득이 없고, 게임마다 상류와 영구 분기된다. 서버가 필요한 건 게임 엔진이 아니라 바깥 쉘이다 |
B. 게임을 모노레포 apps/app/public/ 에 벤더링(초기 구현) | 잦은 게임 커밋이 모노레포 CI/Vercel 을 불필요하게 트리거하고 히스토리를 오염시킨다. 비개발자가 모노레포에 손대야 하고, 게임 업데이트가 앱 릴리즈 cadence 에 묶인다 |
| C. iframe 없이 게임을 쉘 문서에 직접 mount | 게임들의 전역 스코프·스타일·common.js 가 앱 전역과 충돌한다. 격리 가치가 크다 |
| D. 매니페스트(게임 목록)를 모노레포 쉘에 TS 로 들고 있기 | 게임 “추가” 때마다 모노레포를 또 건드려야 한다. 매니페스트도 게임 레포에 두고 쉘이 가져가야 완전 디커플링 |
Decision
세 층으로 나눈다. 게임 콘텐츠 변경이 절대 모노레포를 건드리지 않게 하는 것이 핵심 원칙이다.
- 게임 = 모노레포 밖 별도 레포 + Vercel 정적 배포.
koreanproptech/howmuchhome-arcade(게임*.html,common.js,thumbs/,sounds/, 매니페스트games.json, 헤더용vercel.json)를 Vercel 정적 프로젝트로https://arcade.howmuchhome.co에 배포. 게임 추가/수정 = 이 레포에 push → Vercel 자동 배포. 매니페스트까지 여기 있어 게임 추가도 모노레포 배포가 불필요하다. CDN 의존은 유지(현재 CSP 미강제). - 쉘 = 모노레포 apps/app(React). 허브
apps/app/src/app/arcade/page.tsx가${ARCADE_BASE}/games.json을 원격으로 가져와(ISR) 목록을 그리고, 플레이어play/[gameId]/_components/ArcadePlayer.tsx가${ARCADE_BASE}/${id}.html을 전체화면 iframe 으로 띄운다. 베이스 URL 은_lib/config.ts(NEXT_PUBLIC_ARCADE_BASE_URL). 랭킹·대결·점수제출(후속)이 전부 이 쉘에 모인다. - 브리지 = 공통 choke point 한 곳, cross-origin aware. 모든 게임이 게임오버 때 호출하는
common.js의resultScreen한 지점에서 임베드(iframe) 상태일 때만postMessage({source:'arcade', type, gameId, …})를 부모 쉘로 보낸다. 게임과 쉘은 다른 origin 이므로, 쉘이 iframe src 에?host=<쉘 origin>을 실어 보내고common.js가 그걸 targetOrigin·수신 검증에 쓴다(연속 플레이로 쿼리가 빠져도 유지되게 sessionStorage 에 저장). 쉘은 들어오는 메시지를 아케이드 origin 으로 엄격히 검증한다. 단독 실행(top === self) 이면 전부 no-op. 채널은 양방향 generic(부모→게임 리스너 자리 포함) — 실시간 대결의 상대 상태·매치 제어가 같은 채널로 들어오게 하기 위함. 프로토콜 타입은 쉘의_lib/bridge.ts, 게임의common.js.
native 는 apps/app /arcade 를 웹뷰로 로드하고, 게임은 그 안의 중첩 cross-origin iframe 으로 뜬다.
아케이드 사이트는 vercel.json 의 Content-Security-Policy: frame-ancestors 로 얼마집·프리뷰·로컬에서만
임베드를 허용한다.
후속 PR: Supabase 점수 제출 + 랭킹, Supabase Realtime(presence+broadcast) + 커스텀 JWT 기반 실시간 대결.
Consequences
좋아지는 것
- 게임 콘텐츠가 모노레포와 완전히 분리된다. 게임 추가/수정이 howmuchhome-web 의 CI/Vercel 을 전혀 트리거하지 않고 히스토리도 안 건드린다. 비개발자가 게임 레포에만 push 하면 끝.
- 서버 신원·랭킹·대결이 전부 React 쉘 한 곳에 모인다. 게임은 “점수만 외치는” 블랙박스라 인증을 몰라도 된다.
- iframe 격리로 게임들의 전역 스코프·스타일이 앱과 섞이지 않는다.
- native 웹뷰에서도 동일 구조로 뜬다.
감수하는 것
- cross-origin 복잡도. postMessage targetOrigin·origin 검증,
?host=전달, frame-ancestors, games.json CORS 를 맞춰야 한다. 같은 origin 이었다면 없을 배선이다. - 쉘이 원격 매니페스트에 의존한다. 아케이드 사이트가 다운이면 허브가 목록을 못 받는다 → 쉘은 fetch 실패를 빈/에러 상태로 처리(크래시 X)하지만, 그 사이 목록은 비어 보인다. ISR revalidate 주기만큼 반영도 지연된다.
- 외부 CDN·중첩 iframe 런타임 의존이 남는다. native 웹뷰가 오프라인이거나 CSP 가 더 조여지면 깨질 수 있다 → 필요 시 게임 레포에서 three.js 등 로컬 벤더링(별도 하드닝).
- 점수 포맷이 게임 표시값 그대로라(만원 콤마 등) 서버 제출 PR 에서 수치 정규화가 필요하다.
이 결정을 다시 열어야 할 때
- 실시간 대결이 게임 엔진에 깊은 네트워크 동기화를 요구해 게임을 더는 블랙박스로 둘 수 없게 될 때(대안 A 일부 재검토).
- 게임 업데이트가 드물어지고 콘텐츠를 앱과 함께 버전 고정하고 싶어질 때(대안 B 재검토).
- CSP 강제·오프라인 요구로 CDN 의존을 끊어야 할 때(게임 레포 로컬 벤더링으로 해소되면 이 ADR 유지).