Xingu - 아이스브레이킹 플랫폼 기획안

웹 기반 실시간 멀티플레이 아이스브레이킹 플랫폼

프로젝트 개요

🎯 핵심 콘셉트

Xingu는 동아리, 워크샵, 팀 빌딩 등에서 사용할 수 있는 웹 기반 아이스브레이킹 플랫폼입니다.

주요 특징

🌐 설치 불필요: 브라우저에서 바로 실행
👥 역할 분리: 호스트는 관리, 플레이어는 참여
⚡ 실시간 동기화: WebSocket 기반 즉각 반응 (예정)
🎮 다양한 게임: 초성, 밸런스, 라이어 등 7개 게임
🎨 플레이어 중심 UX: PIN 입력을 랜딩 페이지 중앙에 배치
🎴 시각적 게임 선택 & 방 만들기: 카드 기반 UI와 필터 시스템
📌 게임 저장 기능: 담기/바로 시작 두 가지 옵션 ⭐
🔑 카카오 로그인: 간편한 소셜 로그인으로 게임 관리

비전

동아리, 스터디, 워크샵, 팀 빌딩 등 다양한 그룹 활동에서 사용할 수 있는 올인원 아이스브레이킹 플랫폼

타겟 사용자

호스트 (관리자)

MT/워크샵 진행자
팀 리더
교육자/강사
동아리 운영진

플레이어 (참가자)

워크샵 참가자
팀원
학생
동아리 회원

핵심 기능

1. 방 시스템

방 생성: 호스트가 게임 방 생성 (6자리 PIN 코드 발급)
방 참여: PIN 코드 입력으로 간편 참여
참가자 관리: 호스트가 게임 시작/종료 제어, 강퇴 기능
방 설정: 인원 제한, 게임 설정 커스터마이징

2. 실시간 통신

WebSocket 기반: Socket.io를 통한 실시간 양방향 통신
동기화: 모든 참가자가 동일한 게임 상태 공유
즉시 반영: 호스트의 액션이 모든 플레이어에게 실시간 전달

3. 게임 시스템

다양한 게임 지원: 퀴즈, 워드, 커뮤니케이션, 액션 등
게임 탐색: 카드 기반 UI와 필터 시스템
커스터마이징: 게임별 설정 가능 (라운드, 시간, 난이도)
점수 시스템: 실시간 점수 집계 및 순위
결과 공유: 게임 결과 다운로드 및 공유 기능

📝 게임 목록: 구체적인 게임 아이디어는 GAME_LIST.md 참조

4. 역할 분리

호스트: 게임 선택 & 방 만들기, 방 관리, 게임 진행 제어, 참가자 모니터링
플레이어: 방 참여, 게임 참여, 답변 제출

사용자 플로우

🎯 호스트 플로우 (간략)

1. 랜딩 페이지 → 우측 상단 [게임 선택 & 방 만들기]
   ↓
2. 게임 선택 & 방 만들기 (/create)
   - 카드 기반 게임 목록 탐색
   - 필터로 원하는 게임 찾기
   - 게임 상세 모달에서 설정 조정
   ↓
3. 호스트 대기실 (/host/[code]/lobby)
   - 방 코드 공유 (복사, QR)
   - 참가자 입장 확인 및 관리
   - 최종 설정 확인
   ↓
4. 게임 진행 (/host/[code]/game)
   - 게임 컨트롤 (시작/일시정지/종료)
   - 참가자 상태 실시간 모니터링
   - 대형 화면 모드 (선택)
   ↓
5. 결과 확인 (/host/[code]/result)
   - 순위 및 통계 표시
   - 결과 공유 (이미지, 링크, CSV)
   - 새 게임 시작 or 방 종료

🔍 상세 정보: HOST_GUIDE.md에서 호스트 화면 상세 설계 확인

👥 플레이어 플로우 (간략)

1. 랜딩 페이지 → 중앙 PIN 입력
   ↓
2. 닉네임 입력 모달
   ↓
3. 플레이어 대기실 (/play/[code]/lobby)
   - 게임 정보 확인
   - 호스트 시작 대기
   ↓
4. 게임 참여 (/play/[code]/game)
   - 문제 확인
   - 답변 입력/제출
   - 내 점수 및 순위 확인
   ↓
