IndiChess - Microservices Chess Platform

A full-stack, real-time multiplayer chess application built with microservices architecture. Play chess with friends through matchmaking or private matches, featuring real-time gameplay, live chat, and time controls.

📋 Table of Contents

Features
Architecture
Tech Stack
Project Structure
Prerequisites
Installation & Setup
Running the Application
API Documentation
Folder Structure
Configuration
Troubleshooting
Contributing

✨ Features

Core Gameplay

⚡ Real-time Multiplayer Chess - Play with opponents in real-time using WebSocket
🎯 Matchmaking System - Quick match with players of similar skill
🔒 Private Matches - Create and share match IDs to play with friends
⏱️ Time Controls - Blitz (3+0) and Rapid (10+0) game modes
💬 In-game Chat - Communicate with your opponent during matches
🏆 Game Outcomes - Win, loss, draw, and resignation tracking

Authentication

🔐 JWT Authentication - Secure token-based authentication
🌐 OAuth 2.0 Integration - Login with Google and GitHub
👤 User Profiles - Manage your account and view game history

Technical Features

🎨 Modern UI - Beautiful, responsive interface with Tailwind CSS
🔄 Service Discovery - Eureka for automatic service registration
🌉 API Gateway - Centralized routing and load balancing
📡 WebSocket Support - Real-time bidirectional communication
🗄️ PostgreSQL - Reliable data persistence

🏗️ Architecture

This project follows a microservices architecture with the following services:

┌─────────────────────────────────────────────────────────────┐
│                        FRONTEND                             │
│                    React + TypeScript                       │
│                    (Port 5173/8081)                         │
└──────────────┬─────────────────────────┬────────────────────┘
               │                         │
       REST API│                         │WebSocket (Direct)
               │                         │
               ▼                         ▼
    ┌──────────────────┐      ┌──────────────────────┐
    │   API GATEWAY    │      │   MATCH SERVICE      │
    │   (Port 8080)    │      │   (Port 8082)        │
    └────────┬─────────┘      │  - Game Logic        │
             │                │  - WebSocket Server  │
             │                │  - Matchmaking       │
    ┌────────┴─────────┐      │  - Chat              │
    │                  │      └──────────────────────┘
    ▼                  ▼
┌─────────────┐  ┌──────────────────┐
│USER SERVICE │  │  MATCH SERVICE   │
│(Port 8083)  │  │  (Port 8082)     │
│- Auth       │  │- Match CRUD      │
│- JWT        │  │- REST APIs       │
│- OAuth2     │  └──────────────────┘
└─────────────┘
         │
         ▼
┌──────────────────┐
│  EUREKA SERVER   │
│  (Port 8761)     │
│- Service Registry│
└──────────────────┘

Service Communication

REST APIs → Routed through API Gateway (Port 8080)
WebSocket → Direct connection to Match Service (Port 8082)
Service Discovery → All services register with Eureka

🛠️ Tech Stack

Backend

Java 17 - Primary programming language
Spring Boot 3.2 - Application framework
Spring Cloud - Microservices infrastructure
- Eureka Server - Service discovery
- Spring Cloud Gateway - API Gateway
Spring Security - Authentication & authorization
Spring WebSocket - Real-time communication
PostgreSQL - Primary database
JWT - Token-based authentication
OAuth 2.0 - Social login (Google, GitHub)
Maven - Dependency management

Frontend

React 18 - UI framework
TypeScript - Type-safe JavaScript
Vite - Build tool and dev server
Tailwind CSS - Utility-first CSS framework
shadcn/ui - Component library
React Router - Client-side routing
STOMP.js - WebSocket client
SockJS - WebSocket fallback

📁 Project Structure

