# gallardos/multitask-backend architecture

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

- Interactive diagram: https://gitdiagram.com/gallardos/multitask-backend
- Repository: https://github.com/gallardos/multitask-backend

## Overview

##### Project Type and Purpose
- This project is a backend service for the Multitask browser game. It powers the global leaderboard system and exposes secure HTTP endpoints to submit and retrieve scores.
- It is built on Spring Boot, uses a stateless HTTP API secured by an API key, and interfaces with a database (PostgreSQL based on the README sample configuration).

##### Analyzing the File Structure
- The presence of typical Maven files (pom.xml, mvnw) and the src/main/java directory structure confirms it is a Java Spring Boot application.
- The backend package under com.multitask.backend is organized into distinct sub-packages:
- config: Contains configuration classes like ApiKeyFilter, CorsConfig, SecurityConfig, and ModelMapperConfig which handle API key authentication, CORS policies, and mapping configuration.
- controllers: Houses controllers such as ScoreController that manage incoming HTTP requests.
- domain/entity: Holds domain objects (Score, ScoreDTO) representing the core data models.
- repository: Contains ScoreRepository, likely managing database interactions.
- security: Includes ScoreSignatureValidator and other security-related classes.
- service and service/impl: Implements the business logic within ScoreService and its implementation ScoreServiceImpl.
- exception: Contains GlobalExceptionHandler for centralized error handling.
- The test directory mirrors these packages, ensuring that tests cover controller, service, and security behaviors.

a. Client/Frontend (External):
- Represents the browser-based game frontend making HTTP requests.
b. API Gateway / HTTP Entry Point:
- Incoming requests flow into the backend where they are first intercepted by an API key filter (ApiKeyFilter) ensuring security.
c. Controller Layer:
- ScoreController receives the requests, validates endpoints, and orchestrates call flows.
d. Service Layer:
- ScoreService (with its implementation ScoreServiceImpl) handles business logic such as processing and validating score data.
e. Repository Layer:
- ScoreRepository manages persistence and retrieval of scores, interacting with the database.
f. Configuration and Security Components:
- Config classes (SecurityConfig, ProdSecurityConfig, CorsConfig) which configure the overall behavior of the service.
- The ScoreSignatureValidator in the security package further validates score submissions.
g. Exception Handler:
- GlobalExceptionHandler ensures that errors are captured and returned in a user-friendly format.
h. Database Backend:
- A PostgreSQL database (or relational database) that is accessed via Spring Data JPA based on the datasource configurations in the properties files.

##### Architectural Patterns and Design Principles
- The design adheres to a layered architecture pattern – separating concerns into controllers, services, and repositories.
- The use of centralized exception handling (GlobalExceptionHandler) illustrates a cross-cutting concern handled in one component.
- Security is enforced via declarative configurations and filters (ApiKeyFilter, SecurityConfig) ensuring a stateless service model.
- Integration with the external database is clearly separated, permitting easy scalability and potential future extension.

