PPI 아키텍처 문서

아동 대화 연습을 위한 AI 아바타 플랫폼 · Turborepo 모노레포 · OpenAI Realtime API + Mediasoup SFU

3
앱 (web, socket, stt)
111+
페이지 / API 엔드포인트
77
커스텀 훅
62
UI 컴포넌트
47
섹션 컴포넌트
60+
유틸리티 파일
🗺 시스템 개요
치료사 (Host)
모니터링 + 피드백
아동 (Guest)
AI와 대화 연습
↕ WebRTC / Socket.io
apps/web
Next.js 16 · Port 3000
apps/socket
Socket.io + Mediasoup · Port 3001
apps/stt
Go · STT 처리 서버
↕ AWS SDK
DynamoDB
프로필 · 로그 · 활동
AWS S3
음성 · 미디어 파일
OpenAI Realtime
핑퐁이 AI 아바타
Google STT
음성 인식

수업 흐름

아동은 /client-guest, 치료사는 /main/meet, 모니터는 /monitor-dashboard에서 접속합니다.

  • 아동: 핑퐁이 AI와 직접 대화 연습
  • 치료사: 아동 활동 모니터링 + 세션 제어
  • 모니터: 자동 응답 · STT · LLM 개입
  • 세션 로그 자동 기록 및 분석

FSD 아키텍처 레이어

Feature-Sliced Design 기반의 계층형 구조입니다.

  • pages — Next.js App Router 라우트
  • widgets — 재사용 UI 컴포넌트 묶음
  • features — 기능별 로직 (자동 응답, STT 등)
  • entities — 비즈니스 모델 · Zustand 상태
  • shared — 공유 타입 · 유틸 · UI

핑퐁이 AI 세션

OpenAI Realtime API 기반 실시간 대화 엔진입니다.

  • VAD 기반 음성 감지
  • 실시간 STT · 전사 (Google Speech API)
  • 턴별 세션 로그 기록
  • 활동 단계별 프롬프트 제어
📦 앱 구조 (Turborepo)

apps/web · Next.js 16

메인 웹 애플리케이션. 치료사 대시보드, 게스트 수업, API 라우트 포함.

  • React 19.2.6 + TypeScript 5.9
  • Tailwind CSS 4.x
  • Zustand 5 · Socket.io Client
  • mediasoup-client 3.18
  • AWS DynamoDB · S3 SDK
  • Port: 3000

apps/socket · Node.js

Mediasoup SFU 전용 실시간 통신 서버. 게스트·호스트·모니터 시그널링 처리.

  • Socket.io 4.x (/sfu 네임스페이스)
  • Mediasoup 3.x (SFU)
  • Prometheus 메트릭
  • S3 녹음 업로드
  • REST API (rooms, peers, groups)
  • Port: 3001

apps/stt · Go

별도 운영 STT 처리 서버. Google Speech API 연동.

  • Google Speech API 연동
  • 배치 처리 · 화자 분리
  • 중복 제거 (dedup)
  • 환각 감지 (hallucination)
  • WebSocket 클라이언트 연동
🔌 Socket 서버 (/sfu 네임스페이스) 핸들러 구조

Transport · Media

  • getRouterRtpCapabilities
  • createWebRtcTransport
  • connectWebRtcTransport
  • produce (카메라·마이크·AI 오디오)
  • consume (스트림 구독)
  • newProducer / producerClosed

Room · Session

  • join-group / leave-group
  • session-start / session-stop
  • session-control (호스트 → 게스트)
  • chat-message (호스트 → 게스트)
  • avatar-info 교환
  • graceful disconnect

Monitoring · REST API

  • monitor-subscribe (모니터 구독)
  • monitoring-data (실시간 상태 전송)
  • GET /rooms — 활성 룸 목록
  • GET /rooms/:roomId — 룸 상세
  • GET /peers — 피어 목록
  • DELETE /groups/:id/peers
🗂 라우트 구조

UI 페이지

/main대시보드 홈
/main/meet/[roomId]호스트 수업 진행
/main/activity활동 관리
/main/log세션 로그 분석
/main/avatars아바타 관리
/main/prompt-test프롬프트 테스트
/main/schedule일정 관리
/main/curriculum커리큘럼 관리
/main/member치료사 관리
/main/user사용자(부모) 관리
/main/res리소스 관리
/main/class-mgmt클래스 관리
/client-guest아동 수업 입장 (PIN·이름·장치 선택)
/client-guest/session아동 수업 세션 (GuestLayout)
/monitor-dashboard모니터 대시보드 (예정·라이브 세션)
/monitor-dashboard/[group]/[roomId]개별 방 모니터링

API 엔드포인트 (주요)

