🎮 Guess Which?

An Educational Web Game for Learning Research Paradigms, Approaches, and Methods

---

🧭 Project Overview

Guess Which? is a two-player web-based educational game inspired by Guess Who?.
Players ask yes/no questions to infer the opponent’s target card (Paradigm / Approach / Method).
The project features real-time gameplay, interactive cards, and persistent match records.

• 🧩 Course: COMPSCI 399 Capstone Project, 2025 S2 — Team QAQ
• this is our final project report project report

---

📋 Project Management

• Project Management Board:
  jira
• Repository:
  github

---

⚙️ Technologies

Frontend

• Vue 3
• Vite 5
• Pinia 2 (state management)
• Element Plus 2 (UI components)
• Socket.IO Client 4.7+
• Tailwind-style theme (custom)

Backend

• Node.js 20+
• Express 4.19+
• Socket.IO Server 4.7+
• bcrypt 5.1.1 (password hashing)
• dotenv 16.4+ (environment variables)

Database

• MySQL 8.0.43
• SQL dump: Dump20251001.sql
• Tables: users, players, rooms, room_members, matches, turns, turn_answers, guesses, cards
  (with foreign keys and indexes)

Deployment

• Alibaba Cloud ECS (Hong Kong)
• CentOS 7.9
• Baota (BT Panel) — visual management for Node, Nginx, MySQL
• Nginx reverse proxy + HTTPS
• ICP Filing (if applicable)

---

🧩 System Architecture

Frontend (Vue 3 + Socket.IO client)
        ↓
Controllers (auth/card/room/match.controller.js)
        ↓
Service Layer (auth.service.js / card.service.js / room.service.js / room.state.js)
        ↓
Models (user.model.js / room.model.js)
        ↓
MySQL 8 (Dump20251001.sql)

• room.state.js — business/service layer, in-memory RoomState (players, turns, Q&A, snapshots)
• room.service.js — matchmaking, readiness, and state transitions
• card.service.js — card retrieval and metadata
• auth.service.js — registration/login with bcrypt

---

💻 Installation & Setup

Prerequisites: Node.js 20+, MySQL 8.0.43, Git.
Optional: Docker / Baota / Nginx for deployment.

1. Clone

git clone https://github.com/uoa-compsci399-s2-2025/capstone-project-s2-2025-team-32.git
cd guess-which

2. Database

# Create schema and seed data
mysql -u root -p < Dump20251001.sql

3. Backend

cd ./Backend
npm install
npm start  

4. Frontend

cd ./Frontend
npm install
npm run dev  # open http://localhost:5173

---

🚀 Usage Examples

1. Create & Join Room

   • Player A creates a room and gets a 6-character code.
   • Player B enters the code to join.

2. Start Match

   • Each side receives 16 cards.
   • undo/reset/surrender functions
   • Use yes/no questions via real-time Socket.IO events.
   • Make a guess when confident.

3. End & Review

   • Show summary: duration, turns, selected cards, and guesses.

---

🌐 Deployed URL

Keep the site available until final marks are released.

• Production URL:
  https://team-32-qaq.xyz/
• Environment: Alibaba Cloud (HK) · CentOS 7.9
• Panel: Baota (Node, Nginx, MySQL)
• Reverse Proxy: Nginx with HTTPS
• Configuration: via .env (never commit secrets)

---

🔮 Future Plan

• AI Single-Player Mode: Add AI opponent for solo play and learning reinforcement
• Data Analytics Dashboard: Track user progress and learning performance
• Online Matchmaking: Enable cross-region multiplayer matches
• Internationalization: Expand multilingual support (e.g., Māori)
• Educator Mode: Customizable sets for classroom use
• PWA / Mobile optimization
• Enable scalable deployment in authentic classroom environments as well as independent self-learning scenarios.

---

🙏 Acknowledgements

• Supervisors: Ms. Tracy, Ms. Asma
• Team QAQ: Jue Wang, Siyun Liu, Jiawen Zhou, Lisha Zou, Tianze Wang
• References / Tutorials:
  • Socket.IO Docs — https://socket.io/docs/v4
  • Express Guide — https://expressjs.com/
  • Vue 3 Guide — https://vuejs.org/guide/introduction.html
  • Baota Docs — https://www.bt.cn/bbs/
  • Node.js — https://nodejs.org/docs/latest/api/
  • Docker Compose — https://docs.docker.com/compose/
  • SQL schema design — https://dev.mysql.com/doc/refman/8.0/en/
  • jsonwebtoken (JWT Auth) — https://github.com/auth0/node-jsonwebtoken
  • bcrypt (Password hashing) — https://github.com/kelektiv/node.bcrypt.js

---