A complete full-stack real-time leaderboard system built with modern web technologies. Features user authentication, game management, score tracking, live leaderboards, direct messaging, and social features.
- ✅ JWT Authentication - Secure access & refresh token rotation
- ✅ Role-Based Access Control - User/Admin permissions
- ✅ Game Management - CRUD operations with image uploads
- ✅ Score Submission - Real-time score tracking with metadata
- ✅ Live Leaderboards - Global, per-game, and daily rankings
- ✅ Direct Messaging - Real-time chat with unread tracking
- ✅ Social Features - Friend requests, user connections
- ✅ WebSocket Support - Live updates via Socket.IO
- ✅ Responsive UI - Modern React interface with Tailwind CSS
- Runtime: Node.js with TypeScript
- Framework: Express 5.1
- Database: PostgreSQL (via Prisma ORM)
- Cache: Redis 5.9
- Real-time: Socket.IO 4.8
- Validation: Zod
- Auth: JWT (jsonwebtoken)
- File Upload: Multer + Cloudinary
- Security: bcrypt password hashing
- Framework: React 18 with TypeScript
- Build Tool: Vite
- State Management: Zustand
- Data Fetching: TanStack Query (React Query)
- Styling: Tailwind CSS
- Forms: React Hook Form + Zod
- Real-time: Socket.IO Client
- Icons: Lucide React
- Animations: Framer Motion
- Node.js >= 18.x
- PostgreSQL >= 14.x
- Redis >= 6.x
- Cloudinary account (for image uploads)
# Install backend dependencies
cd server
npm install
# Install frontend dependencies
cd ../client
npm install
# Return to root
cd ..Create a .env file in the server/ directory:
# Server
PORT=5000
NODE_ENV=development
# Database (PostgreSQL)
DATABASE_URL="postgresql://user:password@localhost:5432/leaderboard?schema=public"
# Redis
REDIS_URL="redis://localhost:6379"
# JWT Secrets
JWT_SECRET="your-super-secret-jwt-key-here"
JWT_REFRESH_TOKEN_SECRET="your-refresh-token-secret-here"
# Cloudinary (for image uploads)
CLOUDINARY_CLOUD_NAME="your-cloud-name"
CLOUDINARY_API_KEY="your-api-key"
CLOUDINARY_API_SECRET="your-api-secret"cd server
# Generate Prisma Client
npx prisma generate
# Run migrations
npx prisma migrate dev
# (Optional) Open Prisma Studio
npx prisma studio# Terminal 1: Start Backend Server
cd server
npm run dev
# Server will start on http://localhost:5000
# Terminal 2: Start Frontend Client
cd client
npm run dev
# Client will start on http://localhost:5173 (or next available port)Open your browser and navigate to http://localhost:5173 to access the full application.
POST /v1/api/auth/register - Register new user
POST /v1/api/auth/login - Login (returns access + refresh tokens)
POST /v1/api/auth/refresh - Refresh access token
POST /v1/api/auth/logout - Logout (revoke refresh token)
GET /v1/api/users - Get all users (auth required)
GET /v1/api/users/:id - Get user by ID (auth required)
PUT /v1/api/users/:id - Update user (own profile or admin)
DELETE /v1/api/users/:id - Delete user (own profile or admin)
GET /v1/api/games - Get all games (public)
GET /v1/api/games/:id - Get game details (public)
POST /v1/api/games - Create game (admin only, supports image)
PUT /v1/api/games/:id - Update game (admin only, supports image)
DELETE /v1/api/games/:id - Delete game (admin only)
POST /v1/api/scores/:id - Submit score for game (auth required)
GET /v1/api/scores/:id/best - Get user's best score (auth required)
GET /v1/api/leaderboard/global - Global leaderboard
GET /v1/api/leaderboard/game/:id - Game-specific leaderboard
GET /v1/api/leaderboard/game/:id/daily - Daily leaderboard
GET /v1/api/leaderboard/game/:id/rank - User's rank (auth required)
Query params: ?limit=100 (default: 100)
POST /v1/api/messages/ - Send message (auth required)
GET /v1/api/messages/conversation/:id - Get conversation (auth required)
POST /v1/api/messages/mark-read - Mark messages as read (auth required)
GET /v1/api/messages/unread-count - Get unread count (auth required)
socket.emit("joinGameRoom", gameId); // Join game room for updates
socket.emit("leaveGameRoom", gameId); // Leave game roomsocket.on("leaderboard:update", (data) => {
// { gameId, userId, score, rank }
});
socket.on("message:new", (message) => {
// New message received
});
socket.on("message:sent", (message) => {
// Message sent confirmation
});
socket.on("message:unread_count", ({ count }) => {
// Updated unread message count
});const socket = io("http://localhost:5000", {
auth: {
token: "your-jwt-access-token",
},
});POST /v1/api/auth/register
Content-Type: application/json
{
"username": "player123",
"email": "player@example.com",
"password": "securePassword123"
}POST /v1/api/auth/login
Content-Type: application/json
{
"email": "player@example.com",
"password": "securePassword123"
}
# Response:
{
"message": "Login Successful",
"accessToken": "eyJhbGc...",
"refreshToken": "eyJhbGc...",
"user": {
"userId": "uuid",
"name": "player123",
"email": "player@example.com",
"role": "USER"
}
}POST /v1/api/games
Authorization: Bearer <admin-access-token>
Content-Type: multipart/form-data
slug: tetris-classic
title: Tetris Classic
description: Classic block-stacking puzzle game
metadata: {"maxLevel": 20, "scoreMultiplier": 100}
image: <file>POST /v1/api/scores/:gameId
Authorization: Bearer <access-token>
Content-Type: application/json
{
"score": 15000,
"meta": {
"level": 10,
"lines": 45,
"duration": 320
}
}
# Response:
{
"success": true,
"saved": { /* score object */ },
"leaderboardUpdated": true,
"rank": 3,
"score": 15000
}GET /v1/api/leaderboard/game/:gameId?limit=50
# Response:
[
{
"rank": 1,
"userId": "uuid",
"score": 25000,
"user": {
"id": "uuid",
"username": "topplayer",
"displayName": "Top Player",
"avatarUrl": "https://..."
}
},
...
]POST /v1/api/messages
Authorization: Bearer <access-token>
Content-Type: application/json
{
"toUserId": "recipient-uuid",
"content": "Hello! Good game!"
}- Responsive Design - Mobile-first approach with Tailwind CSS
- Modern UI Components - Clean, accessible interface
- Real-time Updates - Live leaderboard and message updates
- Form Validation - Client-side validation with error handling
- Loading States - Smooth loading indicators and skeletons
- User registration and login
- Form validation and error handling
- Secure token management
- User statistics and overview
- Quick action cards
- Top players preview
- Browse available games
- Game details with leaderboard preview
- Score submission with metadata support
- Global leaderboard rankings
- Game-specific leaderboards
- Real-time rank updates
- Daily leaderboard support
- Friend requests (send, accept, reject)
- Friends list management
- Real-time messaging system
- Unread message counters
- Game management (CRUD operations)
- User statistics overview
- Admin-only features
- User - Authentication, profile, roles
- Game - Game definitions with metadata
- Score - User scores per game
- Message - Direct messages between users
- RefreshToken - JWT refresh token management
- Friendship - Social connections
- Leaderboard - Cached in Redis sorted sets
Optimized queries with composite indexes on:
Score:[gameId, createdAt],[userId]Message:[toUserId, isRead],[fromUserId, createdAt],[toUserId, createdAt]
- ✅ Password hashing with bcrypt (10 rounds)
- ✅ JWT access tokens (1h expiry)
- ✅ Refresh token rotation (2d expiry)
- ✅ Token revocation on logout
- ✅ Role-based authorization
- ✅ Input validation with Zod
- ✅ SQL injection protection (Prisma)
- ✅ CORS configuration
.
├── client/ # React Frontend
│ ├── public/ # Static assets
│ ├── src/
│ │ ├── api/ # API endpoints & axios config
│ │ ├── components/ # Reusable UI components
│ │ │ ├── common/ # Basic components (Button, Input, etc.)
│ │ │ ├── features/ # Feature-specific components
│ │ │ └── layout/ # Layout components
│ │ ├── contexts/ # React contexts (legacy)
│ │ ├── hooks/ # Custom React hooks
│ │ ├── lib/ # Utilities (queryClient, utils)
│ │ ├── pages/ # Page components
│ │ │ ├── auth/ # Authentication pages
│ │ │ ├── dashboard/ # Dashboard pages
│ │ │ ├── games/ # Game-related pages
│ │ │ ├── leaderboard/ # Leaderboard pages
│ │ │ ├── chat/ # Chat pages
│ │ │ ├── friends/ # Friends pages
│ │ │ ├── profile/ # Profile pages
│ │ │ └── admin/ # Admin pages
│ │ ├── providers/ # Context providers
│ │ ├── stores/ # Zustand stores
│ │ ├── styles/ # Global styles
│ │ ├── types/ # TypeScript type definitions
│ │ └── utils/ # Helper functions
│ ├── package.json
│ ├── tsconfig.json
│ ├── vite.config.ts
│ └── README.md
├── server/ # Node.js Backend
│ ├── prisma/
│ │ ├── schema.prisma # Database schema
│ │ └── migrations/ # Migration history
│ ├── src/
│ │ ├── config/ # Configuration files
│ │ │ ├── db.ts # Prisma client
│ │ │ ├── redis.ts # Redis client
│ │ │ ├── cloudinary.ts # Cloudinary config
│ │ │ └── socket.ts # Socket.IO setup
│ │ ├── controllers/ # Request handlers
│ │ ├── middleware/ # Auth & role middleware
│ │ ├── routes/ # API route definitions
│ │ ├── schemas/ # Zod validation schemas
│ │ ├── services/ # Business logic
│ │ ├── types/ # TypeScript types
│ │ ├── utils/ # Helper functions
│ │ └── index.ts # App entry point
│ ├── .env # Environment variables
│ ├── package.json
│ ├── tsconfig.json
│ └── README.md
└── README.md # This file
cd server
npm run build
npm startcd client
npm run build
# Dist files will be in client/dist/- Set
NODE_ENV=production - Use secure JWT secrets (32+ characters)
- Configure production database URL
- Enable Redis persistence
- Set up CORS allowed origins
- Use managed Cloudinary account
- Database: Railway, Neon, Supabase
- Redis: Redis Cloud, Upstash
- Backend Hosting: Railway, Render, Fly.io
- Frontend Hosting: Vercel, Netlify, Railway
- CDN: Cloudinary (images)
- Redis Caching - Leaderboard data in sorted sets
- Database Indexes - Optimized query performance
- Connection Pooling - Prisma connection management
- Pagination - Cursor-based for messages, limit-based for leaderboards
- WebSocket - Efficient real-time updates
-
Backend Setup:
- Register user → Login → Get tokens
- Create admin user in DB:
UPDATE "User" SET role = 'ADMIN' WHERE email = '...' - Create games with admin token
- Submit scores and verify leaderboard updates
-
Frontend Testing:
- Register/login through the UI
- Browse games and submit scores
- Check real-time leaderboard updates
- Test friend requests and messaging
- Verify responsive design on mobile/desktop
-
Real-time Features:
- Test Socket.IO connections
- Open multiple browser tabs to verify live updates
- Test message delivery and friend request notifications
UPDATE "User" SET role = 'ADMIN' WHERE email = 'admin@example.com';npx prisma generateEnsure Redis is running:
redis-server
# or
docker run -d -p 6379:6379 redisnpx prisma migrate reset # ⚠️ Drops all data
npx prisma migrate devChange PORT in .env or kill process:
# Windows
netstat -ano | findstr :5000
taskkill /PID <PID> /F
# Linux/Mac
lsof -ti:5000 | xargs kill -9{
"start": "node dist/index.js",
"build": "tsc",
"dev": "nodemon --watch src --ext ts --exec \"npm run build && npm run start\"",
"postinstall": "prisma generate"
}{
"dev": "vite",
"build": "tsc -b && vite build",
"preview": "vite preview"
}- Fork the repository
- Create feature branch:
git checkout -b feature/amazing-feature - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Open Pull Request
ISC
Built with ❤️ for real-time gaming experiences - Full-stack application with modern React frontend and robust Node.js backend.
Happy Coding! 🎮🚀