/api/realtime/callOpenAI Realtime 세션 토큰
/api/activities활동 CRUD
/api/activity-templates활동 템플릿
/api/session-logs세션 로그
/api/lessons수업 CRUD
/api/avatars아바타 관리
/api/ice-serversICE 서버 정보
/api/resources미디어 리소스
/api/members치료사 계정
/api/users부모/아동 계정
/api/guest-data게스트 세션 데이터
/api/chat-presets치료사 채팅 프리셋
/api/recording-captions녹음 자막
/api/lesson-progress레슨 진행률
/api/classes수업 클래스
/api/health헬스체크
/metricsPrometheus 메트릭
주요 코드 흐름
게스트 세션 흐름 (/client-guest)
1
엔트리
/client-guest
PIN · 이름 · 장치 선택
2
SFU 연결
use-mediasoup-socket
/sfu 네임스페이스
3
Device 초기화
use-mediasoup-device
RTP Capabilities 로드
4
미디어 발행
use-mediasoup-producer
카메라 · 마이크 produce
5
AI 세션
use-ai-session
OpenAI Realtime 연결
6
STT
use-external-stt
Google Speech API
7
AI 음성 발행
AI 오디오 스트림
SFU produce → 모니터 수신
8
로그 기록
use-session-logs
DynamoDB 저장
모니터 대시보드 흐름 (/monitor-dashboard)
1
대시보드
useMonitorUserId
라이브 · 예정 세션
2
SFU 구독
use-monitor-socket
게스트 스트림 consume
3
세션 관리
use-monitor-session
활동 · 스텝 상태 추적
4
자동 응답
features/monitor/
auto-response · auto-transition
5
외부 STT
features/monitor/
external-stt
6
전역 상태
use-monitor-data-store
rooms · sessions · toasts
호스트 흐름 (/main/meet/[roomId])
1
수업 입장
use-host-socket
SFU 룸 참여
2
스트림 수신
use-mediasoup-consumer
게스트 비디오 · AI 오디오
3
세션 제어
session-control
시작 · 중단 · 스텝 이동
4
채팅 피드백
host-chat-panel
프리셋 · 직접 입력
5
로그 분석
session-log-table
턴별 시각화
게스트 페이지 핵심 엔티티 구조

entities/guest-session 구성

  • use-ai-session — OpenAI Realtime 연결 관리
  • use-transcripts — 전사 결과 상태
  • use-guest-connection — 소켓 + Device 통합 연결
  • external-stt-observer — WebSocket STT 관찰자

entities/guest-page-session 구성

  • use-guest-page-session — 활동·스텝 상태 총괄
  • use-step-sync — 모니터와 스텝 동기화
  • use-step-transition — 스텝 전환 처리
  • use-auto-save-lesson-progress — 진행률 자동 저장

use-ai-session 제어 인터페이스

  • startSession(params) — 세션 시작
  • stopSession() — 세션 종료
  • sendTextMessage(text) — 텍스트 입력
  • interruptResponse() — AI 응답 중단
  • setMicrophoneEnabled(bool) — 마이크 ON/OFF
  • setNoiseReduction(mode) — 노이즈 감소
  • reloadSession() — 세션 재시작
  • jumpToStep(index) — 활동 단계 이동
