Case Study - Football Team Api (Hexagonal Architecture)

📖 Information

• Football Team Management Service:
  • Implement a Spring Boot-based service through hexagonal architecture for managing football teams and their associated players, encompassing functionalities for team listing, player retrieval by team ID, and support for team and player updates or deletions
  • Functional Features:
    • List all football teams.
    • List players of a selected football team using the team’s ID.
    • Delete or update a football team using its ID.
    • Delete players from a football team or add a new player to the team.
  • Business Rules:
    • A football team can have a maximum of 18 players.
    • Only up to 6 players on a team can be foreigners.
    • A maximum of 2 goalkeepers can be defined per team.

Explore Rest APIs

Endpoints Summary

Method	Url	Description	Request Body	Path Variable	Response
POST	/api/v1/authentication/user/register	Register for Admin or User	RegisterRequest		CustomResponse<Void>
POST	/api/v1/authentication/user/login	Login for Admin or User	LoginRequest		CustomResponse<TokenResponse>
POST	/api/v1/authentication/user/refresh-token	Refresh Token for Admin or User	TokenRefreshRequest		CustomResponse<TokenResponse>
POST	/api/v1/authentication/user/logout	Logout for Admin or User	TokenInvalidateRequest		CustomResponse<Void>
POST	/api/v1/football-teams	Create a new football team	CreateFootballTeamRequest	-	CustomResponse<FootballTeamResponse>
PUT	/api/v1/football-teams/{teamId}	Update an existing football team's name	UpdateFootballTeamRequest	teamId (UUID)	CustomResponse<FootballTeamResponse>
GET	/api/v1/football-teams/{teamId}	Retrieve a football team's details by ID	-	teamId (UUID)	CustomResponse<FootballTeamResponse>
DELETE	/api/v1/football-teams/{teamId}	Delete a football team by ID	-	teamId (UUID)	CustomResponse<Void>
POST	/api/v1/football-teams/teamsList	Retrieve a paginated list of football teams	FootballTeamPagingRequest	-	CustomResponse<CustomPagingResponse<FootballTeamResponse>>
POST	/api/v1/football-teams/{teamId}/players	Add a new player to a team	AddPlayerRequest	teamId (UUID)	CustomResponse<PlayerResponse>
PUT	/api/v1/football-teams/{teamId}/players/{playerId}	Update an existing player on a team	UpdatePlayerRequest	teamId (UUID), playerId (UUID)	CustomResponse<PlayerResponse>
DELETE	/api/v1/football-teams/{teamId}/players/{playerId}	Delete a player from a team	-	teamId (UUID), playerId (UUID)	CustomResponse<Void>
GET	/api/v1/football-teams/{teamId}/players	Retrieve a paginated list of players for a team	PlayerPagingRequest	teamId (UUID)	CustomResponse<CustomPagingResponse<PlayerResponse>>

Technologies

---

• Java 21
• Spring Boot 3.0
• Restful API
• Open Api (Swagger)
• Maven
• Junit5
• Mockito
• Integration Tests
• TestContainers
• Docker
• Docker Compose
• CI/CD (Github Actions)
• Postman
• Prometheus
• Grafana
• Kubernetes
• JaCoCo (Test Report)
• Sonarqube
• Loki (Log Aggregation System)

Postman

Import postman collection under postman_collection folder

Prerequisites

Define Variable in .env file

FOOTBALL_TEAM_DB_IP=localhost
FOOTBALL_TEAM_DB_PORT=5432
POSTGRES_USER={POSTGRES_USER}
POSTGRES_PASSWORD={POSTGRES_PASSWORD}

Open Api (Swagger)

http://localhost:3112/swagger-ui/index.html

---

JaCoCo (Test Report)

After the command named mvn clean install completes, the JaCoCo report will be available at:

target/site/jacoco/index.html

Navigate to the target/site/jacoco/ directory.

Open the index.html file in your browser to view the detailed coverage report.

---

Maven, Docker and Kubernetes Running Process

Maven Run

To build and run the application with Maven, please follow the directions shown below;

$ cd footballteamapi
$ mvn clean install
$ mvn spring-boot:run

---

Docker Run

The application can be built and run by the Docker engine. The Dockerfile has multistage build, so you do not need to build and run separately.

Please follow directions shown below in order to build and run the application with Docker Compose file;

$ cd footballteamapi
$ docker-compose up -d

If you change anything in the project and run it on Docker, you can also use this command shown below

$ cd footballteamapi
$ docker-compose up --build

To monitor the application, you can use the following tools:

• Prometheus:
  Open in your browser at http://localhost:9090
  Prometheus collects and stores application metrics.

• Grafana:
  Open in your browser at http://localhost:3000
  Grafana provides a dashboard for visualizing the metrics.
  Default credentials:

  • Username: admin
  • Password: admin

• Define prometheus data source url, use this link shown below

http://prometheus:9090

• Define loki data source url, use this link shown below

http://loki:3100

---

Kubernetes Run

To build and run the application with Maven, please follow the directions shown below;

• Start Minikube

$ minikube start

• Open Minikube Dashboard

$ minikube dashboard

• To deploy the application on Kubernetes, apply the Kubernetes configuration file underneath k8s folder

$ kubectl apply -f k8s

• To open Prometheus, click tunnel url link provided by the command shown below to reach out Prometheus

minikube service prometheus-service

• To open Grafana, click tunnel url link provided by the command shown below to reach out Prometheus

minikube service grafana-service

• Define prometheus data source url, use this link shown below

http://prometheus-service.default.svc.cluster.local:9090

• Define loki data source url, use this link shown below

http://loki-service.default.svc.cluster.local:3100

---

Docker Image Location

https://hub.docker.com/repository/docker/noyandocker/footballteamapi/general

Define Loki through Grafana

• Define Loki Dashboard
• Define query after selecting data source as Loki
• Define Label Filter as app and its value footballteamapi
• Run the query
• Show the result in the Dashboard

Sonarqube

• Go to localhost:9000 for Docker and Go there through minikube service sonarqube for Kubernetes
• Enter username and password as admin
• Change password
• Click Create Local Project
• Choose the baseline for this code for the project as Use the global setting
• Click Locally in Analyze Method
• Define Token
• Click Continue
• Copy sonar.host.url and sonar.token (sonar.login) in the properties part in pom.xml
• Run mvn sonar:sonar to show code analysis

Screenshots

Click here to show the screenshots of project

Figure 1

Figure 2

Figure 3

Figure 4

Figure 5

Figure 6

Figure 7

Figure 8

Figure 9

Figure 10

Figure 11

Figure 12

Figure 13

Figure 14

Figure 15

Figure 16

Figure 17

Figure 18

Figure 19

Figure 20

Figure 21

Figure 22

Figure 23

Figure 24

Figure 25

Figure 26

Figure 27

Figure 28

Figure 29

Figure 30

Figure 31

Figure 32

Figure 33

Figure 34

Figure 35

Figure 36

Figure 37

Figure 38

Figure 39

Figure 40

Figure 41

Figure 42

Figure 43

Contributors

• Sercan Noyan Germiyanoğlu