IndiChess-MicroServices/
│
├── Api-Gateway/                 # API Gateway Service
│   ├── src/
│   │   └── main/
│   │       ├── java/
│   │       │   └── com.Api_Gateway/
│   │       │       └── ApiGatewayApplication.java
│   │       └── resources/
│   │           ├── application.properties
│   │           └── application.yaml    # Gateway routes & CORS config
│   └── pom.xml
│
├── Eureka-Server/              # Service Registry
│   ├── src/
│   │   └── main/
│   │       ├── java/
│   │       │   └── com.Eureka_Server/
│   │       │       └── EurekaServerApplication.java
│   │       └── resources/
│   │           └── application.properties
│   └── pom.xml
│
├── Match-Service/              # Game Logic & WebSocket
│   ├── src/
│   │   └── main/
│   │       ├── java/
│   │       │   └── com.Match_Service/
│   │       │       ├── Config/
│   │       │       │   ├── SecurityConfig.java
│   │       │       │   ├── WebSocketConfig.java
│   │       │       │   └── WebSocketAuthInterceptor.java
│   │       │       ├── Controller/
│   │       │       │   ├── MatchController.java
│   │       │       │   ├── MatchmakingController.java
│   │       │       │   ├── GameWebSocketController.java
│   │       │       │   └── ChatController.java
│   │       │       ├── Service/
│   │       │       │   └── MatchService.java
│   │       │       ├── Model/
│   │       │       ├── Repository/
│   │       │       ├── Security/
│   │       │       └── dto/
│   │       └── resources/
│   │           └── application.properties
│   └── pom.xml
│
├── User-Service/               # Authentication & User Management
│   ├── src/
│   │   └── main/
│   │       ├── java/
│   │       │   └── com.User_Service/
│   │       │       ├── Config/
│   │       │       ├── Controller/
│   │       │       ├── Service/
│   │       │       ├── Model/
│   │       │       ├── Repository/
│   │       │       └── Security/
│   │       └── resources/
│   │           ├── application.properties
│   │           ├── static/            # OAuth2 success pages
│   │           └── templates/
│   └── pom.xml
│
└── frontend/                   # React Frontend
    ├── src/
    │   ├── components/         # Reusable UI components
    │   ├── contexts/          # React contexts (Auth, etc.)
    │   ├── hooks/             # Custom React hooks
    │   ├── lib/               # Utilities and API client
    │   │   └── api.ts         # API service layer
    │   ├── pages/             # Page components
    │   │   ├── ChessGame.tsx  # Main game interface
    │   │   ├── Play.tsx       # Matchmaking page
    │   │   ├── CreateMatch.tsx
    │   │   ├── Dashboard.tsx
    │   │   ├── Login.tsx
    │   │   └── Register.tsx
    │   └── types/             # TypeScript type definitions
    ├── public/
    ├── package.json
    ├── tailwind.config.js
    ├── tsconfig.json
    └── vite.config.ts

📋 Prerequisites

Before you begin, ensure you have the following installed:

Required Software

Java 17 or higher - Download
Maven 3.8+ - Download
Node.js 18+ - Download
PostgreSQL 14+ - Download
Git - Download

Optional (Recommended)

IntelliJ IDEA or Eclipse - For Java development
VS Code - For frontend development
Postman - For API testing

🚀 Installation & Setup

1. Clone the Repository

git clone https://github.com/yourusername/IndiChess-MicroServices.git
cd IndiChess-MicroServices

2. Database Setup

Create Databases

# Connect to PostgreSQL
psql -U postgres

# Create databases
CREATE DATABASE user_service_db;
CREATE DATABASE match_service_db;

# Exit psql
\q

Configure Database Credentials

Update database credentials in each service's application.properties:

User-Service (User-Service/src/main/resources/application.properties):

spring.datasource.url=jdbc:postgresql://localhost:5432/user_service_db
spring.datasource.username=postgres
spring.datasource.password=yourpassword

Match-Service (Match-Service/src/main/resources/application.properties):

spring.datasource.url=jdbc:postgresql://localhost:5432/match_service_db
spring.datasource.username=postgres
spring.datasource.password=yourpassword

3. Configure JWT Secret

Both User-Service and Match-Service need the same JWT secret for token validation.

User-Service (application.properties):

jwt.secret=your-very-long-secret-key-min-256-bits-recommended-for-hs384

