Architecture Proposal · 2026-10-23

ppi-monitor-app — 진행자 데스크톱 앱 설계

마지막 업데이트 2026-10-23

기존 진행자 웹을 Electron 창에 그대로 띄우고, 웹에서 일어난 이벤트(수업 진입·종료)를 앱에 전달해 앱 창 화면 녹화를 자동으로 시작·종료합니다. 녹화 로직은 이미 있는 /monitor-recorder를 재사용하고, 앱은 “화면 선택”과 “창 수명”만 대신 맡습니다.

설계 제안 · 구현 전신규 저장소 ppi-monitor-app대상 OS: macOS · Windows
한 줄 결론 — 기술적으로 가능합니다. 단 Electron(Chromium 내장)이어야 합니다. 진행자 웹이 쓰는 getDisplayMedia·setSinkId·MediaRecorder(webm)·팝업+BroadcastChannel은 macOS WKWebView(Tauri·Wails)에서 동작이 보장되지 않습니다. 웹 쪽 변경은 브리지 어댑터 1개 + 이벤트 발행 지점 몇 곳 + 녹화 화면 선택 분기로 작고, 일반 브라우저 동작은 그대로 유지됩니다.

확인2026-10-23 PPI checkout(PPI-1376 브랜치) 정적 확인 · 추정Electron 동작 중 PoC로 검증이 필요한 항목 · 신규아직 존재하지 않는 제안 파일·API

01왜 Electron인가 — 진행자 웹의 브라우저 의존성

진행자 페이지(/monitor-dashboard/[group], /monitor-dashboard/[group]/[roomId], /monitor-recorder/[group])가 실제로 쓰는 API를 기준으로 판단했습니다.

API사용 위치 확인ElectronTauri (Mac WKWebView / Win WebView2)
WebRTC · mediasoup · Socket.io모니터 전반✅✅
getDisplayMedia + displaySurface === "browser" 검사features/monitor-recording/model/use-video-crop-recorder.ts⚠️ 앱에서는 탭이 아니라 창이 잡힘 → 분기 필요❌
MediaRecorder (vp9/opus webm)features/monitor-recording/model/chunk-recorder.ts✅⚠️ Mac은 mp4 위주
setSinkIdshared/ui/meet-video.tsx 외✅⚠️ Mac 불안정
window.open 팝업 + BroadcastChannelfeatures/monitor-recording/model/use-monitor-recording-beacon.ts✅ (setWindowOpenHandler로 같은 session 창 생성)⚠️ 팝업 직접 구현
iron-session 쿠키 (sameSite: lax, prod secure)lib/session-options.ts✅ 원격 https URL 로드 시 그대로✅

앱이 커지는 비용(설치본 약 100MB 이상)은 있지만, 웹과 같은 Chromium 엔진이라 “브라우저에서 되던 것이 앱에서도 된다”는 전제를 지킬 수 있다는 점이 결정적입니다.

02설계 원칙

  1. 얇은 셸 — 앱은 운영 중인 PPI 웹 URL(https)을 로드합니다. Next.js를 번들하지 않으므로 웹 배포가 곧 앱 반영이고, 앱 업데이트는 셸 기능이 바뀔 때만 필요합니다.
  2. 웹이 의미를, 앱이 OS 권한을 — “수업이 시작됐다”는 판단은 웹(소켓·수업 상태를 아는 쪽)이 하고, 앱은 화면 캡처·창·권한·트레이처럼 브라우저가 못 하는 일만 합니다.
  3. 브라우저 동작 불변 — 웹은 window.ppiApp이 있을 때만 앱 경로를 탑니다. 없으면 지금과 같은 버튼·탭 선택 녹화를 그대로 씁니다.
  4. 최소 노출 — nodeIntegration: false, contextIsolation: true, sandbox: true. preload는 타입이 정해진 함수 몇 개만 노출하고, main은 보낸 쪽 origin을 검사합니다.
  5. 버전 독립 — 웹은 수시로 배포되고 앱은 늦게 업데이트됩니다. 브리지는 version·capabilities로 협상해 오래된 앱에서도 웹이 깨지지 않게 합니다.

