How lucasroeder13/leaderboardlearning works
Project type and purpose
• This is a backend microservice (Spring Boot REST API) that exposes endpoints for user authentication, score submission, and real-time leaderboard retrieval.
• It uses Redis for fast ranking operations, SQLite for persistent user data, and JWT for stateless security.
File structure
• src/main/java/com/leaderboard/
• Main.java – application entry point
• config/ – DataSourceConfig, RedisConfig, OpenAPIConfig (bean definitions and third-party integrations)
• controller/ – REST controllers (AuthController, LeaderboardController, LeaderboardScoreController, MainController)
• service/ – business logic (AuthHandler, DBHandler, RedisDBHandler, JWTHandler)
• filter/ – JWTAuthenticationFilter for request filtering
• exception/ – custom exceptions and a global handler
• model/ – entity and DTO classes (UserModel, LeaderboardModel, PlayerScoreEntry, etc.)
• Configuration files at the root (application.properties, application-template.properties) and Gradle build scripts
• src/test – unit and integration tests for controllers and services
README for additional insights
• Tech stack: Spring Boot, Spring Security, Spring Data JPA, Spring Data Redis, JWT, SQLite, Lombok, Springdoc OpenAPI
• Features: JWT auth, role-based endpoint protection, Redis-based real-time leaderboard, Swagger UI
• Deployment assumptions: external Redis server, file-based SQLite DB
Main components
a. External actors
• Client (Web or mobile)
• Redis server (standalone or cluster)
• SQLite file (persistent store)
b. Application tiers (Spring Boot service)
• API Layer (Controllers + Filter)
• Service Layer (AuthHandler, DBHandler, RedisDBHandler, JWTHandler)
• Data Layer (JPA repositories interacting with SQLite; RedisTemplate for Redis)
• Configuration Beans (DataSourceConfig, RedisConfig, OpenAPIConfig, SecurityConfig)
c. Cross-cutting concerns
• Spring Security (SecurityConfig, JWTAuthenticationFilter)
• API documentation (OpenAPIConfig → Swagger UI)
• Exception handling (GlobalExceptionHandler)
Relationships and interactions
1. Client → HTTP request → JWTAuthenticationFilter (extracts and validates token via JWTHandler)
2. Filter passes to Controllers (AuthController or Leaderboard*Controller)
3. Controller invokes Service layer:
• AuthHandler handles signup/login (JPA → SQLite; returns a JWT)
• LeaderboardScoreController/LeaderboardController calls RedisDBHandler (sorted set operations) and DBHandler (fallback to persistent store)
4. Service layer uses DataSourceConfig’s DataSource and RedisConfig’s RedisTemplate
5. Responses return JSON to client
6. OpenAPIConfig exposes metadata at /v3/api-docs and Swagger UI
Architectural patterns and principles
• Layered architecture (Controller → Service → Repository)
• Dependency injection for configuration and beans
• Aspect-style exception handling (GlobalExceptionHandler)
• Filter chain for authentication (JWTAuthenticationFilter)
• Caching and in-memory ranking with Redis sorted sets
• Stateless REST with JWT tokens