5. 결과 확인 (/play/[code]/result)
   - 내 최종 순위
   - 전체 순위

🔍 상세 정보: PLAYER_GUIDE.md에서 플레이어 화면 상세 설계 확인

🔄 실시간 동기화

호스트가 게임을 시작하면 → 모든 플레이어 화면 자동 전환
플레이어가 답변 제출하면 → 호스트 화면에 실시간 표시
라운드 종료 시 → 모두에게 결과 표시
호스트가 방을 종료하면 → 모든 플레이어 연결 해제

기술 스택

Frontend

Framework: Next.js 15 (App Router)
Language: TypeScript
Styling: Tailwind CSS
UI Components: Shadcn UI, Radix UI
Authentication: Next-auth v5 + Kakao OAuth ⭐
Database ORM: Prisma ⭐
Real-time: Socket.io Client (예정)

Backend

Runtime: Node.js
API: Next.js API Routes
Authentication: Next-auth v5 ⭐
Database: SQLite (개발), PostgreSQL (프로덕션 예정)
Real-time: Socket.io (예정)
Cache: Redis (예정)

Infrastructure

Hosting: Vercel (Frontend + API)
WebSocket Server: 별도 Node.js 서버 (Railway/Fly.io)
Database: Supabase / Railway

Next.js 15 주요 활용 기능

Turbopack: 더 빠른 개발 서버 및 빌드
Server Actions: 간편한 서버 사이드 로직 처리
Partial Prerendering: 최적화된 렌더링
Improved Caching: 향상된 캐싱 전략

시스템 아키텍처

📐 페이지 구조

/                          # 랜딩 페이지 (PIN 입력 중앙 배치) ✅
├── /login                # 로그인 페이지 (카카오) ⭐ ✅
├── /dashboard            # 대시보드 (저장된 게임) ⭐ ✅
├── /create               # 게임 선택 & 방 만들기 (카드 + 필터 + 저장/방만들기) ⭐ ✅
├── /how-to-play          # 사용 방법 (예정)
├── /about                # 서비스 소개 (예정)
│
├── /host/[code]          # 호스트 전용 화면 (예정)
│   ├── /lobby            # 대기실 (방 코드 공유, 참가자 관리)
│   ├── /game             # 게임 진행 (컨트롤, 모니터링)
│   └── /result           # 결과 (순위, 통계, 공유)
│
└── /play/[code]          # 플레이어 전용 화면 (예정)
    ├── /lobby            # 대기실 (게임 정보, 대기)
    ├── /game             # 게임 참여 (답변 입력)
    └── /result           # 결과 (내 순위, 전체 순위)

📁 프로젝트 폴더 구조

xingu/
├── app/                     # Next.js 15 App Router
│   ├── page.tsx            # 랜딩 페이지 ✅
│   ├── login/              # 로그인 페이지 ⭐ ✅
│   ├── dashboard/          # 대시보드 (저장된 게임) ⭐ ✅
│   ├── create/             # 게임 선택 & 방 만들기 ✅
│   ├── host/[code]/        # 호스트 화면 (예정)
│   ├── play/[code]/        # 플레이어 화면 (예정)
│   ├── api/                # API Routes
│   │   └── auth/[...nextauth]/  # Next-auth API ⭐ ✅
│   └── providers.tsx       # SessionProvider ⭐ ✅
│
├── components/             # React 컴포넌트
│   ├── landing/           # PIN 입력, 닉네임 모달 ✅
│   ├── create/            # 게임 카드, 필터, 모달, 저장 모달 ⭐ ✅
│   ├── host/              # 호스트 전용 컴포넌트 (예정)
│   ├── player/            # 플레이어 전용 컴포넌트 (예정)
│   ├── shared/            # Navbar, Footer, Loading, Error ✅
│   ├── games/             # 게임별 컴포넌트 (예정)
│   └── ui/                # Shadcn UI 컴포넌트 ✅
│
├── lib/                    # 유틸리티 및 설정
│   ├── games/             # 게임 메타데이터, 필터 로직 ✅
│   ├── game-engine/       # 게임 로직, 점수 계산 (예정)
│   ├── prisma.ts          # Prisma 클라이언트 ⭐ ✅
│   ├── auth.ts            # Next-auth 설정 ⭐ ✅
│   └── utils.ts           # 유틸리티 함수 ✅
│
├── hooks/                  # Custom Hooks
│   ├── use-room.ts
│   ├── use-socket.ts
│   ├── use-game.ts
│   ├── use-game-filter.ts
│   └── use-pin-validation.ts
│
├── types/                  # TypeScript 타입
│   ├── game.ts            # Game, GameCategory, GameFilter
│   ├── room.ts            # Room
│   ├── player.ts          # Player
│   └── socket-events.ts   # Socket 이벤트
│
├── stores/                 # Zustand 스토어
│   ├── room-store.ts
│   └── player-store.ts
│
├── server/                 # WebSocket 서버 (별도 실행)
│   ├── index.ts
│   ├── socket-handlers/
│   └── game-logic/
│
├── docs/                   # 문서
│   ├── PLANNING.md        # 전체 기획 (현재 문서)
│   ├── HOST_GUIDE.md      # 호스트 화면 상세 설계
│   ├── PLAYER_GUIDE.md    # 플레이어 화면 상세 설계
│   └── GAME_LIST.md       # 게임 아이디어 목록
│
├── README.md
└── package.json