03전체 구조

┌──────────────────────── ppi-monitor-app (Electron) ────────────────────────┐
│ main process                                                                │
│  ├ windows.ts      메인 창(진행자 웹) · 녹화 창(숨김) 생성·수명 관리        │
│  ├ bridge.ts       ipcMain: 웹 이벤트 수신 → origin 검사 → 정책 실행        │
│  ├ capture.ts      setDisplayMediaRequestHandler → 메인 창 소스 자동 지정   │
│  ├ permissions.ts  미디어·화면 권한: PPI origin만 허용, macOS TCC 상태 확인 │
│  ├ navigation.ts   허용 origin 밖 이동 차단, 외부 링크 → shell.openExternal │
│  ├ tray.ts         녹화 상태 표시(●REC), 수동 중지, 종료                    │
│  └ updater.ts      electron-updater (stage별 채널)                          │
│ preload            contextBridge → window.ppiApp { version, emit, on, … }   │
└───────────────┬───────────────────────────────────────────┬─────────────────┘
                │ 메인 창 (BrowserWindow, partition A)       │ 녹화 창 (hidden, 같은 partition A)
                ▼                                            ▼
     https://<ppi>/monitor-dashboard/{group}       https://<ppi>/monitor-recorder/{group}?recordingId=…
     ├ 수업 진입·종료 → ppiApp.emit(…)              ├ getDisplayMedia → (앱이 메인 창 소스 지정)
     └ useMonitorRecordingBeacon                    ├ 카드 영역 크롭 영상 + 아동별 오디오
          └ BroadcastChannel ◀──────────────────────┘ └ 업로드(presigned PUT → S3)
핵심 — 녹화 창은 기존 웹 페이지 /monitor-recorder 그대로입니다. 앱이 하는 일은 ① 그 창을 숨김·백그라운드 무제한으로 띄우고 ② 화면 선택 창 없이 메인 창을 캡처 대상으로 넘기는 것뿐입니다. 아동별 오디오 믹싱, 크롭, 업로드 로직은 중복 구현하지 않습니다.

저장소 구성 신규

ppi-monitor-app/
├ src/
│ ├ main/        index.ts · windows.ts · bridge.ts · capture.ts
│ │              permissions.ts · navigation.ts · tray.ts · updater.ts · config.ts
│ ├ preload/     index.ts            # contextBridge 노출
│ └ shared/      bridge-contract.ts  # 이벤트 이름·payload 타입·version
├ build/         entitlements.mac.plist · icons
├ electron-builder.yml               # dmg(Mac) · nsis(Win) · publish(S3)
└ package.json                       # electron-vite + electron-builder

빌드 도구는 electron-vite(개발)와 electron-builder(패키징·서명·업데이트)를 제안합니다. Electron Forge도 가능하지만 S3 기반 자동 업데이트·공증 설정 예시가 electron-builder 쪽이 많습니다.

04웹 ↔ 앱 이벤트 브리지

계약 (bridge-contract)

// window.ppiApp — 앱에서만 존재. 브라우저에서는 undefined
interface PpiAppBridge {
  version: 1;
  capabilities: Array<"auto-capture" | "recording-control" | "tray">;
  emit<E extends WebToAppEvent["type"]>(type: E, payload: PayloadOf<E>): void;
  on<E extends AppToWebEvent["type"]>(type: E, cb: (p: PayloadOf<E>) => void): () => void;
}

type WebToAppEvent =
  | { type: "monitor:group-opened";   payload: { groupId: string } }
  | { type: "monitor:room-opened";    payload: { groupId: string; roomId: string } }
  | { type: "lesson:started";         payload: { groupId: string; roomId: string } }
  | { type: "lesson:completed";       payload: MonitorLessonCompletion }   // 기존 타입 재사용
  | { type: "lesson:all-ended";       payload: { groupId: string } }
  | { type: "recording:state";        payload: { recordingId: string; state: RecState } };

type AppToWebEvent =
  | { type: "recording:stop-request"; payload: { reason: "user" | "app-quit" | "tcc-denied" } }
  | { type: "app:capture-insets";     payload: { top: number; left: number; scale: number } };

