# osanyem/formula-one-api architecture

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

- Interactive diagram: https://gitdiagram.com/osanyem/formula-one-api
- Repository: https://github.com/osanyem/formula-one-api

## Overview

##### Project Type & Purpose
- This is a full-stack API back-end project where the “frontend” is essentially the API consumer (e.g., Swagger UI or any client).
- Its core purpose is to serve Formula 1 data using RESTful endpoints with strong separation of concerns (Controller, Service, Repository layers) and integration with a MySQL database.

##### File Structure
- Top-Level Components:
- The root includes Maven configuration files (pom.xml, mvnw, etc.) and Docker Compose for containerizing services (e.g., MySQL).
- The src directory is split between main (application logic) and test (unit/integration tests).
- Within src/main/java/com/osanyemo/f1_api:
- The "controller" directory hosts the REST endpoints.
- The "service" package contains the business logic.
- The "repository" package implements the data access layer.
- The "entity" package defines the JPA entities that map to the database tables.
- The "exception" package provides custom exception handling (including a global exception handler).
- The resources directory contains configuration files (application.properties) and a sample SQL script (data.sql).

##### Examining the README for Architectural Insights
- The README clarifies that the API relies on Spring Boot, uses SpringDoc OpenAPI for documentation, and is backed by MySQL.
- It describes endpoints for drivers, teams, and races, indicating a clear separation and modularity within the API’s controllers.
- Specific instructions for starting the database (using either MySQL directly or Docker) and building the project are provided, reinforcing the external dependency on MySQL.

a. Main Components to Include:
- Client / API Consumer (could be Swagger UI, Postman, or any HTTP client)
- REST Controllers (DriverController, TeamController, RaceController)
- Service Layer (DriverService, RaceService, TeamService)
- Data Access Layer (repositories like DriverRepository, RaceRepository, etc.)
- JPA Entities (Driver, Team, Race, etc.)
- Exception Handling Module (GlobalExceptionHandler and associated exceptions)
- Database (MySQL)
- Configuration components (application.properties, OpenAPI configuration through SpringDoc)

b. Relationships & Interactions:
- The client sends HTTP requests that are received by the REST Controllers.
- Controllers call the Service layer for business logic.
- The Service layer interacts with the Repository layer for performing database operations.
- The Repository layer uses JPA entities to map and persist data in the MySQL database.
- Exception Handling intercepts and manages errors across these layers.
- Documentation is auto-populated via SpringDoc (which connects to the REST Controllers).

c. Key Architectural Patterns:
- Layered Architecture (Controller → Service → Repository)
- Separation of Concerns, ensuring that each package has a distinct responsibility.
- Use of Spring Boot’s Dependency Injection for managing component dependencies.
- Use of global exception handling to catch and handle errors across the API.

d. Relevant Technologies & Libraries:
- Java (JDK 17)
- Spring Boot 3.2.x (for building the web application)
- Maven (for build and dependency management)
- MySQL (database)
- SpringDoc OpenAPI / Swagger (for API documentation)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Client("API Consumer (Swagger/Postman)"):::client
    end

    %% Controller Layer
    subgraph "Controller Layer"
        CT("DriverController\nRaceController\nTeamController"):::controllers
    end

    %% Service Layer
    subgraph "Service Layer"
        SV("DriverService\nRaceService\nTeamService"):::services
    end

    %% Repository Layer
    subgraph "Repository Layer"
        RP("DriverRepository\nRaceRepository\nTeamRepository\nCircuitRepository\nRaceResultRepository\nSeasonRepository"):::repository
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        ENT("Driver\nTeam\nRace\nCircuit\nRaceResult\nSeason"):::entities
        DB("MySQL Database"):::database
    end

    %% Support Modules
    subgraph "Support Modules"
        EX("GlobalExceptionHandler\nErrorResponse\nResourceNotFoundException"):::exception
        OA("OpenAPI Config"):::config
        AC("Application Config"):::config
    end

    %% Connections - Vertical Flow
    Client -->|"HTTP_request"| CT
    CT -->|"Calls_service"| SV
    SV -->|"Queries_repository"| RP
    RP -->|"Persists_data"| DB
    RP -->|"Maps_to"| ENT

    %% Exception Handling connections
    CT -->|"Handles_exceptions"| EX
    SV -->|"Handles_exceptions"| EX

    %% Documentation connection from controllers to OpenAPI configuration
    CT -->|"Auto_docs"| OA

    %% Styles
    class Client client
    class CT controllers
    class SV services
    class RP repository
    class ENT entities
    class DB database
    class EX exception
    class OA,AC config

    %% Click Events
    click CT "https://github.com/osanyem/formula-one-api/tree/main/src/main/java/com/osanyemo/f1_api/controller"
    click SV "https://github.com/osanyem/formula-one-api/tree/main/src/main/java/com/osanyemo/f1_api/service"
    click RP "https://github.com/osanyem/formula-one-api/tree/main/src/main/java/com/osanyemo/f1_api/repository"
    click ENT "https://github.com/osanyem/formula-one-api/tree/main/src/main/java/com/osanyemo/f1_api/entity"
    click EX "https://github.com/osanyem/formula-one-api/tree/main/src/main/java/com/osanyemo/f1_api/exception"
    click OA "https://github.com/osanyem/formula-one-api/blob/main/src/main/java/com/osanyemo/f1_api/OpenApiConfig.java"
    click AC "https://github.com/osanyem/formula-one-api/blob/main/src/main/resources/application.properties"
    click DB "https://github.com/osanyem/formula-one-api/blob/main/docker-compose.yml"

    %% Class Definitions for colors
    classDef client fill:#f9e79f,stroke:#333,stroke-width:2px
    classDef controllers fill:#aed6f1,stroke:#333,stroke-width:2px
    classDef services fill:#a9dfbf,stroke:#333,stroke-width:2px
    classDef repository fill:#f9e79f,stroke:#333,stroke-width:2px
    classDef entities fill:#f5b7b1,stroke:#333,stroke-width:2px
    classDef database fill:#d5f5e3,stroke:#333,stroke-width:2px
    classDef exception fill:#f6ddcc,stroke:#333,stroke-width:2px
    classDef config fill:#e8daef,stroke:#333,stroke-width:2px
```
