# ptit-projects/football-stats-website architecture

> Architecture diagram of the GitHub repository ptit-projects/football-stats-website, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ptit-projects/football-stats-website
- Repository: https://github.com/ptit-projects/football-stats-website

## Overview

##### Project Type & Purpose
- This is a backend web application built with Java and Spring Boot. The project is part of a larger football statistics website ("football-stats-website") and likely serves as the API/server component for managing data about football clubs, leagues, players, matches, and user authentication.
- Since the repository includes Maven configuration (pom.xml, mvnw scripts) and a standardized Spring Boot structure, you’re looking at a well-organized full-stack backend, possibly connected with a frontend elsewhere.

##### Analyzing the File Structure
- Top-Level Directory: Aside from configuration files such as .gitignore and .devcontainer, the main work happens inside the “epl-web” folder.
- Build/Configuration: Maven wrapper files (“mvnw”, “pom.xml”), and a devcontainer configuration imply that containerization and consistent builds are part of the workflow.
- Source Layout (epl-web/src/main/java):
– The package “vn.ptit.project/epl_web” is the core Java package.
– Within it, directories are organized by function:
- config: Contains Spring configuration classes (e.g., CorsConfig, SecurityConfig, OpenAPIConfig) to set up cross-origin resource sharing, global exception handling, API documentation via OpenAPI/Swagger, and security definitions.
- controller: Contains the REST controllers (for instance, AuthController) that expose application endpoints.
- domain: Contains entity classes such as Club, League, Player, Match, etc., reflecting the football data domain.
- dto: Holds Data Transfer Objects for both requests and responses – for example, handling user registration data.
- repository: Contains Spring Data JPA repositories for database interactions.
- service: Contains business logic (e.g., UserService) separating the controller layer from the data access layer.
- util (and its subdirectories): Supports common functionality such as formatting REST responses and handling custom exceptions.
- Resources & Testing:
– “src/main/resources” holds configuration like application.properties and additional Spring metadata.
– “src/test” contains the tests to validate application behavior.
- Deployment/Infrastructure:
– “init.sql” indicates initial database setup, while “mysql.yml” may be a Docker Compose or Kubernetes config for setting up a MySQL service in a containerized environment.

##### Insights from the README File

a. Main Components to Include:
- Entry Point: “EplWebApplication.java” (Spring Boot Application Startup)
- Controllers: E.g., AuthController (handles incoming HTTP requests, such as user authentication)
- Service Layer: Contains services like UserService that encapsulate business logic.
- Data Access Layer: Repositories (e.g., UserRepository) that interface with the database.
- Domain Models: Entities such as Club, League, Player, etc.
- Configuration & Cross-Cutting Concerns: Config classes (SecurityConfig, CorsConfig, OpenAPIConfig) and Exception handling (GlobalException, InvalidRequestException).
- Utilities: DTO converters, response formatters, annotation-based API messages.
- External Infrastructure:
– Database: Represent MySQL (with an “init.sql” for initial setup) and possibly an external MySQL container (mysql.yml).
– Dev Container Setup: Indicate that the development environment is containerized (.devcontainer configuration).

b. Relationships & Interactions:
- Flow from Controller → Service → Repository → Database.
- That DTOs mediate data exchange between the client and the domain model.
- Exception handling by connecting utilities to both controller and service layers.

c. Key Architectural Patterns:
- Layered Architecture (Controller, Service, Repository)
- Dependency Injection (typical in Spring Boot)
- Separation of Concerns (distinct packages for configuration, business logic, domain, etc.)
- RESTful API design (controller to handle HTTP requests using DTOs)
- Containerized development (using devcontainer files) and externalized configuration for deployment.

d. Relevant Technologies & Frameworks:
- Java with Spring Boot framework.
- Maven as the build tool.
- Spring Security for authentication/authorization.
- OpenAPI for automated API documentation.
- Docker (implied by devcontainer and mysql.yml) for containerization of the development environment and database.
- JUnit (or similar) testing framework located in the “src/test” directory.

