# zakariaalla/nice-equipe-football-api architecture

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

- Interactive diagram: https://gitdiagram.com/zakariaalla/nice-equipe-football-api
- Repository: https://github.com/zakariaalla/nice-equipe-football-api

## Overview

##### Project type and purpose
- This is a monolithic RESTful backend service (“Nice Equipe Football API”) built with Spring Boot.
- Purpose: expose endpoints to manage football teams (“équipes”), players, positions, and user authentication/authorization via JWT.

##### File structure
- Top-level artifacts:
- Dockerfile + docker-compose.yml – containerize the API + PostgreSQL.
- pom.xml – Maven build, Spring Boot dependencies (Web, Data JPA, Security, Validation, Test).
- src/main/java/com/francefootball/niceequipefootballapi:
- config (SwaggerConfig, security, AOP logging, DB initializer)
- controller (AuthenticationController, EquipeController, JoueurController, PositionController + exception handlers)
- metier (DTOs, enums, exceptions, service interfaces + implementations including AuthenticationService, EquipeService, JoueurService, JwtService)
- persistence (JPA entities, repositories)
- src/main/resources/config: profile-specific YAML files for dev/qualif/prod.
- src/test: unit and integration tests per layer.

##### README
- Tech stack: Java 21, Spring Boot 3.4.4, Spring Data JPA, Spring Security + JWT, Springdoc OpenAPI, PostgreSQL, H2 (tests), Lombok.
- Run modes: Docker Compose brings up API + Postgres; local via Maven with Spring profiles.
- Two public endpoints (GET équipes, GET positions); all others secured by JWT.
- Swagger UI at `/nice-foot-api/swagger-ui/index.html`, Postman collection included.