🔌 WebSocket 통신 (간략)

주요 이벤트

// 방 관련
create:room, join:room, leave:room, close:room

// 게임 관련
game:start, game:pause, game:end
round:next, answer:submit

// 동기화
sync:players, sync:state, sync:score

🔍 상세 정보: 전체 WebSocket 아키텍처는 별도 문서화 예정

데이터 모델

핵심 인터페이스 (요약)

// 게임 메타데이터
interface Game {
  id: string;
  name: string;
  slug: string;
  description: string;
  category: GameCategory;
  difficulty: 1 | 2 | 3 | 4 | 5;
  minPlayers: number;
  maxPlayers: number;
  estimatedDuration: number;
  thumbnail: string;
  status: 'available' | 'coming_soon' | 'beta';
  isRecommended: boolean;
  tags: string[];
  settings: GameSettingsSchema;
}

// 게임 필터
interface GameFilter {
  categories: GameCategory[];
  difficulty: number[];
  playerCount: { min: number; max: number };
  duration: { min: number; max: number };
  status: 'all' | 'available' | 'coming_soon';
  searchQuery: string;
}

// 방
interface Room {
  id: string;
  code: string; // 6자리 PIN
  hostId: string;
  gameId: string;
  status: 'waiting' | 'playing' | 'finished';
  maxPlayers: number;
  gameSettings: Record<string, any>;
  players: Player[];
  createdAt: Date;
}

// 참가자
interface Player {
  id: string;
  socketId: string;
  roomId: string;
  nickname: string;
  isHost: boolean;
  score: number;
  hasAnswered: boolean;
  joinedAt: Date;
}

// 게임 세션
interface GameSession {
  id: string;
  roomId: string;
  gameId: string;
  currentRound: number;
  totalRounds: number;
  state: GameState;
  rounds: Round[];
  startedAt: Date;
}

🔍 상세 정보: 전체 데이터 모델 스키마는 types/ 디렉토리 참조

개발 로드맵

Phase 1: 기반 구축 ✅ (완료)

목표: 프로젝트 기본 설정 및 핵심 인프라 구축

Next.js 15 프로젝트 초기 설정
Tailwind CSS + Shadcn UI 구성
폴더 구조 및 라우팅 설정
TypeScript 타입 정의 (Game, Room, Player, GameFilter)
기본 레이아웃 및 공통 컴포넌트 (Navbar, Footer)

Phase 1.5: 회원 시스템 ⭐ ✅ (완료)

목표: 카카오 로그인 및 게임 템플릿 저장 기능

Phase 2: 호스트 경험 - 게임 선택 & 방 만들기 ✅ (완료)

목표: 카드 기반 게임 선택 & 방 만들기 시스템 구현

게임 메타데이터 정의 (7개 게임)
게임 카드 컴포넌트 (썸네일, 제목, 메타 정보)
게임 필터 시스템 (카테고리, 난이도)
게임 그리드 레이아웃 (반응형)
추천 게임 섹션
게임 상세 모달 (설명, 설정 폼)
방 생성 API (진행 중)

