Hidden Catch - AI 기반 틀린그림찾기 게임
AI가 자동으로 틀린그림을 생성하는 인터랙티브 웹 게임
Hidden Catch는 사용자가 업로드한 이미지를 Google Gemini AI가 자동으로 분석하고 수정하여 틀린그림찾기 퍼즐을 생성하는 웹 기반 게임입니다.
🎮 라이브 데모 접속: http://3.35.22.142/
- 🎨 AI 자동 퍼즐 생성: Gemini Vision API로 객체 탐지, Imagen API로 이미지 자동 편집
- 🎮 인터랙티브 게임플레이: 3분 타이머, 목숨 시스템, 실시간 정답 확인
- 🏗️ 현대적 아키텍처: FastAPI, React, Celery 비동기 처리
- ☁️ AWS 클라우드 배포: EC2, RDS, S3를 활용한 확장 가능한 인프라
- 🐳 Docker 기반: 간편한 로컬 개발 및 배포 환경
- 이미지 업로드: 사용자가 최대 3장의 이미지를 업로드
- AI 처리:
- Vision API가 이미지에서 주요 객체 탐지
- Imagen API가 탐지된 객체를 자연스럽게 수정
- 게임 시작: 원본과 수정된 이미지를 비교하며 다른 부분 찾기
- 점수 계산: 정답 개수, 플레이 시간에 따라 점수 부여
- React 18: 컴포넌트 기반 UI
- CSS3: 반응형 디자인 및 애니메이션
- FastAPI: 고성능 비동기 API 서버
- SQLAlchemy 2.0: ORM 및 데이터베이스 관리
- Celery 5.5: 비동기 작업 처리 (AI 이미지 처리)
- Redis 7: 메시지 브로커 및 캐싱
- Google Gemini 2.5 Flash: 객체 탐지
- Google Imagen 3: 이미지 편집
- AWS S3: 이미지 스토리지
- AWS RDS: PostgreSQL 데이터베이스
- AWS EC2: 애플리케이션 호스팅
- Docker & Docker Compose: 컨테이너화
- Nginx: 리버스 프록시 및 정적 파일 서빙
- uv: Python 패키지 관리
term-project/
├── docs/ # 문서
│ ├── sequence-diagrams.md # 시퀀스 다이어그램
│ ├── userflow/ # 사용자 플로우
│ └── wireframe/ # 와이어프레임
├── src/
│ ├── front/
│ │ └── game-app/ # React 프론트엔드
│ │ ├── src/
│ │ │ ├── components/ # React 컴포넌트
│ │ │ └── App.js
│ │ └── package.json
│ ├── backend/ # FastAPI 백엔드
│ │ ├── app/
│ │ │ ├── api/ # API 엔드포인트
│ │ │ ├── models/ # SQLAlchemy 모델
│ │ │ ├── services/ # 비즈니스 로직
│ │ │ ├── worker/ # Celery 태스크
│ │ │ └── core/ # 설정 및 유틸리티
│ │ └── pyproject.toml
│ ├── infra/
│ │ └── nginx/ # Nginx 설정
│ └── docker-compose.yml # Docker 오케스트레이션
└── README.md
- Docker & Docker Compose
- Node.js 18+ (로컬 개발 시)
- Python 3.13+ (로컬 개발 시)
- 저장소 클론
git clone https://github.com/hidden-catch/hidden-catch1.git
cd hidden-catch1- 환경 변수 설정
cd src
cp .env.example .env
# .env 파일을 편집하여 필요한 키 입력:
# - DATABASE_URL
# - AWS_S3_BUCKET_NAME, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
# - GOOGLE_APPLICATION_CREDENTIALS (GCP 서비스 계정 키 경로)
# - GCP_PROJECT_ID- Docker Compose 실행
docker compose up -dcd src/front/game-app
npm install
npm start # http://localhost:3000cd src/backend
uv sync
source .venv/bin/activate # Windows: .venv\Scripts\activate
uvicorn app.main:app --reload- 홈페이지 접속: 브라우저에서 http://3.35.22.142 열기
- 이미지 업로드: "게임 시작" 버튼 클릭 후 1~3장의 이미지 선택
- AI 처리 대기: 퍼즐 생성 중 로딩 화면 표시 (약 30초~1분)
- 게임 플레이:
- 원본과 수정된 이미지를 비교
- 다른 부분을 클릭하여 정답 찾기
- 3분 제한 시간, 10개의 목숨
- 점수 확인: 모든 스테이지 완료 후 최종 점수 확인
User Browser
↓
Nginx (Port 80)
↓
FastAPI Backend (Port 8000) ←→ PostgreSQL (RDS)
↓ ↓
Redis (Port 6379) S3 Bucket
↓
Celery Worker → Vision API / Imagen API
자세한 시퀀스 다이어그램은 docs/sequence-diagrams.md를 참조하세요.
- Vision API로 이미지 내 객체 자동 탐지
- 탐지된 객체의 위치(bounding box) 정보 추출
- Imagen API로 특정 영역만 자연스럽게 수정
- S3에 원본 및 수정 이미지 저장
- 클릭 좌표 기반 정답 판정 (오차 범위 50px)
object-fit: contain보정으로 정확한 좌표 매핑- 실시간 점수 계산 및 진행 상태 추적
- 다중 스테이지 지원
- Celery로 이미지 처리를 백그라운드에서 실행
- Redis 메시지 큐를 통한 작업 분산
- 프론트엔드 폴링으로 진행 상태 확인
- 포함관계에 있는 객체들은(ex: 자전거 안에 바퀴) Imagen API가 동시에 수정하기 어려움.
- 유저 입장에서 큰 객체 보다는 작은 객체를 찾는 것이 더 흥미로움.
- Vision API가 탐지한 객체 중 포함관계에 있는 객체들은 트리구조에 담아서 리프 노드에 작은 객체가 모이게 처리 및 분리하여 Imagen API에 요청.
- S3 버킷 정책 확인 (CORS 설정)
- Presigned URL 만료 시간 확인 (기본 15분)
주요 엔드포인트:
POST /api/v1/games- 게임 생성POST /api/v1/games/{game_id}/uploads/complete- 업로드 완료GET /api/v1/games/{game_id}- 게임 상태 조회POST /api/v1/games/{game_id}/stages/{stage}/check- 정답 확인POST /api/v1/games/{game_id}/stages/{stage}/complete- 스테이지 완료
This project is licensed under the MIT License.
- Frontend & Infrastructure: [정찬수]
- Backend: [양승조]
- AI Integration: [양승조/정찬수]
- UI/UX Design: [윤석현]
프로젝트에 대한 질문이나 제안사항이 있으시면 이슈를 등록해주세요!