웹 쪽 변경 범위 신규 제안

파일변경
shared/lib/desktop-bridge/getDesktopBridge()(없으면 null), 타입, emitToDesktop() no-op 래퍼
app/monitor-dashboard/[group]/page.tsx진입 시 monitor:group-opened
app/monitor-dashboard/[group]/[roomId]/page.tsx진입 시 monitor:room-opened
shared/lib/monitor-lesson-completion-channel.tsBroadcastChannel 발행과 함께 lesson:completed
features/monitor-recording/model/use-monitor-recording-beacon.ts앱이면 정책에 따라 openRecorder를 자동 호출(버튼 없이)
features/monitor-recording/model/use-video-crop-recorder.ts앱이면 displaySurface !== "browser" 거부를 건너뛰고 app:capture-insets로 크롭 좌표 보정

05자동 녹화 흐름

① 진행자 로그인 → 메인 창에서 /monitor-dashboard/{group}
② 웹: 시작 조건 충족(정책: §08) → openRecorder() → window.open(/monitor-recorder/…)
③ main: setWindowOpenHandler가 /monitor-recorder 를 가로챔
        → BrowserWindow({ show:false, webPreferences:{ partition:A,
             backgroundThrottling:false, autoplayPolicy:"no-user-gesture-required" } })
④ 녹화 창: getDisplayMedia() 호출
        → main: session.setDisplayMediaRequestHandler
             desktopCapturer.getSources({types:["window"]})
             에서 mainWindow.getMediaSourceId() 와 같은 소스를 callback({ video })
        → 선택 창 없이 메인 창 영상 트랙 획득
⑤ 녹화 창: 기존 로직 그대로 — 크롭 영상 + room별 아동 오디오(mediasoup 수신) 녹화
        → recording:state 를 앱에 보고 → 트레이 ●REC 표시
⑥ 종료: lesson:all-ended / 30분 한도 / 트레이 중지 / 앱 종료 요청
        → 녹화 창이 finalize·업로드 → recording:state=done → main이 녹화 창 닫음

앱이 해결해 주는 기존 제약

PoC 검증 필수 추정
  • 사용자 동작 없는 getDisplayMedia — Electron 공식 예제는 버튼 클릭 안에서 호출합니다. 클릭 없이 호출해도 setDisplayMediaRequestHandler가 불리는지 확인되지 않았습니다. 막히면 대안: 녹화 창에서 getUserMedia({ video: { mandatory: { chromeMediaSource: "desktop", chromeMediaSourceId } } })로 받습니다(웹에 분기 1개 추가).
  • useSystemPicker는 쓰지 않음 — 켜면 macOS 시스템 선택 창이 우선되어 handler가 호출되지 않습니다.
  • 창 캡처 좌표 — 탭 캡처는 웹 viewport만 담지만, 창 캡처는 타이틀바·테두리가 포함될 수 있습니다. main이 getContentBounds()와 getBounds()의 차이와 배율을 app:capture-insets로 보내 크롭을 보정합니다.
  • 창 최소화·가려짐 — 최소화된 창은 OS에 따라 프레임이 멈추거나 검게 나옵니다. 녹화 중에는 최소화를 막거나 경고합니다.

06보안·권한

항목설계
렌더러 격리contextIsolation·sandbox on, nodeIntegration off. preload는 emit/on/version/capabilities만 노출
이벤트 출처main에서 senderFrame.url origin 허용 목록 검사. 허용 외 origin(외부 링크·채널톡 등)의 이벤트는 무시
탐색 제한will-navigate로 PPI origin 밖 이동 차단. _blank·채널톡 링크는 shell.openExternal로 기본 브라우저에서 열기
미디어 권한setPermissionRequestHandler/setPermissionCheckHandler: PPI origin의 media·display-capture만 허용
macOS TCCInfo.plist NSMicrophoneUsageDescription·NSCameraUsageDescription, Hardened Runtime entitlements. 화면 기록 권한은 systemPreferences.getMediaAccessStatus("screen")로 확인하고, 미허용이면 설정 화면 안내(허용 후 앱 재시작 필요)
녹화 고지아동 화면·음성이 녹화되므로 트레이·창 제목에 ●REC 상시 표시. 자동 시작이라도 진행자가 녹화 중임을 항상 알 수 있어야 함

