코드레벨 문서화 로드맵 — 기능별 백로그 / 진행 트래커 계획트래커
마지막 업데이트 2026-07-29
- 입력: 이 문서는 이렇게 읽으면 됩니다
- 주요 처리 단계: P0 핵심 · 복잡 · 문서 부재 최우선
- 결과: 작성 가이드
문서 읽는 법 · 활용 가이드식
이 문서는 이렇게 읽으면 됩니다
코드레벨 문서화 로드맵 — 기능별 백로그 / 진행 트래커의 핵심을 활용 가이드식으로 먼저 안내합니다. 기술적 결론과 원문 근거는 아래 본문에 보존되어 있습니다.
핵심 흐름 펼쳐 보기
- 어떤 상황에서 이 문서를 쓰는지 확인합니다.
- 절차와 판단 기준을 순서대로 적용합니다.
- 기대 산출물과 운영 체크리스트로 결과를 확인합니다.
- 목적
- 이미 코드레벨 문서가 있는 기능 중복 작성 금지
- P0 핵심 · 복잡 · 문서 부재 최우선
목적
PPI 모노레포의 주요 기능을 코드레벨 동작 흐름 관점에서 문서화하기 위한 마스터 백로그이자 진행 트래커. 신규 합류 개발자가 특정 서브시스템의 "어디서 시작해 무엇을 호출하는지"를 빠르게 파악하는 것이 목표.
운영 규칙: 각 문서를 작성할 때마다 이 표의 상태를 미작성 → 진행중 → 완료로 갱신하고, 완료 시 기능명에 해당 문서 링크를 건다. 헤더의 진행 카운트(
n / 28)도 같이 갱신.
미작성 문서 없음 진행중 작성 중 완료 코드레벨 문서 존재 부분 관련 문서는 있으나 코드레벨 흐름 보강 필요
이미 코드레벨 문서가 있는 기능 중복 작성 금지
features/·architecture/에 이미 존재. 신규 작업 시 제외하거나 링크만 연결한다.
| 기능 | 문서 | 비고 |
|---|---|---|
| 아바타 RMS 립싱크 | features/아바타-RMS-립싱크-canvas-코드레벨-동작흐름.html 외 | 완료 |
| 오디오 분석 에이전트 | features/오디오-분석-에이전트-코드레벨-동작흐름.html 외 2편 | 완료 |
| MFCC 튜닝 / 기계음 영어 발화 감지 | features/MFCC-튜닝-변천사.html, 기계음 영어 발화 감지 로직 분석.html | 완료 |
| 리소스 다운로드 (Range·재시도) | features/리소스-다운로드-HTTP-Range-이어받기.html 외 | 완료 (다운로드 한정) |
| 아동 알림 프리셋 | features/아동-알림-프리셋-생성관리..., architecture/아동-알림-프리셋-동작-흐름.html | 완료 |
| 첫 발화 한국어 유도 / 회기 보고서 | features/첫 발화..., 회기-보고서-....html | 완료 |
| Redis 인프라 | architecture/PPI-879-redis-migration..., redis-troubleshooting-guide.html | 부분 이관·트러블슈팅. routerManager 소유권 흐름은 미커버(#5) |
| 카드뷰 세션 | features/카드뷰-세션-변천사.html | 부분 변천사(history). 코드레벨 아키텍처는 미커버(#13) |
P0 핵심 · 복잡 · 문서 부재 최우선
| # | 기능 | 주요 파일 | 상태 |
|---|---|---|---|
| 1 | OpenAI Realtime 세션 매니저 client / audio | apps/web/hooks/use-session-manager.ts (~1,300L) | 완료 |
| 2 | Socket.io + mediasoup SFU 서버 (peer/room 라이프사이클) server | apps/socket/src/server.ts, sfu-socket/signalingHandler.ts | 완료 |
| 3 | 녹음 파이프라인 (mediasoup→ffmpeg→OGG→S3) server | apps/socket/src/recording/recordingManager.ts (1,653L) | 완료 |
| 4 | STT 배치 + 화자분리 + dedup/환각감지 (Go) stt | apps/stt/internal/{handler/websocket.go, stt/batch.go, diarization/speaker.go, stt/dedup.go} | 완료 |
| 5 | Router 매니저 / 크로스인스턴스 소유권 · router-sync server / redis | apps/socket/src/mediasoup/routerManager.ts, redis/room-store.ts | 완료 |
P1 주요 서브시스템
| # | 기능 | 주요 파일 | 상태 |
|---|---|---|---|
| 6 | 게스트/호스트 세션 릴레이 (핑퐁이 음성 guest→host) client / server | hooks/use-guest-session-relay.ts, use-host-session-relay.ts, socket session-handlers.ts | 완료 |
| 7 | 오디오 처리 체인 (Gate→EQ→Comp→Limiter DSP) client / audio | hooks/use-audio-processing-chain.ts | 완료 |
| 8 | AI 오디오 노이즈 가드 (버징/정적 CV·ZCR·PLC) client / audio | hooks/use-ai-audio-noise-guard.ts | 완료 |
| 9 | External STT 클라이언트 (WS 프로토콜·prebuffer·diarization 수신) client / stt | entities/guest-session/lib/external-stt-observer.ts, hooks/use-external-stt.ts | 완료 |
| 10 | mediasoup 클라이언트 producer/consumer + simulcast/layer client / webrtc | hooks/mediasoup/use-mediasoup-{producer,consumer}.ts, use-video-expansion.ts | 완료 |
| 11 | V1 레거시 P2P WebRTC (ICE restart·candidate buffering·reconnect) client / webrtc | hooks/use-web-rtc.ts, use-{guest,host}-media-manager.ts | 완료 |
| 12 | Activity 시스템 (템플릿·step 시퀀싱·jumpConfig·auto-finish) app | hooks/use-activity-templates.ts, lib/activity-utils.ts | 완료 |
| 13 | Monitor 대시보드 아키텍처 (카드/포커스/통합 코드레벨) app | app/monitor-dashboard/, stores/use-monitor-data-store.ts | 완료 |
| 14 | 세션 로그 시스템 (stt_dedup/verified·MFCC·캡션) app | components/pages/session-log.tsx, types/db/session-log.types.ts | 완료 |
| 15 | Meet/룸 + 호스트 세션 라이프사이클 + 입장 승인 app / server | components/pages/host.tsx, lib/lesson-session.*, socketSfu.ts | 완료 |
| 16 | Redis 인프라 (heartbeat·leader election·reaper) server / redis | apps/socket/src/redis/{reaper,reaper-scheduler,peer-store}.ts | 완료 |
P2 보조 · 소규모
| # | 기능 | 주요 파일 | 상태 |
|---|---|---|---|
| 17 | 볼륨 증폭기 (마이크 auto-gain) client / audio | hooks/use-volume-amplifier.ts | 완료 |
| 18 | STT 폴백 (Web Speech API) client / stt | hooks/use-stt-fallback.ts | 완료 |
| 19 | WebRTC 모니터링/통계 (getStats 해석) client | hooks/use-webrtc-monitoring.ts | 완료 |
| 20 | 호스트 모니터링 claim / 그룹 모니터링 server | apps/socket/.../monitoring-handlers.ts | 완료 |
| 21 | 화면 공유 (host→guest) client | hooks/use-screen-share.ts | 완료 |
| 22 | 리소스 캐싱/프리캐시/SW 전체 시스템 app | hooks/use-resource-cache.ts, use-resource-processing.ts | 완료 |
| 23 | Auth/세션/TURN·ICE 발급 app / server | app/api/{members,users}/auth, api/ice-servers, lib/auth-refresh.ts | 완료 |
| 24 | 언어 가드 설정 스토어 (draft/save·STT·MFCC·early-interrupt) app | stores/use-language-guard-settings-store.ts | 완료 |
| 25 | 게스트 입장 플로우 (디바이스·네트워크 품질·can-enter) app | components/pages/guest-entry.tsx, use-device-manager.ts | 완료 |
| 26 | STT 오디오 처리/세션 (Go: VAD·필터·turn history) stt | apps/stt/internal/{audio,session} | 완료 |
| 27 | 클래스 관리/스케줄링 app | app/main/class-mgmt, lib/class-group-utils.ts | 완료 |
| 28 | Shared 상수/타입 (이벤트·mediasoup config) shared | packages/shared/src/{utils,types} | 완료 |
작성 가이드
- 포맷: 기존
features/아바타-RMS-립싱크-canvas-코드레벨-동작흐름.html·오디오-분석-에이전트-코드레벨-동작흐름.html구조를 따른다 (증상/개요 → 진입점 → 코드 흐름 → 파일·라인 표 → 함정/주의). - 위치: 기능 흐름 문서는
features/, 인프라/아키텍처는architecture/. - 필수:
copy-for-claude.js+share-link.js스크립트 포함,index.html해당 카테고리에 등록 + count 갱신. - 트래커 갱신: 작성 완료 시 이 문서의 상태 배지 + 기능명 링크 + 헤더 진행 카운트 갱신.
✅ 로드맵 전체 완료 (28/28): 🟥 P0(#1~5) · 🟧 P1(#6~16) · 🟨 P2(#17~28) 모두 코드레벨 문서 작성됨. 이후 코드 변경 시 해당 문서를 갱신하고, 새 기능은 이 표에 항목을 추가해 관리한다.