Phase 3: 핵심 기능 구현 (진행 중)

목표: 방 시스템 및 실시간 통신

랜딩 페이지 (PIN 입력 중앙 배치)
방 참여 플로우 UI (PIN 검증, 닉네임 모달)
호스트 대기실 (방 코드 표시, 참가자 관리)
플레이어 대기실 (게임 정보, 참가자 목록)
실시간 참가자 동기화 (WebSocket)
방 생성/참여 API
WebSocket 서버 구현
Redis 세션 관리

Phase 4: 첫 게임 구현 (2주)

목표: MVP 게임 2개 완성

게임 인터페이스 표준화
초성 게임 (호스트/플레이어 화면, 점수 계산)
밸런스 게임 (투표 시스템, 결과 시각화)
결과 화면 (순위, 통계)

Phase 5: 안정화 & 테스트 (1주)

목표: 버그 수정 및 UX 개선

엣지 케이스 처리
에러 핸들링
모바일 반응형 테스트
내부 테스트 및 피드백

Phase 6-8: 확장 및 배포

Phase 6: 게임 확장 (3-5개 추가 게임)
Phase 7: 고도화 (회원 시스템, 통계, 공유 기능)
Phase 8: 배포 & 운영 (최적화, 모니터링, 런칭)

참고 문서

📚 프로젝트 문서

PLANNING.md (현재 문서) - 프로젝트 전체 기획 및 큰 틀
HOST_GUIDE.md - 호스트 화면 상세 설계
PLAYER_GUIDE.md - 플레이어 화면 상세 설계
GAME_LIST.md - 게임 아이디어 및 상세 기획
README.md - 프로젝트 소개

🎯 핵심 디자인 원칙

플레이어 중심 UX

랜딩 페이지: PIN 입력을 중앙에 배치 (대부분의 사용자가 플레이어)
최소 입력: PIN과 닉네임만으로 즉시 참여
모바일 최적화: 터치 친화적 UI

호스트 경험 최적화

시각적 게임 선택 & 방 만들기: 카드 기반 UI로 쉬운 탐색
빠른 필터링: 상황에 맞는 게임 즉시 찾기
실시간 모니터링: 참가자 상태 한눈에 확인
유연한 컨트롤: 게임 진행 완전 제어

기술적 원칙

실시간성: WebSocket으로 즉각적인 동기화
확장성: 게임별 독립적인 컴포넌트
성능: 코드 스플리팅, 이미지 최적화
안정성: 에러 처리, 자동 재연결

🚀 시작하기

개발 환경 설정

# 프로젝트 생성
npx create-next-app@latest xingu --typescript --tailwind --app

# 의존성 설치
npm install socket.io-client zustand

# Shadcn UI 초기화
npx shadcn@latest init
npx shadcn@latest add button input dialog card badge

폴더 구조 생성

mkdir -p components/{landing,create,host,player,shared,games,ui}
mkdir -p lib/{games,game-engine}
mkdir -p hooks types stores server

다음 단계

게임 메타데이터 작성 (lib/games/game-data.ts)
타입 정의 (types/)
랜딩 페이지 구현
게임 선택 & 방 만들기 페이지 구현 ⭐ (Phase 2의 핵심)

💡 차별화 포인트

플레이어 중심 UX: PIN 입력을 랜딩 페이지 중앙에 배치
시각적 게임 탐색: 카드 기반 UI와 필터 시스템
설치 불필요: 웹 기반으로 별도 앱 설치 없이 즉시 사용
한국형 콘텐츠: 한국 문화에 최적화된 게임 및 질문
실시간 동기화: 모든 참가자가 동일한 경험
역할 분리: 호스트와 플레이어의 명확한 역할 및 화면 구분

문서 작성일: 2025.10.11
최종 수정일: 2025.10.11
버전: 4.0
주요 변경사항:

Phase 1, 1.5, 2 완료 상태 반영
카카오 로그인 연동 완료
게임 담기/바로 시작 기능 추가
대시보드 및 템플릿 시스템 구현
Prisma + SQLite DB 설정 완료
기술 스택 업데이트 (Next-auth, Prisma)

FilesExpand file tree

PLANNING.md

Latest commit

History