Match-Service (application.properties):

jwt.secret=your-very-long-secret-key-min-256-bits-recommended-for-hs384

⚠️ Important: Use a secure, random secret in production!

4. OAuth 2.0 Configuration (Optional)

To enable Google/GitHub login, add credentials to User-Service:

application.properties:

# Google OAuth2
spring.security.oauth2.client.registration.google.client-id=your-google-client-id
spring.security.oauth2.client.registration.google.client-secret=your-google-client-secret

# GitHub OAuth2
spring.security.oauth2.client.registration.github.client-id=your-github-client-id
spring.security.oauth2.client.registration.github.client-secret=your-github-client-secret

How to get credentials:

Google: Google Cloud Console
GitHub: GitHub Developer Settings

5. Build All Services

# Build Eureka Server
cd Eureka-Server
mvn clean install
cd ..

# Build API Gateway
cd Api-Gateway
mvn clean install
cd ..

# Build User Service
cd User-Service
mvn clean install
cd ..

# Build Match Service
cd Match-Service
mvn clean install
cd ..

6. Setup Frontend

cd frontend
npm install

▶️ Running the Application

Start Services in Order

Services must be started in this specific order:

1. Start Eureka Server (Service Registry)

cd Eureka-Server
mvn spring-boot:run

Wait for: Eureka Server started on port 8761

Verify at: http://localhost:8761

2. Start User Service

cd User-Service
mvn spring-boot:run

Wait for: User Service started on port 8083

3. Start Match Service

cd Match-Service
mvn spring-boot:run

Wait for: Match Service started on port 8082

4. Start API Gateway

cd Api-Gateway
mvn spring-boot:run

Wait for: API Gateway started on port 8080

5. Start Frontend

cd frontend
npm run dev

Frontend will start on: http://localhost:5173

🎮 Using the Application

1. Register an Account

Go to http://localhost:5173/register
Create an account with email/password
Or use Google/GitHub OAuth

2. Play Chess

Quick Match (Matchmaking)

Click "Play" from dashboard
Select game mode (Blitz or Rapid)
Wait for opponent
Game starts automatically when matched

Private Match

Click "Create Private Match"
Share the Match ID with a friend
Friend enters Match ID to join
Game starts when both players ready

3. Game Features

Make Moves: Click piece → Click destination
Chat: Use chat panel to message opponent
Resign: Click flag icon to resign
Time: Watch your clock and opponent's clock

📚 API Documentation

Authentication Endpoints

POST /auth/register
POST /auth/login
GET  /auth/me

Match Endpoints

POST /match/create-private
POST /match/{id}/join
GET  /match/{id}
POST /match/{id}/resign

WebSocket Endpoints

CONNECT /ws (Port 8082)
SUBSCRIBE /topic/matchmaking/{email}
SUBSCRIBE /topic/game/{matchId}
SUBSCRIBE /topic/game/{matchId}/chat
SEND /app/matchmaking/join
SEND /app/game/{matchId}/move
SEND /app/game/{matchId}/chat

⚙️ Configuration

Service Ports

Service	Port	Description
Frontend	5173	React development server
Frontend (Build)	8081	Production build (optional)
API Gateway	8080	Main entry point for REST APIs
User Service	8083	Authentication & user management
Match Service	8082	Game logic & WebSocket
Eureka Server	8761	Service registry

Environment Variables

Create .env file in frontend/:

VITE_API_URL=http://localhost:8080

CORS Configuration

CORS is configured in API Gateway (application.yaml):

spring:
  cloud:
    gateway:
      globalcors:
        cors-configurations:
          '[/**]':
            allowed-origins:
              - "http://localhost:5173"
              - "http://localhost:8081"
            allowed-methods:
              - GET
              - POST
              - PUT
              - DELETE
            allow-credentials: true

🐛 Troubleshooting

Common Issues

1. Services Not Registering with Eureka

Symptom: Service doesn't appear in Eureka dashboard

Solution:

