Realtime Leaderboard System

A real-time leaderboard system built with Spring Boot, Redis, and SQLite.This project involves creating a backend system for a real-time leaderboard service. The service will allow users to compete in various games or activities, track their scores, and view their rankings on a leaderboard. The system will feature user authentication, score submission, real-time leaderboard updates, and score history tracking. Redis sorted sets will be used to manage and query the leaderboards efficiently.

Features

• 🔐 JWT Authentication - Secure user authentication and authorization
• 🏆 Real-time Leaderboard - Fast ranking updates using Redis
• 💾 Persistent Storage - SQLite database for user data
• 📊 Score Management - Add, update, and retrieve user scores
• 🔒 Spring Security - Protected endpoints with role-based access
• 📚 API Documentation - Interactive Swagger/OpenAPI documentation
• ⚡ High Performance - Redis caching for fast leaderboard queries

Tech Stack

• Java 21
• Spring Boot 3.5.7
• Spring Security - Authentication & Authorization
• Spring Data JPA - Database operations
• Spring Data Redis - Caching and leaderboard management
• SQLite - Lightweight persistent storage
• JWT (JSON Web Tokens) - Secure authentication
• Lombok - Code simplification
• Springdoc OpenAPI - API documentation
• Maven - Build automation

Prerequisites

• Java 21 or higher
• Redis server (local or remote)
• Maven

Getting Started

1. Clone the Repository

git clone <repository-url>
cd RankingLeaderboard

2. Configure Application

Copy the template configuration file:

cp application-template.properties application.properties

Edit application.properties and configure the following:

spring.application.name=Rankingboard

# SQLITE CONFIG
spring.datasource.url=jdbc:sqlite:database.db
spring.datasource.driver-class-name=org.sqlite.JDBC
spring.jpa.database-platform=org.hibernate.community.dialect.SQLiteDialect
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

# REDIS CONFIG
spring.redis.host=localhost
spring.redis.port=6379

# JWT CONFIG
jwt.secret=YourSuperSecretKeyForJwtGenerationMustBeAtLeast32Bytes!
jwt.expiration=86400000

# SWAGGER
springdoc.api-docs.enabled=true
springdoc.swagger-ui.enabled=true

# LOGGING
logging.level.root=INFO
logging.level.com.leaderboard=DEBUG

Generate a secure JWT secret:

openssl rand -base64 32

3. Build the Project

Windows / Linux / macOS:

mvn clean install

4. Run the Application

mvn spring-boot:run

The application will start on http://localhost:8080 Swagger UI: http://localhost:8080/swagger-ui/index.html

API Documentation

Once the application is running, access the interactive API documentation at:

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI JSON: http://localhost:8080/v3/api-docs

Running Tests

Execute all tests:

mvn test

View test reports:

• Open build/reports/tests/test/index.html in your browser

Project Structure

src/
├── main/
│   ├── java/com/leaderboard/
│   │   ├── Main.java                 # Application entry point
│   │   ├── SecurityConfig.java       # Security configuration
│   │   ├── config/                   # Configuration classes
│   │   ├── controller/               # REST API controllers
│   │   ├── exception/                # Custom exceptions
│   │   ├── filter/                   # Security filters
│   │   ├── model/                    # Data models/entities
│   │   └── service/                  # Business logic services
|   |   |__ repository/               #Repository interfaces 
│   └── resources/
│       └── application.properties    # Configuration file
└── test/                             # Test files

High-Level System Architecture

Environment Variables

The application supports the following environment variables:

Variable	Description	Default
REDIS_HOST	Redis server hostname	localhost
REDIS_PORT	Redis server port	6379
REDIS_PASSWORD	Redis password	(empty)
JWT_SECRET	Secret key for JWT signing	(see application.properties)
JWT_EXPIRATION	JWT token expiration time (ms)	86400000 (24 hours)
DATABASE_URL	Database connection URL	jdbc:sqlite:test.db

Development

Development Tools

The project includes Spring Boot DevTools for automatic restart during development.

Code Quality

The project uses:

• Lombok to reduce boilerplate code
• Spring Boot validation for input validation
• JPA for database abstraction

Acknowledgments

• Built with Spring Boot and Redis