##### Instructing the Principal Software Engineer – What
– Application Entry Point (Spring Boot Application)
– Configurations (SecurityConfig, CorsConfig, OpenAPIConfig)
– Controller Layer (AuthController and any other potential REST endpoints)
– Service Layer (UserService and any business logic modules)
– Repository/Data Access Layer (UserRepository and other repositories)
– Domain Models (all entity classes like Club, League, Player, etc.)
– Utilities (for exception handling and REST response formatting)
– External Services (MySQL database and the Dev Container environment)
– Data flow from external calls to controllers, then to services, repositories, and back.
– Dependencies between configuration modules and the core application components.
– This helps in visually discriminating between the application core and the external systems.

##### Final Detailed Advice
- Every component of the layered architecture is represented and clearly labeled.
- Modular nature of the project – even if the current file tree shows one major module (epl-web), it lays out a classical multi-layered design.
- Do not hesitate to break down each major package into its components if clarity is needed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    EC["External Client"]:::extern

    %% Entry Point
    EP["EplWebApplication (Startup)"]:::entry

    %% Configuration
    CFG["Configuration (SecurityConfig, CorsConfig, OpenAPIConfig)"]:::config

    %% Controller Layer
    CTL["AuthController (REST Endpoints)"]:::controller

    %% Data Transfer Objects
    DTO["DTOs (Data Transfer Objects)"]:::domain

    %% Service Layer
    SRV["UserService (Business Logic)"]:::service

    %% Repository Layer
    REP["UserRepository (Data Access)"]:::repository

    %% Domain Models
    DOM["Domain Models (Club, League, Player, etc.)"]:::domain

    %% Utilities
    UTIL["Utilities (Exception & Response Handling)"]:::util

    %% External Infrastructure
    DB["Database (MySQL)"]:::extern
    DEV["Dev Environment (Container Settings)"]:::extern

    %% Data Flow
    EC -->|"HTTP_Request"| EP
    EP -->|"loads"| CFG
    EP -->|"initializes"| CTL
    CTL -->|"maps data via"| DTO
    CTL -->|"calls"| SRV
    SRV -->|"invokes"| REP
    REP -->|"queries"| DB
    SRV -->|"processes with"| DOM
    CTL -->|"handles errors with"| UTIL
    SRV -->|"handles exceptions with"| UTIL
    DEV -.->|"hosts"| EP

    %% Click Events
    click EP "https://github.com/ptit-projects/football-stats-website/blob/main/epl-web/src/main/java/vn/ptit/project/epl_web/EplWebApplication.java"
    click CTL "https://github.com/ptit-projects/football-stats-website/blob/main/epl-web/src/main/java/vn/ptit/project/epl_web/controller/AuthController.java"
    click SRV "https://github.com/ptit-projects/football-stats-website/blob/main/epl-web/src/main/java/vn/ptit/project/epl_web/service/UserService.java"
    click REP "https://github.com/ptit-projects/football-stats-website/blob/main/epl-web/src/main/java/vn/ptit/project/epl_web/repository/UserRepository.java"
    click DOM "https://github.com/ptit-projects/football-stats-website/tree/main/epl-web/src/main/java/vn/ptit/project/epl_web/domain"
    click DTO "https://github.com/ptit-projects/football-stats-website/tree/main/epl-web/src/main/java/vn/ptit/project/epl_web/dto"
    click CFG "https://github.com/ptit-projects/football-stats-website/tree/main/epl-web/src/main/java/vn/ptit/project/epl_web/config"
    click UTIL "https://github.com/ptit-projects/football-stats-website/tree/main/epl-web/src/main/java/vn/ptit/project/epl_web/util"
    click DB "https://github.com/ptit-projects/football-stats-website/blob/main/mysql.yml"
    click DEV "https://github.com/ptit-projects/football-stats-website/blob/main/.devcontainer"

    %% Styles
    classDef entry fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef controller fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef service fill:#ffeeba,stroke:#856404,stroke-width:2px;
    classDef repository fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef config fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef domain fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef util fill:#f5c6cb,stroke:#721c24,stroke-width:2px;
    classDef extern fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