07배포·운영

08구현 전 확정할 정책

질문선택지제안
자동 녹화 시작 시점그룹 페이지 진입 / 첫 아동 접속 / 진행자 수업 시작첫 아동 접속(빈 화면 녹화 방지). 페이지 진입은 녹화 창 준비(오디오 연결)만
종료 시점모든 아동 수업 종료 / 30분 한도 / 수동셋 다. 기존 “모든 아동 수업 종료 시 녹화 종료 안내”를 앱에서는 자동 종료로
포커스뷰([roomId]) 이동 시녹화 유지 / 분할유지(창 단위 캡처라 화면 전환도 그대로 기록)
브라우저 녹화 경로유지 / 앱 전용당분간 유지. 앱에서는 버튼을 숨겨 중복 녹화 방지
지원 OS 최소 버전—채택하는 Electron 버전의 지원 범위에 맞춤(진행자 장비 조사 필요)
설치·배포 대상사내 배포 / 기관 배포미정 — 서명·업데이트 채널 설계에 영향

09단계별 계획과 완료 기준

단계범위완료 기준
P0 셸저장소 생성, 메인 창 로드, 권한·탐색 제한, 외부 링크Mac·Win에서 로그인 유지, 카드뷰·포커스뷰 영상·음성·출력 장치 선택 정상
P1 브리지preload·bridge·계약, 웹 어댑터(no-op), 이벤트 발행 지점앱에서 이벤트 수신 로그 확인, 브라우저 동작 변화 없음(기존 테스트 통과)
P2 캡처 PoC숨김 녹화 창, 자동 소스 지정, 크롭 보정클릭·선택 창 없이 녹화 시작, 카드 경계 정확, 가려짐·창 크기 변경 시 유지
P3 자동 정책시작·종료 정책, 트레이 ●REC, 종료 가드수업 1회 전체가 사람 조작 없이 녹화·업로드, 앱 종료 시 유실 없음
P4 배포서명·공증·인스톨러·자동 업데이트깨끗한 Mac·Win에서 설치→TCC 허용→업데이트까지 통과

PPI 웹 변경은 repository 규칙에 따라 brainstorming 설계 승인 → code-quality-guardian baseline → 구현 → guardian-gate 리뷰 순서로 진행합니다.

Claude용 핵심 맥락

ppi-monitor-app은 진행자 웹(/monitor-dashboard)을 Electron BrowserWindow로 로드하는 얇은 셸이다. Tauri는 macOS WKWebView에서 getDisplayMedia·setSinkId·webm MediaRecorder가 보장되지 않아 제외했다. 웹↔앱은 preload contextBridge의 window.ppiApp(version·capabilities·emit·on)으로 연결하고 main이 senderFrame origin을 검사한다.

자동 녹화는 기존 /monitor-recorder 페이지를 재사용한다. setWindowOpenHandler로 녹화 팝업을 숨김 창(같은 partition, backgroundThrottling false, autoplay 허용)으로 만들고, setDisplayMediaRequestHandler에서 desktopCapturer의 메인 창 소스(mainWindow.getMediaSourceId)를 자동 지정한다. 웹은 앱일 때 use-video-crop-recorder의 displaySurface==="browser" 검사를 건너뛰고 app:capture-insets로 크롭 좌표를 보정한다. 사용자 동작 없는 getDisplayMedia 허용 여부는 미검증이며, 막히면 chromeMediaSource desktop getUserMedia로 대체한다.

미확정 정책: 시작 시점(제안: 첫 아동 접속), 종료(모든 아동 종료·30분·수동), 브라우저 녹화 경로 유지 여부, 최소 OS, 배포 대상. 단계 P0 셸 → P1 브리지 → P2 캡처 PoC → P3 자동 정책 → P4 서명·업데이트. 2026-10-23 설계 제안, 구현 전.