A modern, full-stack backgammon platform built with React, Node.js, and MongoDB. Play backgammon online with real-time gameplay, tournaments, ELO ratings, and cross-platform support.
- Real-time Multiplayer: Play live games with WebSocket communication
- Game Modes: Casual unranked games and competitive ranked matches
- Tournament System: Single/double elimination, round-robin tournaments
- ELO Rating System: Skill-based matchmaking and progression tracking
- Spectator Mode: Watch ongoing games and learn from others
- Responsive Design: Works seamlessly on desktop, tablet, and mobile
- Cross-Platform: Web browsers + native mobile apps (Android/iOS)
- User Profiles: Track statistics, achievements, and game history
- Real-time Chat: In-game messaging and community features
- Performance Analytics: Detailed game statistics and improvement insights
- Modern Tech Stack: React 18, Node.js, MongoDB, TypeScript
- Real-time Communication: Socket.IO for live gameplay
- State Management: Redux Toolkit for predictable state updates
- Mobile Apps: Capacitor for native Android/iOS deployment
- Monorepo Architecture: Shared code between frontend, backend, and mobile
playbg/
├── apps/
│ ├── backend/ # Node.js/Express API server
│ ├── frontend/ # React web application
│ └── mobile/ # Capacitor mobile app wrapper
├── packages/
│ ├── shared/ # Shared TypeScript types and utilities
│ └── game-logic/ # Core backgammon game engine
├── package.json # Root workspace configuration
└── README.md
- Node.js 18+ and npm 9+
- MongoDB (local or cloud instance)
- Git
-
Clone the repository
git clone <repository-url> cd playbg
-
Install dependencies
npm install
-
Set up environment variables
# Backend environment cp apps/backend/.env.example apps/backend/.env # Edit apps/backend/.env with your MongoDB URI and JWT secret
-
Build shared packages
npm run build --workspace=packages/shared npm run build --workspace=packages/game-logic
-
Start development servers
# Start both frontend and backend npm run dev # Or start individually npm run dev:backend # API server on http://localhost:5000 npm run dev:frontend # React app on http://localhost:3000
# Development
npm run dev # Start both frontend and backend
npm run dev:backend # Start only backend server
npm run dev:frontend # Start only frontend app
npm run dev:mobile # Start mobile development
# Building
npm run build # Build all packages
npm run build:backend # Build backend only
npm run build:frontend # Build frontend only
# Testing
npm run test # Run tests in all packages
npm run lint # Lint all packages
# Utilities
npm run clean # Clean all build artifactsThe backend is built with:
- Express.js - Web framework
- MongoDB + Mongoose - Database and ODM
- Socket.IO - Real-time communication
- JWT - Authentication
- TypeScript - Type safety
Key directories:
apps/backend/src/routes/- API endpointsapps/backend/src/models/- Database modelsapps/backend/src/socket/- WebSocket handlersapps/backend/src/middleware/- Express middleware
The frontend uses:
- React 18 - UI framework
- TypeScript - Type safety
- Tailwind CSS - Styling
- Redux Toolkit - State management
- React Router - Navigation
- Vite - Build tool
Key directories:
apps/frontend/src/components/- Reusable UI componentsapps/frontend/src/pages/- Route componentsapps/frontend/src/store/- Redux store and slicesapps/frontend/src/services/- API clients
The core game engine (packages/game-logic/) includes:
- BackgammonEngine - Game state management and move validation
- EloRating - Rating calculation system
- GameUtils - Utility functions for game operations
- Standard backgammon rules with doubling cube support
- Crawford rule implementation for match play
- Automatic move validation and legal move highlighting
- Pip count and match equity calculations
- ELO-based rating system (starting at 1200)
- Separate ratings for different game speeds
- Rating history and progression tracking
- Leaderboards and ranking systems
- Multiple tournament formats (elimination, round-robin)
- Automated bracket generation and management
- Prize pool distribution
- Tournament chat and spectator modes
# Build and generate Android APK
npm run build:mobile
cd apps/mobile
npx cap add android
npx cap sync android
npx cap open android# Build and generate iOS app
npm run build:mobile
cd apps/mobile
npx cap add ios
npx cap sync ios
npx cap open iosBackend (.env)
NODE_ENV=development
PORT=5000
MONGODB_URI=mongodb://localhost:27017/playbg
JWT_SECRET=your-super-secret-jwt-key
JWT_EXPIRE=7d
FRONTEND_URL=http://localhost:3000-
Local MongoDB
# Install MongoDB locally or use Docker docker run -d -p 27017:27017 --name mongodb mongo:latest -
MongoDB Atlas (Cloud)
- Create account at MongoDB Atlas
- Create cluster and get connection string
- Update
MONGODB_URIin.env
# Run all tests
npm run test
# Run tests for specific package
npm run test --workspace=packages/game-logic
npm run test --workspace=apps/backend
npm run test --workspace=apps/frontend# Build all packages for production
npm run build
# Start production server
npm start# Build and run with Docker Compose
docker-compose up --build- Development: Local development with hot reload
- Staging: Testing environment with production-like setup
- Production: Optimized build with monitoring and logging
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- TypeScript for type safety
- ESLint + Prettier for code formatting
- Conventional commits for commit messages
- Comprehensive testing for new features
This project is licensed under the MIT License - see the LICENSE file for details.
- Backgammon rules and gameplay mechanics
- Open source libraries and frameworks used
- Community feedback and contributions
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: [email protected]
Built with ❤️ for the backgammon community