Files
music_quiz/docs/01-architecture.md

5.6 KiB

01. 구조와 기술 스택

결정

joke-app과 같은 스택을 쓴다. 이미 운영 중이고 로그인·관리자·채팅·실시간 방이 검증돼 있어서, 같은 틀 위에 음악퀴즈만 새로 얹는 게 가장 빠르고 안전하다.

영역 선택 joke-app과 관계
런타임 Bun 1.3 + TypeScript 5.9, Bun workspaces 같음
서버 Hono 4 (HTTP) + Bun.serve WebSocket /ws, zod 4 검증 같음
DB bun:sqlite (WAL), 번호 붙은 SQL 마이그레이션 같음
웹 React 19 + Vite 8 + react-router + zustand, Pretendard 같음
스타일 손으로 쓴 CSS 변수 한 벌(global.css), CSS 프레임워크 없음 구조 같음, 색·형태는 새로
테스트 bun test(단위·통합) + playwright-core e2e(시스템 Chrome) 같음
배포 Docker compose(프록시 모드), NPMplus 뒤 같음, 포트만 2974
음원 재생 브라우저 YouTube IFrame API(숨김) + 서버 기준 시각 동기화 새로 추가
곡 수집기 Bun 스크립트(tools/collector), 필요시 Python 보조(하이라이트 분석) 새로 추가

폴더 구조 (예정)

music_quiz/
├─ apps/
│  ├─ server/            # Hono + WS + 게임 진행
│  │  ├─ src/auth/       # joke-app에서 가져옴 (discord.ts, sessions.ts, users.ts)
│  │  ├─ src/admin/      # roles.ts, audit, settings + 노래 관리 API
│  │  ├─ src/rooms/      # 방, 라운드 진행(quiz-engine), 투표
│  │  ├─ src/songs/      # 곡 조회·출제 선택·정답 판정(matcher)
│  │  ├─ src/sync/       # 시계 맞추기, 재생 준비·시작·일시정지 조정
│  │  └─ src/db/migrations/
│  └─ web/
│     ├─ src/pages/      # Home, Room, Game, Admin/*
│     ├─ src/components/ # ChatPanel, StarRating, YearRange, ArtistPicker, ...
│     └─ src/styles/global.css
├─ packages/shared/      # 프로토콜(zod), 정답 정규화 함수(서버·클라 공용), 장르/난이도 상수
├─ tools/collector/      # 차트·플레이리스트 수집, 유튜브 매칭, 분류
├─ data/seed/            # sta_songs.json 등 초기 데이터
├─ deploy/               # Dockerfile, docker-compose.proxy.yml, npmplus 설정
├─ assets/brand/         # 아이콘
└─ docs/                 # 이 문서들

joke-app에서 가져올 것

  • auth/discord.ts, auth/sessions.ts, auth/users.ts — 디스코드 OAuth(state 서명 쿠키), sid 세션 쿠키, 게스트 로그인/병합
  • admin/roles.ts — SUPERADMIN_DISCORD_IDS + admins 표, 감사 기록(admin_audit)
  • ws/rate-limit.ts, db/index.ts, 마이그레이션 001~003(사용자·세션·관리자·게스트 정리)
  • 웹: ChatPanel/ChatMessage, useTypingSignal(입력 중 신호), Sheet, Toasts, SiteHeader, NicknameForm, SchemaForm(관리자 자동 폼), 관리자 레이아웃(.admin-layout, .data-table)
  • 프로토콜 방식: {t: ...} JSON 메시지 + zod 판별 유니온, 방 상태 브로드캐스트

가져오지 않을 것 (컴퓨터 대결 제거)

  • packages/shared/src/bots.ts, packages/games/src/bots/*, 서버 rooms/bots.ts·bot-profile.ts·luck*.ts·ai/*
  • 프로토콜 addBot/removeBot/botLevel, 설정 botChat, "컴퓨터와 연습" 타일, /api/quick/*, docker-compose.ai.yml
  • 보드게임 엔진(cards.ts, grid.ts, betting.ts)과 게임 카탈로그
  • BotActivity.tsx는 사람 "입력 중" 표시 부분만 남긴다

바뀌는 점

  • 인원 무제한: joke-app은 좌석(seats) 배열 + 최대 32명. 음악퀴즈는 좌석 개념 없이 players 목록으로 관리하고 상한을 두지 않는다. 서버 보호용 상한만 관리자 설정에 두되 기본값은 "없음".
  • 방 상태 전송: 인원이 많아도 버티도록 전체 상태 대신 변경분만 보낸다(joke-app view-patch.ts 활용). 점수판은 점수 변동분만, 채팅은 개별 메시지로.
  • 게임 진행: 턴제 엔진 대신 시간 기반 라운드 진행기(quiz-engine)를 서버에 둔다. 서버 시계가 기준이고 클라이언트는 serverNow 보정값으로 카운트다운을 그린다.

실시간 메시지 (초안)

클라이언트 → 서버

t 내용
join / leave 방 입장/퇴장
config (방장) 방 설정 변경
ready / start / kick / host 준비, 시작, 강퇴, 방장 넘기기
chat 채팅 = 정답 입력 (서버가 정답 판정)
typing 입력 중 on/off
hint 힌트 요청(Ctrl+I)
skip 스킵 투표 토글(Ctrl+K)
audioReady / stall 이번 문제 음원 준비 완료 / 재생 중 버퍼링 보고
replay 다시듣기 투표 토글(Ctrl+R)
ping 시계 맞추기

서버 → 클라이언트

t 내용
room / patch 방 정보, 변경분
prepare / play / pause 문제 준비(영상 ID·시작 위치), 모두 같은 시각에 재생, 버퍼링 대기 일시정지
round 문제 진행 정보(번호, 모드, 제한 시간, 가사 일부)
hint 힌트 공개(초성 등)
vote 스킵/힌트 투표 현황
answer 정답 줄 + 5줄 블록 한 덩어리(seq), 정답자, 정답(제목-가수), 점수 변화
chat / typing 채팅, 입력 중 목록
result 게임 종료 결과

메모리·디스크 예산 (8GB 규칙)

  • 앱 컨테이너 상한 mem_limit: 1g (예상 사용 200~400MB)
  • 수집기·하이라이트 분석은 systemd-run --user --scope -p MemoryMax=2G로 따로 실행, 곡 단위로 스트리밍 처리
  • 음원은 브라우저가 유튜브에서 직접 재생하므로 서버 음원 캐시 없음 (12 문서 Q1)