# lucasroeder13/leaderboardlearning architecture

> Architecture diagram of the GitHub repository lucasroeder13/leaderboardlearning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucasroeder13/leaderboardlearning
- Repository: https://github.com/lucasroeder13/leaderboardlearning

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    Client["Web/Mobile Client"]:::external
    RedisServer["Redis Server"]:::datastore
    SQLiteDB["SQLite DB (file)"]:::datastore

    %% Spring Boot Service Components
    subgraph "Spring Boot Service"
        direction TB

        Main["Main.java"]:::config

        subgraph "Security Layer"
            direction TB
            SecurityConfig["SecurityConfig"]:::config
            JWTFilter["JWTAuthenticationFilter"]:::config
            GlobalExHandler["GlobalExceptionHandler"]:::config
        end

        subgraph "API Layer"
            direction TB
            AuthCtrl["AuthController"]:::controller
            LeaderboardCtrl["LeaderboardController"]:::controller
            ScoreCtrl["LeaderboardScoreController"]:::controller
            MainCtrl["MainController"]:::controller
        end

        subgraph "Service Layer"
            direction TB
            AuthHandler["AuthHandler"]:::service
            JWTHandler["JWTHandler"]:::service
            DBHandler["DBHandler"]:::service
            RedisDBHandler["RedisDBHandler"]:::service
        end

        subgraph "Config Beans"
            direction TB
            DataSourceCfg["DataSourceConfig"]:::config
            RedisCfg["RedisConfig"]:::config
            OpenAPICfg["OpenAPIConfig"]:::config
        end
    end

    %% Data Layer (external shown above)
    %% Connections
    Client -->|"HTTP Request"| JWTFilter
    SecurityConfig -->|configure| JWTFilter
    JWTFilter -->|filter/validate JWT| AuthCtrl
    JWTFilter -->|filter/validate JWT| LeaderboardCtrl
    JWTFilter -->|filter/validate JWT| ScoreCtrl
    JWTFilter -->|filter/validate JWT| MainCtrl

    AuthCtrl -->|"POST /auth/*"| AuthHandler
    LeaderboardCtrl -->|"GET /leaderboard"| RedisDBHandler
    LeaderboardCtrl -->|"fallback"| DBHandler
    ScoreCtrl -->|"POST /leaderboard/score"| RedisDBHandler
    ScoreCtrl -->|log/store| DBHandler
    MainCtrl -->|"GET /health"| Main

    AuthHandler -->|JPA| DBHandler
    AuthHandler -->|issue JWT| JWTHandler
    JWTHandler -->|uses| SecurityConfig

    DBHandler -->|JDBC| SQLiteDB
    RedisDBHandler -->|Redis sorted set| RedisServer

    DataSourceCfg -->|provides DataSource| DBHandler
    RedisCfg -->|provides RedisTemplate| RedisDBHandler
    OpenAPICfg -->|expose /v3/api-docs| Client

    GlobalExHandler ---|handles| AuthCtrl
    GlobalExHandler ---|handles| LeaderboardCtrl
    GlobalExHandler ---|handles| ScoreCtrl
    GlobalExHandler ---|handles| MainCtrl

    %% Click events
    click Main "https://github.com/lucasroeder13/leaderboardlearning/blob/master/src/main/java/com/leaderboard/Main.java"
    click SecurityConfig "https://github.com/lucasroeder13/leaderboardlearning/blob/master/src/main/java/com/leaderboard/SecurityConfig.java"
    click DataSourceCfg "https://github.com/lucasroeder13/leaderboardlearning/blob/master/src/main/java/com/leaderboard/config/DataSourceConfig.java"
    click RedisCfg "https://github.com/lucasroeder13/leaderboardlearning/blob/master/src/main/java/com/leaderboard/config/RedisConfig.java"
    click OpenAPICfg "https://github.com/lucasroeder13/leaderboardlearning/blob/master/src/main/java/com/leaderboard/config/OpenAPIConfig.java"
    click JWTFilter "https://github.com/lucasroeder13/leaderboardlearning/blob/master/src/main/java/com/leaderboard/filter/JWTAuthenticationFilter.java"
    click AuthCtrl "https://github.com/lucasroeder13/leaderboardlearning/blob/master/src/main/java/com/leaderboard/controller/AuthController.java"
    click LeaderboardCtrl "https://github.com/lucasroeder13/leaderboardlearning/blob/master/src/main/java/com/leaderboard/controller/LeaderboardController.java"
    click ScoreCtrl "https://github.com/lucasroeder13/leaderboardlearning/blob/master/src/main/java/com/leaderboard/controller/LeaderboardScoreController.java"
    click MainCtrl "https://github.com/lucasroeder13/leaderboardlearning/blob/master/src/main/java/com/leaderboard/controller/MainController.java"
    click AuthHandler "https://github.com/lucasroeder13/leaderboardlearning/blob/master/src/main/java/com/leaderboard/service/AuthHandler.java"
    click JWTHandler "https://github.com/lucasroeder13/leaderboardlearning/blob/master/src/main/java/com/leaderboard/service/JWTHandler.java"
    click DBHandler "https://github.com/lucasroeder13/leaderboardlearning/blob/master/src/main/java/com/leaderboard/service/DBHandler.java"
    click RedisDBHandler "https://github.com/lucasroeder13/leaderboardlearning/blob/master/src/main/java/com/leaderboard/service/RedisDBHandler.java"

    %% Styling
    classDef controller fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef service fill:#E5F9E0,stroke:#28A745,color:#28A745;
    classDef datastore fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00;
    classDef config fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
    classDef external fill:#FFFFFF,stroke:#000000;
```