Ensure Eureka Server is running first
Check eureka.client.service-url.defaultZone in application.properties
Verify network connectivity to localhost:8761

2. Database Connection Errors

Symptom: org.postgresql.util.PSQLException

Solution:

# Check PostgreSQL is running
sudo service postgresql status

# Verify databases exist
psql -U postgres -l

# Check credentials in application.properties

3. CORS Errors in Browser

Symptom: "blocked by CORS policy"

Solution:

Ensure you're using correct ports (REST→8080, WebSocket→8082)
Check ChessGame.tsx uses http://localhost:8082/ws for WebSocket
Verify API Gateway CORS configuration

4. JWT Token Errors

Symptom: "Invalid token" or 401 Unauthorized

Solution:

Ensure same JWT secret in User-Service and Match-Service
Clear browser localStorage and re-login
Check token expiration (default 24 hours)

5. WebSocket Connection Fails

Symptom: "Failed to connect to WebSocket"

Solution:

Verify Match Service is running on port 8082
Check browser console for exact error
Ensure JWT token is valid
Try hard refresh (Ctrl+Shift+R)

6. Port Already in Use

Symptom: Port 8080 already in use

Solution:

# Find process using port
lsof -i :8080

# Kill process (replace PID)
kill -9 PID

# Or change port in application.properties
server.port=8081

🔧 Development

Running in Development Mode

Backend (Hot Reload with Spring DevTools):

cd User-Service
mvn spring-boot:run -Dspring-boot.run.profiles=dev

Frontend (Hot Reload):

cd frontend
npm run dev

Building for Production

Backend:

# Each service
mvn clean package -DskipTests

# Run JAR
java -jar target/service-name.jar

Frontend:

npm run build
npm run preview  # Test production build

Database Migrations

Using Flyway (if configured):

mvn flyway:migrate

📊 Project Statistics

Total Services: 4 (Eureka, Gateway, User, Match)
Lines of Code: ~15,000+
Frontend Components: 20+
API Endpoints: 15+
WebSocket Events: 6+

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Authors

Manisha Priya

🙏 Acknowledgments

Chess piece Unicode symbols
Spring Boot team for excellent microservices framework
React community for frontend tools
shadcn/ui for beautiful components

📧 Support

For support, email manishapriya1325@gmail.com or open an issue in the repository.

🗺️ Roadmap

Made with ❤️ by Chess Enthusiasts

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.idea		.idea
Api-Gateway		Api-Gateway
Eureka-Server		Eureka-Server
Match-Service		Match-Service
User-Service		User-Service
frontend		frontend
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

IndiChess - Microservices Chess Platform

📋 Table of Contents

✨ Features

Core Gameplay

Authentication

Technical Features

🏗️ Architecture

Service Communication

🛠️ Tech Stack

Backend

Frontend

📁 Project Structure

📋 Prerequisites

Required Software

Optional (Recommended)

🚀 Installation & Setup

1. Clone the Repository

2. Database Setup

Create Databases

Configure Database Credentials

3. Configure JWT Secret

4. OAuth 2.0 Configuration (Optional)

5. Build All Services

6. Setup Frontend

▶️ Running the Application

Start Services in Order

1. Start Eureka Server (Service Registry)

2. Start User Service

3. Start Match Service

4. Start API Gateway

5. Start Frontend

🎮 Using the Application

1. Register an Account

2. Play Chess

Quick Match (Matchmaking)

Private Match

3. Game Features

📚 API Documentation

Authentication Endpoints

Match Endpoints

WebSocket Endpoints

⚙️ Configuration

Service Ports

Environment Variables

CORS Configuration

🐛 Troubleshooting

Common Issues

1. Services Not Registering with Eureka

2. Database Connection Errors

3. CORS Errors in Browser

4. JWT Token Errors

5. WebSocket Connection Fails

6. Port Already in Use

🔧 Development

Running in Development Mode

Building for Production

Database Migrations

📊 Project Statistics

🤝 Contributing

📝 License

👥 Authors

🙏 Acknowledgments

📧 Support

🗺️ Roadmap

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Packages