##### Main components
a. Clients
– HTTP clients (Postman, other front-ends)
– Swagger UI (web MVC UI served by Springdoc)
b. API Service (Spring Boot application)
– Security Layer: SecurityConfiguration, JwtAuthenticationFilter
– Logging Aspect: RequestResponseLoggingAspect
– API Layer: Controllers
– Business Layer: Service interfaces + implementations
– Data Layer: Spring Data JPA Repositories + Entities
– Config & Initialization: SwaggerConfig, DataInitializer, profile YAMLs
c. Database
– PostgreSQL container (jdbc:postgresql://…)
d. Infrastructure
– Docker Compose orchestrating API + DB
– Maven Wrapper for build
e. External systems
– (Optional) LDAP/OAuth if added later, monitoring, logging sinks

##### Relationships and data flow
1. Client → HTTP request → Spring Security filter chain (JwtAuthenticationFilter validates token)
2. Filter passes to Controller
3. Controller calls Service (business logic, validation via annotations)
4. Service calls Repository → Database (via JPA)
5. DataInitializer seeds DB at startup
6. Controller returns HTTP response → Client
7. Swagger UI endpoints served from the same app

##### Architectural patterns and principles
- Layered architecture (Web → Service → Repository)
- AOP for cross-cutting logging concerns
- Configuration by profiles (dev/qualif/prod)
- JWT stateless authentication
- DTOs to decouple API from persistence models
- Exception handlers for uniform error responses

##### Technologies & frameworks in context
- Spring Boot starters: Web (embedded Tomcat), Data JPA, Security, Validation, Test
- Springdoc OpenAPI for interactive docs
- jjwt for JWT token generation/validation
- Lombok to reduce boilerplate
- PostgreSQL in Docker, H2 in test scope

- Clearly labeled components and layers
- Call out environment/config profiles and initialization behavior

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients" 
        direction TB
        HTTPClient["HTTP Clients (Postman, Front-ends)"]:::client
        SwaggerUI["Swagger UI"]:::client
    end

    %% Infrastructure
    subgraph "Infrastructure (Docker Compose)" 
        direction TB
        DockerCompose["Docker Compose"]:::infra
        subgraph "Containers"
            direction TB
            APIContainer["nice-foot-api (Spring Boot API)"]:::app
            PostgresContainer["PostgreSQL"]:::db
        end
    end

    %% Database
    PostgresContainer -->|"JDBC (jdbc:postgresql://) "| Database["PostgreSQL Database"]:::db

    %% Application Layers
    subgraph "nice-foot-api" 
        direction TB
        %% Security & Config
        subgraph "Security & Configuration" 
            direction TB
            SecurityConfig["SecurityConfiguration"]:::aspect
            JwtFilter["JwtAuthenticationFilter"]:::aspect
            AppConfig["ApplicationConfiguration"]:::aspect
            SwaggerConfig["SwaggerConfig"]:::app
            DataInit["DataInitializer"]:::app
        end

        %% Logging Aspect
        LoggingAspect["RequestResponseLoggingAspect"]:::aspect

        %% API Layer
        subgraph "Controllers" 
            direction TB
            AuthController["AuthenticationController"]:::app
            EquipeController["EquipeController"]:::app
            JoueurController["JoueurController"]:::app
            PositionController["PositionController"]:::app
            ApiExceptionHandler["ApiExceptionHandler"]:::app
        end

        %% Business Layer
        subgraph "Services & DTOs" 
            direction TB
            EquipeServiceIface["EquipeService (interface)"]:::app
            JoueurServiceIface["JoueurService (interface)"]:::app
            AuthService["AuthenticationService"]:::app
            EquipeServiceImpl["EquipeServiceImpl"]:::app
            JoueurServiceImpl["JoueurServiceImpl"]:::app
            JwtService["JwtService"]:::app
            DTOs["DTOs"]:::app
        end

        %% Data Layer
        subgraph "Repositories & Entities" 
            direction TB
            EquipeRepo["EquipeRepository"]:::app
            JoueurRepo["JoueurRepository"]:::app
            RoleRepo["RoleRepository"]:::app
            UserRepo["UserRepository"]:::app
            Entities["JPA Entities"]:::app
        end
    end

    %% Build & Launcher
    Maven["Maven Wrapper & pom.xml"]:::infra
    AppLauncher["NiceEquipeFootballApiApplication"]:::infra

    %% Requests Flow
    HTTPClient -->|"HTTP Request"| JwtFilter
    SwaggerUI -->|"HTTP Request to /swagger-ui"| SecurityConfig
    JwtFilter -->|Validates JWT| SecurityConfig
    SecurityConfig -->|Filter Chain| AuthController
    AuthController -->|"Calls Service"| AuthService
    EquipeController -->|"Calls Service"| EquipeServiceIface
    JoueurController -->|"Calls Service"| JoueurServiceIface
    PositionController -->|"Calls Service"| JwtService
    ApiExceptionHandler --- Controllers

    %% Business to Data
    AuthService -->|"Business Logic"| JwtService
    EquipeServiceImpl -->|"Business Logic"| EquipeRepo
    JoueurServiceImpl -->|"Business Logic"| JoueurRepo
    JwtService -->|"Generates/Validates JWT"| UserRepo
    RepositoriesDB["Database Access"]:::db
    EquipeRepo -->|CRUD| RepositoriesDB
    JoueurRepo -->|CRUD| RepositoriesDB
    RoleRepo -->|CRUD| RepositoriesDB
    UserRepo -->|CRUD| RepositoriesDB

    %% Initialization
    DataInit -->|Seeds Data| RepositoriesDB

    %% App startup
    Maven -->|Builds| APIContainer
    DockerCompose -->|Orchestrates| APIContainer
    DockerCompose -->|Orchestrates| PostgresContainer
    AppLauncher -->|Starts App| Server["Embedded Tomcat"]:::app

    %% Responses
    Controllers -->|"HTTP Response"| HTTPClient

    %% Click Events
    click DockerCompose "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/docker-compose.yml"
    click Dockerfile "https://github.com/zakariaalla/nice-equipe-football-api/tree/develop/Dockerfile"
    click SwaggerConfig "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/config/SwaggerConfig.java"
    click HTTPClient "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/nice-football-collection.postman_collection.json"
    click JwtFilter "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/config/security/JwtAuthenticationFilter.java"
    click SecurityConfig "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/config/security/SecurityConfiguration.java"
    click AppConfig "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/config/security/ApplicationConfiguration.java"
    click LoggingAspect "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/config/aspect/RequestResponseLoggingAspect.java"
    click DataInit "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/config/db/DataInitializer.java"
    click AuthController "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/controller/AuthenticationController.java"
    click EquipeController "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/controller/EquipeController.java"
    click JoueurController "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/controller/JoueurController.java"
    click PositionController "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/controller/PositionController.java"
    click ApiExceptionHandler "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/controller/apihandler/ApiExceptionHandler.java"
    click EquipeServiceIface "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/metier/service/interfaces/EquipeService.java"
    click JoueurServiceIface "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/metier/service/interfaces/JoueurService.java"
    click AuthService "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/metier/service/impl/AuthenticationService.java"
    click EquipeServiceImpl "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/metier/service/impl/EquipeServiceImpl.java"
    click JoueurServiceImpl "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/metier/service/impl/JoueurServiceImpl.java"
    click JwtService "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/metier/service/impl/JwtService.java"
    click Entities "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/persistence/model/Equipe.java"
    click EquipeRepo "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/persistence/repository/EquipeRepository.java"
    click JoueurRepo "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/persistence/repository/JoueurRepository.java"
    click RoleRepo "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/persistence/repository/RoleRepository.java"
    click UserRepo "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/persistence/repository/UserRepository.java"
    click Maven "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/pom.xml"
    click AppLauncher "https://github.com/zakariaalla/nice-equipe-football-api/blob/develop/src/main/java/com/francefootball/niceequipefootballapi/NiceEquipeFootballApiApplication.java"

    %% Styles
    classDef client fill:#b7e4c7,stroke:#2b9348
    classDef app fill:#ade8f4,stroke:#1d3557
    classDef aspect fill:#ffb703,stroke:#d00000
    classDef db fill:#adb5bd,stroke:#495057
    classDef infra fill:#dee2e6,stroke:#6c757d
```