🪝 주요 훅 목록
Mediasoup SFU (hooks/mediasoup/)
use-mediasoup-socketSFU 시그널링 소켓 연결 · 재연결 관리
use-mediasoup-deviceDevice 초기화 · RTP Capabilities 로드
use-mediasoup-producer카메라·마이크·AI 오디오 Producer 생성
use-mediasoup-consumer피어 스트림 Consumer (비디오·오디오 분리)
소켓 연결 (entities/)
use-guest-socket게스트 소켓 이벤트 처리
use-host-socket호스트 소켓 이벤트 처리
use-monitor-socket모니터 소켓 · SFU 구독
use-guest-connection소켓 + Device 통합 연결 (게스트용)
세션 · 페이지 상태 (entities/)
use-ai-sessionOpenAI Realtime API 연결 · 세션 관리
use-transcripts전사 결과 상태 관리
use-guest-page-session활동·스텝 상태 총괄 (게스트 페이지)
use-step-sync모니터와 스텝 동기화
use-step-transition스텝 전환 처리
use-auto-save-lesson-progress레슨 진행률 자동 저장
use-monitor-session모니터 세션 상태 관리
use-session-logs세션 로그 조회 및 관리
use-session-auto-finish자동 종료 조건 감지
use-session-log-table세션 로그 테이블 상태
미디어 · 오디오
use-camera-stream카메라 스트림 관리
use-local-media-stream로컬 미디어 스트림
use-device-manager미디어 장치 선택 관리
use-video-device-validator비디오 장치 유효성 검사
use-avatar-video아바타 비디오 스트림
use-volume-amplifier출력 음량 증폭
use-audio-processing-chain오디오 전처리 체인
use-media-cleanup미디어 리소스 정리
use-mfcc-log-collectorMFCC 패턴 로그 수집
STT · 음성인식
use-external-stt외부 STT (Google Speech API)
use-stt-fallbackSTT 폴백 처리
use-ai-audio-noise-guardAI 오디오 노이즈 가드
use-ai-english-guardAI 영어 가드 (한국어 강제)
use-transcript-english-matcher전사 결과 영어 매칭
use-recording-captions녹음 자막 관리
네트워크 · 모니터링
use-network-status네트워크 온라인 상태
use-network-recovery네트워크 복구 처리
use-monitor-network-level네트워크 레벨 수치 모니터링
use-guest-network-alert게스트 네트워크 경고
use-network-quality네트워크 품질 지표
use-monitor-user-id모니터 사용자 ID 관리
use-guest-controls모니터 → 게스트 제어
데이터 조회
use-activities활동 목록 조회
use-activity-templates활동 템플릿 조회
use-avatars / use-avatar아바타 목록 / 단건 조회
use-avatar-resources아바타 리소스 조회
use-users / use-user사용자(부모) 목록 / 단건
use-members / use-current-member치료사 목록 / 현재 계정
use-lessons수업 목록 조회
use-lesson-templates레슨 템플릿 조회
use-curriculums커리큘럼 조회
use-curriculum-categories커리큘럼 카테고리
use-resources미디어 리소스 조회
use-holidays휴일 정보 조회
use-prompt-variables프롬프트 변수 조회
use-vacations치료사 휴가 관리
기타 유틸리티
use-countdown카운트다운 타이머
use-cumulative-elapsed누적 경과 시간 측정
use-follow-bottom-scroll채팅 스크롤 추종
use-prevent-page-leave페이지 이탈 방지
use-scheduled-polling예약된 폴링 실행
use-mobile-screen모바일 화면 감지
use-kakao-browser-redirect카카오 인앱 브라우저 처리
use-recommended-browser권장 브라우저 가이드
use-resource-cache리소스 캐시 관리
use-resource-upload리소스 업로드 처리
use-sanitized-input입력값 정제
use-network-alert-config네트워크 경고 설정
🧩 FSD 컴포넌트 구조
레이어 의존 방향 (위 → 아래로만 참조 가능)
app/ (pages)
Next.js App Router 라우트
widgets/
재사용 UI 묶음
features/
기능별 로직
entities/
비즈니스 모델 · 상태
shared/
공유 타입 · 유틸 · UI

widgets/guest — 게스트 UI

  • guest-layout — 메인 레이아웃 컨테이너
  • guest-camera — 카메라 비디오
  • meet-avatar — 아바타 표시
  • meet-video — 호스트 비디오
  • transcript-panel — 실시간 전사 패널
  • session-error-screen — 에러 화면
  • resource-loading-screen — 리소스 로딩
  • network-toast — 네트워크 상태
  • status-header — 상태 표시 헤더
  • video-display — 비디오 표시

widgets/monitor-dashboard — 대시보드 UI

  • live-sessions — 라이브 세션 목록
  • today-scheduled — 오늘 예정 세션
  • test-session-manager — 테스트 세션
  • session-card — 세션 카드 컴포넌트
  • alerts-panel — 알림 패널

widgets/monitor — 모니터 UI

  • 모니터링 룸 별 UI 컴포넌트

sections/ — 관리 화면 섹션

  • host-chat-panel — 호스트 채팅
  • host-video — 호스트 비디오
  • share-screen — 화면 공유
  • session-log-table — 세션 로그
  • activity-form / activity-table
  • avatar-form / avatar-list
  • step-table / step-form
  • curriculum-*.tsx (sidebar, detail)
  • performance-monitor — 성능 모니터
🏗 Features · Entities 상세

features/guest

  • entry-cleanup — 엔트리 정리
  • message-input — 메시지 입력 UI
  • session-control — 세션 시작·종료

features/monitor

  • room-monitoring — 방 모니터링
  • group-monitoring — 그룹 모니터링
  • auto-response — 자동 응답
  • auto-transition — 자동 스텝 전환
  • external-stt — 외부 STT
  • realtime-model — LLM 모델 제어
  • vad-settings — VAD 설정
  • lesson-completion — 레슨 완료

entities/guest-session

  • use-ai-session
  • use-transcripts
  • use-guest-connection
  • external-stt-observer

entities/guest-page-session

  • use-guest-page-session
  • use-step-sync
  • use-step-transition
  • use-auto-save-lesson-progress
  • use-noise-test-harness

entities/socket-connection

  • use-mediasoup-socket

