YearEndWebGame

A web-based game platform built with React, TypeScript, and Go, featuring both client and admin interfaces.

Project Structure

The project consists of three main components:

• client/ - Frontend web application for users
• admin/ - Administrative dashboard
• backend/ - Go-based backend server

Tech Stack

Frontend (Client & Admin)

• React 18 with TypeScript
• Vite for build tooling
• TailwindCSS for styling
• Shadcn UI components
• Redux Toolkit for state management
• React Router for navigation
• Framer Motion for animations

Backend

• Go 1.23.2
• Gin web framework
• PostgreSQL database
• Sessions-based authentication

Testing

See TESTING.md for full testing instructions. The E2E QA scope and smoke coverage live in e2e/README.md.

Getting Started

Prerequisites

• Node.js (Latest LTS version)
• Go 1.23.2 or higher
• PostgreSQL 15+

Database Setup

Local Development

1. Create a PostgreSQL database:

createdb yearendwebgame

2. Run the migration:

psql -d yearendwebgame -f backend/migrations/001_initial_schema.sql

3. Copy environment template:

cp backend/.env.example backend/.env

4. Edit backend/.env with your local database credentials:

DB_USER=postgres
DB_NAME=yearendwebgame
DB_PASSWORD=your_password
SESSION_KEY=your-secret-key

Production (Railway)

The backend is configured to use Railway's DATABASE_URL automatically when deployed. Railway PostgreSQL addon provides:

• Automatic DATABASE_URL injection
• Internal networking (zero latency)
• Automatic backups

Installation

1. Install frontend dependencies:

# Client
cd client
npm install

# Admin
cd ../admin
npm install

2. Start the development servers:

# Backend
cd backend
go run .

# Client (in separate terminal)
cd client
npm run dev

# Admin (in separate terminal)
cd admin
npm run dev

Ports

• Backend: 8080
• Client: 5173
• Admin: 5174

Admin Authentication

Admin endpoints are protected with API key authentication. This prevents unauthorized access to game controls.

Setup

1. Generate an API key:

openssl rand -hex 16

2. Configure the backend: Add to your .env file (or Railway environment variables):

ADMIN_API_KEY=your-generated-api-key-here

3. Configure the admin dashboard: Add to admin/.env:

VITE_ADMIN_API_KEY=your-generated-api-key-here

Protected Endpoints

Method	Endpoint	Description
POST	/game/create	Create a new game session
POST	/game/end	End a game session
POST	/game/session-config	Update session configuration
POST	/admin/reset-event	Reset game event
GET	/admin/join	WebSocket connection for admin

Authentication Methods

REST API: Include the API key in the Authorization header:

curl -X POST http://localhost:8080/game/create \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"createdBy": "admin-1"}'

WebSocket: Include the API key as a query parameter:

ws://localhost:8080/admin/join?token=your-api-key

Security Notes

• Never commit API keys to source control
• Use different keys for development and production
• Rotate keys periodically
• The admin dashboard automatically includes the API key from environment variables

---

Kahoot-Style PIN Game Sessions

The platform includes a Kahoot-style PIN-based game session system for easy player joining without authentication.

How It Works

1. Admin Creates Game: Admin clicks "Tạo Mã PIN Mới" in the admin dashboard
2. Players Join: Players visit year-end-web-game.vercel.app and enter the 6-digit PIN
3. Player Flow: Players enter nickname, select team (or auto-assign), and confirm
4. Real-time Updates: Admin sees connected players grouped by team in real-time

API Endpoints

Method	Endpoint	Description
POST	/game/create	Create a new game session with PIN (requires auth)
POST	/game/validate-pin	Validate if PIN exists and is active
POST	/game/join	Join a game session with PIN and nickname
GET	/game/session?pin=XXX	Get session info and player count
POST	/game/end	End a game session (requires auth)

Create Session Request

curl -X POST http://localhost:8080/game/create \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"createdBy": "admin-1"}'

Response:

{
  "pin": "847291",
  "expiresAt": "2026-01-13T04:32:44+07:00",
  "createdAt": "2026-01-13T00:32:44+07:00",
  "message": "Game session created successfully"
}

Join Game Request

curl -X POST http://localhost:8080/game/join \
  -H "Content-Type: application/json" \
  -d '{
    "pin": "847291",
    "nickname": "Player1",
    "teamID": 1
  }'

Response:

{
  "playerId": "9365b751-e49a-488f-8ddf-b5a5e86a0f9a",
  "teamID": 1,
  "message": "Joined game successfully"
}

Rate Limiting

The PIN validation endpoint is rate-limited to prevent brute-force attacks:

• Maximum 10 attempts per minute per IP
• Returns 429 Too Many Requests when exceeded

Session Expiry

• Sessions expire after 4 hours of inactivity
• Expired sessions are automatically cleaned up every 5 minutes
• Maximum 200 players per session

Pre-commit Hooks

This project uses Husky (v9.1.7) and lint-staged (v15.5.3) to enforce code quality before commits.

Automatic Setup

Pre-commit hooks are automatically installed when you run:

pnpm install

This runs the prepare script which configures Husky hooks in .husky/.

What Gets Checked

Frontend (Admin & Client) - Per-package lint-staged configs:

• ESLint with --max-warnings=0 - blocks commits on lint errors
• Prettier - auto-formats staged files

Backend (Go) - Root lint-staged config:

• golangci-lint with --fix - lints and auto-formats Go files

Manual Execution

You can run pre-commit hooks manually:

# Check staged files only
pnpm exec lint-staged

# Debug mode (shows what would run)
pnpm exec lint-staged --debug

Bypassing Hooks

To bypass pre-commit hooks (not recommended):

HUSKY=0 git commit -m "message"

Config Files

• Root: package.json - lint-staged backend config
• Admin: admin/.lintstagedrc.json - ESLint + Prettier rules
• Client: client/.lintstagedrc.json - ESLint + Prettier rules
• Backend: backend/.golangci.yml - golangci-lint configuration

Environment Variables

Backend (Railway)

See backend/.env.example for all required environment variables.

Variable	Required	Description
DATABASE_URL	Production	Railway PostgreSQL connection string
DB_USER	Local	PostgreSQL username
DB_NAME	Local	PostgreSQL database name
DB_PASSWORD	Local	PostgreSQL password
SESSION_KEY	Yes	Secret for session cookies
PORT	No	Server port (default: 8080)
GIN_MODE	No	debug or release
SENTRY_DSN	No	Sentry error tracking

Frontend (Vercel)

Both admin/ and client/ apps need these environment variables configured in Vercel:

Variable	Required	Default	Description
VITE_API_URL	No	Railway URL	Backend API URL (e.g., https://yearendwebgame-production.up.railway.app)
VITE_WS_URL	No	Railway WSS	Backend WebSocket URL (e.g., wss://yearendwebgame-production.up.railway.app)
VITE_SENTRY_DSN	No	-	Sentry DSN for frontend error tracking

Note: If not set, the apps default to the Railway production URL. For local development, copy .env.example to .env and update the URLs to http://localhost:8080 and ws://localhost:8080.

Production URLs

• Client: https://year-end-web-game.vercel.app
• Admin: https://year-end-web-game-admin.vercel.app
• API: https://yearendwebgame-production.up.railway.app

---

CI/CD Pipeline

This project uses GitHub Actions for continuous integration and deployment.

Workflows

Workflow	File	Trigger	Description
CI	.github/workflows/ci.yml	PR to main/develop, push to main/develop	Runs all tests (backend + frontend)
Lint	.github/workflows/lint.yml	PR to main/develop, push to main/develop	Code quality checks (Go + TypeScript)
E2E	.github/workflows/e2e.yml	PR to main/develop, push to main/develop, manual dispatch	End-to-end Playwright tests

CI Workflow Details

Backend Tests:

• Go 1.24.0 with race detector (-race flag)
• PostgreSQL 15 service container
• Coverage reporting with go test -cover

Frontend Tests:

• Admin: Vitest with 170+ tests
• Client: Vitest with 390+ tests
• pnpm for package management

Lint Workflow Details

Backend:

• golangci-lint v1.63 with custom config (.golangci.yml)
• Security-focused linters enabled

Frontend:

• ESLint with TypeScript support
• Prettier formatting checks

E2E Workflow Details

• Playwright tests with Chromium browser
• Backend service with PostgreSQL
• Rate limiting configured for test environment
• Artifacts uploaded on failure (screenshots, traces)
• Manual dispatch with test pattern selection

Required Status Checks

Branch protection is configured to require:

• ✅ ci-summary - All tests must pass
• ✅ lint-summary - All lint checks must pass

Running Workflows Manually

You can trigger workflows manually from the GitHub Actions tab:

1. Go to Actions → Select workflow
2. Click Run workflow
3. Choose branch and parameters (for E2E)

Local Testing

Before pushing, ensure all checks pass locally:

# Backend tests
cd backend && go test -race ./...

# Frontend tests
cd admin && pnpm test
cd client && pnpm test

# E2E tests
cd e2e && pnpm test

# Linting
cd backend && golangci-lint run
cd admin && pnpm lint
cd client && pnpm lint

Workflow Configuration

• Concurrency: Workflows cancel previous runs on the same branch to save resources
• Timeouts: 10 minutes for CI/Lint, 20 minutes for E2E
• Caching: pnpm store and Go modules are cached for faster builds

Troubleshooting

Flaky E2E Tests:

• Check rate limiting configuration
• Verify backend health endpoint responds
• Review Playwright traces in artifacts

Backend Race Conditions:

• CI runs with -race flag enabled
• Check logs for data race warnings

Frontend Test Failures:

• Ensure all dependencies installed with pnpm install --frozen-lockfile
• Check for environment-specific test issues

Deployment

• Backend: Auto-deploys to Railway on push to main
• Frontend: Auto-deploys to Vercel on push to main
• No manual deployment steps required

---

Testing

See TESTING.md for full testing instructions. The E2E QA scope and smoke coverage live in e2e/README.md.