##### Final Recommendations
- Use callouts or annotations to mention key technologies: Spring Boot, Spring Data JPA, PostgreSQL, and any security libraries.
- Avoid overcrowding; however, detail the major modules and how they interact, keeping in mind that every connection (like controller to service) is crucial for understanding the service flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Client["Browser Game"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        Filter["ApiKeyFilter"]:::api
        Controller["ScoreController"]:::api
        Exception["GlobalExceptionHandler"]:::exception
    end

    %% Service Layer
    subgraph "Service Layer"
        ServiceInterface["ScoreService"]:::service
        ServiceImpl["ScoreServiceImpl"]:::service
    end

    %% Repository and Database Layer
    subgraph "Data Layer"
        Repository["ScoreRepository"]:::repository
        Database["PostgreSQL Database"]:::db
    end

    %% Configuration & Security Components
    subgraph "Configuration & Security"
        SecConfig["SecurityConfig"]:::config
        ProdSecConfig["ProdSecurityConfig"]:::config
        CorsConfig["CorsConfig"]:::config
        ModelMapper["ModelMapperConfig"]:::config
        ScoreValidator["ScoreSignatureValidator"]:::security
    end

    %% Configuration Files
    subgraph "Configuration Files"
        ApplicationProp["application.properties"]:::configFiles
        ApplicationProdProp["application-prod.properties"]:::configFiles
    end

    %% Connections
    Client -->|"HTTP Request(x-api-key)"| Filter
    Filter -->|"validates request"| Controller
    Controller -->|"invokes business logic"| ServiceImpl
    ServiceImpl -->|"validates signature"| ScoreValidator
    ServiceImpl -->|"persists score"| Repository
    Repository -->|"reads/writes data"| Database
    Controller -->|"handles errors"| Exception

    %% Configuration relationships
    ApplicationProp -->|"configures"| SecConfig
    ApplicationProdProp -->|"configures"| ProdSecConfig
    SecConfig ---|"extended-by"| ProdSecConfig
    Filter ---|"configuredBy"| CorsConfig
    Controller ---|"maps data via"| ModelMapper

    %% Click Events
    click Filter "https://github.com/gallardos/multitask-backend/blob/main/src/main/java/com/multitask/backend/config/ApiKeyFilter.java"
    click Controller "https://github.com/gallardos/multitask-backend/blob/main/src/main/java/com/multitask/backend/controllers/ScoreController.java"
    click ServiceInterface "https://github.com/gallardos/multitask-backend/blob/main/src/main/java/com/multitask/backend/service/ScoreService.java"
    click ServiceImpl "https://github.com/gallardos/multitask-backend/blob/main/src/main/java/com/multitask/backend/service/impl/ScoreServiceImpl.java"
    click Repository "https://github.com/gallardos/multitask-backend/blob/main/src/main/java/com/multitask/backend/repository/ScoreRepository.java"
    click SecConfig "https://github.com/gallardos/multitask-backend/blob/main/src/main/java/com/multitask/backend/config/SecurityConfig.java"
    click ProdSecConfig "https://github.com/gallardos/multitask-backend/blob/main/src/main/java/com/multitask/backend/config/ProdSecurityConfig.java"
    click CorsConfig "https://github.com/gallardos/multitask-backend/blob/main/src/main/java/com/multitask/backend/config/CorsConfig.java"
    click ModelMapper "https://github.com/gallardos/multitask-backend/blob/main/src/main/java/com/multitask/backend/config/ModelMapperConfig.java"
    click ScoreValidator "https://github.com/gallardos/multitask-backend/blob/main/src/main/java/com/multitask/backend/security/ScoreSignatureValidator.java"
    click Exception "https://github.com/gallardos/multitask-backend/blob/main/src/main/java/com/multitask/backend/exception/GlobalExceptionHandler.java"
    click ApplicationProp "https://github.com/gallardos/multitask-backend/blob/main/src/main/resources/application.properties"
    click ApplicationProdProp "https://github.com/gallardos/multitask-backend/blob/main/src/main/resources/application-prod.properties"

    %% Styles
    classDef client fill:#ffe0b2,stroke:#FF9800,stroke-width:2px;
    classDef api fill:#bbdefb,stroke:#2196f3,stroke-width:2px;
    classDef service fill:#c8e6c9,stroke:#4caf50,stroke-width:2px;
    classDef repository fill:#ffccbc,stroke:#ff5722,stroke-width:2px;
    classDef db fill:#f0f4c3,stroke:#8bc34a,stroke-width:2px;
    classDef security fill:#e1bee7,stroke:#9c27b0,stroke-width:2px;
    classDef exception fill:#d7ccc8,stroke:#795548,stroke-width:2px;
    classDef config fill:#cfd8dc,stroke:#607d8b,stroke-width:2px;
    classDef configFiles fill:#e0f7fa,stroke:#00acc1,stroke-width:2px;
```