entities/monitor

  • use-monitor-session
  • use-monitor-socket
  • use-monitor-user-id
  • use-guest-controls

entities/monitor-dashboard

  • use-sessions
  • use-upcoming-sessions

stores/ (Zustand)

  • use-monitor-data-store
    rooms · sessions · toasts · alerts
  • use-monitor-ui-store
  • use-lesson-cache-store
  • use-session-log-audio-store
  • use-language-guard-settings-store
  • use-first-turn-korean-guide-store
  • use-admin-classes-store

contexts/

  • activities-context
  • activity-templates-context
  • members-context / users-context
🗄 데이터 레이어

DynamoDB 테이블

  • activity — 활동 데이터
  • activity-template — 활동 템플릿
  • session-log — 세션 로그 (턴별)
  • chat-log — 채팅 로그
  • chat-preset — 치료사 채팅 프리셋
  • member — 치료사 계정
  • user — 부모/아동 계정
  • lesson — 수업 정보
  • lesson-session — 레슨 세션
  • resource — 미디어 리소스
  • avatar — 아바타 데이터
  • curriculum — 커리큘럼
  • speech-alert-rule — 음성 경고 규칙

API 레이어 구조

  • lib/api/controllers/ — 요청 라우팅
  • lib/api/services/ — 비즈니스 로직
  • lib/api/dao/ — DynamoDB 직접 접근
  • lib/dynamodb.ts — 클라이언트 초기화
  • lib/dynamodb-utils.ts — 쿼리 헬퍼
  • lib/db-queries.ts — 공통 쿼리
  • lib/s3.ts — S3 파일 처리
  • lib/auth.middleware.ts — 인증 검증
  • lib/ppi-api-client.ts — 내부 API 클라이언트

TypeScript 타입 체계

  • types/db/ — 26개 DB 모델 타입
  • types/enum/ — 열거형 타입
  • types/props/ — 컴포넌트 Props
  • types/stt.types.ts — STT 관련 타입
  • types/mediasoup.types.ts — Mediasoup 타입
  • types/delegates.types.ts — 콜백 위임 타입
  • types/instruction-variables.types.ts
  • types/index.ts — barrel export
계층 파일 위치 역할 주요 항목
Controller lib/api/controllers/ HTTP 요청 파싱 · 응답 포맷팅 guest-data, lesson-session
Service lib/api/services/ 비즈니스 로직 처리 guest-data, lesson-progress, resource
DAO lib/api/dao/ DynamoDB 직접 CRUD 각 도메인별 DAO
Middleware lib/auth.middleware.ts API 인증 검증 토큰 기반 인증
기술 스택

프론트엔드

  • React 19.2.6
  • Next.js 16.2.6
  • TypeScript 5.9.2
  • Tailwind CSS 4.1.14
  • Zustand 5.0.9
  • Socket.io Client 4.8.1
  • mediasoup-client 3.18.1

백엔드 / 서버

  • Node.js (LTS ≥ 20.9)
  • Express 4.x
  • Socket.io 4.x
  • Mediasoup 3.x (SFU)
  • Go (STT 서버)
  • MySQL2
  • prom-client

AI / 음성

  • OpenAI Realtime API
  • Google Speech API
  • VAD (Voice Activity Detection)
  • Web Audio API
  • MFCC 분석
  • 노이즈 감소 필터
  • LogRocket 10.1.0

인프라 / 클라우드

  • AWS DynamoDB
  • AWS S3
  • AWS EC2 (ARM64)
  • AWS ALB · Route53
  • Docker / GHCR
  • Terraform
  • GitHub Actions (CI/CD)
인프라 및 배포

배포 아키텍처

GitHub GitHub Actions (workflow_dispatch)
빌드 Docker 이미지 빌드 · GHCR 푸시
프로비전 Terraform으로 AWS 인프라 생성
DNS {branch}-dev.dubuhealth.in 자동 생성
정리 EventBridge + Lambda (3일 후 자동 삭제)

모니터링

  • Prometheus 메트릭 (/metrics)
  • HTTP 요청 수 · 지연시간
  • Socket.io 접속 수
  • Mediasoup 워커 · 리소스 상태
  • Node.js 런타임 메트릭
  • 서버 → JSON Lines (Loki 호환)
  • 브라우저 → LogRocket 세션 기록
  • /api/health — 헬스체크 엔드포인트
환경 트리거 URL 패턴 비고
개발 수동 (workflow_dispatch) {branch}-dev.dubuhealth.in 3일 후 자동 삭제
운영 Web deploy-web-prod.yml dubuhealth.in 승인 후 배포
운영 Socket deploy-socket-prod.yml socket.dubuhealth.in 승인 후 배포
PPI Architecture Document · V2 (Mediasoup SFU) 기준 · 2026-05-20