# luissouza/flight-booking-clean-architecture architecture

> Architecture diagram of the GitHub repository luissouza/flight-booking-clean-architecture, 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/luissouza/flight-booking-clean-architecture
- Repository: https://github.com/luissouza/flight-booking-clean-architecture

## Overview

##### Project type and purpose
- This is a REST API project built with Java and Spring Boot following Clean Architecture principles.
- Its main purpose is to fetch and analyze flight data from external APIs, compute average flight and baggage prices, and then record these results – all while maintaining a clean separation of concerns (Entities, Application, Adapters). It integrates with external services (mock flight data, airport locations, airline APIs), a Postgres database, Elastic Search for logging, and uses caching.

##### File structure
- Clear layered structure:
- The “src/main/java/org/pt/flightbooking/entities” folder contains the core domain models and business entities.
- The “src/main/java/org/pt/flightbooking/application” layer holds DTOs, use cases, mappers, and business logic.
- The “src/main/java/org/pt/flightbooking/adapters” is rich in controllers, configuration, datasources (with separate packages for implementations and repositories), exception handling, logging, caching, and gateway interactions with external services.

##### README for additional insights
- It explains that the API groups flights by destination, calculates price averages, and persists history – pointing out that the business logic is organized into use cases within the application layer.
- It also mentions integrations with external APIs for flights and airports, as well as background persistence/logging in database and Elastic Search.

a. Main Components:
- Client / Consumer (users, Postman, Swagger UI)
- API Gateway / Presentation Layer – represented by the Controllers under adapters/controller.
- Application Layer – containing use cases (FlightUseCaseImpl, FlightsLogsUseCaseImpl), DTOs, and mappers.
- Domain Layer – with Entities and Models representing flights, baggage, and locations.
- Infrastructure / Adapter Layer – includes external communication elements:
- Data sources (FlightsDataSource, FlightsLogsDataSource) and repository implementations that interact with Elastic Search and Postgres.
- External Gateways/Clients (for external APIs such as Get Flights API and Airport Locations API; also the WebClient configuration and handlers).
- Exception handling, logging components, and caching components.
- Cross-cutting concerns – exception handling, caching, logging configuration, and API documentation (Swagger/OpenAPI).

b. Relationships and interactions:
- Application layer interacting with Domain entities and mapping resources into DTOs.
- Application layer calling into the Infrastructure/Adapter layer to fetch flight data from external APIs, log flight activities, and persist data.
- Interactions between the caching system (annotated in the code) and the data fetching operations; also highlight exception handling flowing upward to the Controllers.

c. Architectural patterns and design principles:
- Clean Architecture pattern with clear boundaries between:
- Entities (inner circle/domain) – independent of external frameworks,
- Application (use cases and business logic),
- Adapters / Infrastructure (controllers, gateways, repositories, configuration).
- Use of patterns such as Gateway Pattern (for external API integration), Repository Pattern (for JPA and Elastic Search access), and Mapping (DTOs converting external formats into domain models).
- Separation for logging, caching, and exception handling as aspects crossing multiple layers.

d. Relevant technologies, frameworks, and tools:
- Java JDK 20, Spring Boot, Maven for build,
- Docker (Dockerfile, docker-compose),
- Postgres for persistence,
- Elastic Search for indexing/logging,
- Cucumber & Junit for testing,
- Swagger/OpenAPI for API documentation,
- Lombok for reduced boilerplate.

##### Essential elements
- With technology names (e.g., “Spring Boot”, “Postgres”, “ElasticSearch”) next to the relevant components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client/Consumer (Postman,SwaggerUI)"]:::client

    subgraph "Presentation (Controllers)"
         FC["FlightsController (REST_API_Endpoints)"]:::presentation
    end

    subgraph "Application Layer (UseCases,DTOs,Mappers)"
         FUC["FlightUseCases (Business_Logic)"]:::application
    end

    subgraph "Domain (Entities & Models)"
         FM["FlightModel & Entities"]:::domain
    end

    subgraph "Infrastructure / Adapters"
         DS["Data Sources"]:::infrastructure
         REP["Repositories"]:::infrastructure
         EGC["External_API_Clients (Flights,Airports)"]:::infrastructure
         WC["WebClient_Configuration"]:::infrastructure
         GC["General_Configuration"]:::infrastructure
         IC["Infrastructure_Configuration"]:::infrastructure
    end

    subgraph "Cross-Cutting Concerns"
         EH["Exception_Handling"]:::cross
         LG["Logging"]:::cross
         CC["Caching_Configuration"]:::cross
    end

    Client -->|"HTTP_Request"| FC
    FC -->|"Executes"| FUC
    FUC -->|"Uses_Domain"| FM
    FUC -->|"Persists_to"| DS
    FUC -->|"Persists_to"| REP
    FUC -->|"Calls"| EGC
    EGC -.->|"Uses"| WC
    FUC -->|"Reads_Config"| GC
    FUC -->|"Reads_Config"| IC
    FC -.->|"Handles_Errors"| EH
    FUC -->|"Logs_Data"| LG
    FUC -->|"Caches_Data"| CC

    click FM "https://github.com/luissouza/flight-booking-clean-architecture/tree/main/src/main/java/org/pt/flightbooking/entities"
    click FUC "https://github.com/luissouza/flight-booking-clean-architecture/tree/main/src/main/java/org/pt/flightbooking/application"
    click FC "https://github.com/luissouza/flight-booking-clean-architecture/tree/main/src/main/java/org/pt/flightbooking/adapters/controller"
    click DS "https://github.com/luissouza/flight-booking-clean-architecture/tree/main/src/main/java/org/pt/flightbooking/adapters/datasources"
    click REP "https://github.com/luissouza/flight-booking-clean-architecture/tree/main/src/main/java/org/pt/flightbooking/adapters/datasources/repository"
    click EGC "https://github.com/luissouza/flight-booking-clean-architecture/tree/main/src/main/java/org/pt/flightbooking/adapters/gateway"
    click WC "https://github.com/luissouza/flight-booking-clean-architecture/tree/main/src/main/java/org/pt/flightbooking/adapters/infrastructure/webclient"
    click EH "https://github.com/luissouza/flight-booking-clean-architecture/tree/main/src/main/java/org/pt/flightbooking/adapters/exception"
    click LG "https://github.com/luissouza/flight-booking-clean-architecture/tree/main/src/main/java/org/pt/flightbooking/adapters/logger"
    click CC "https://github.com/luissouza/flight-booking-clean-architecture/tree/main/src/main/java/org/pt/flightbooking/adapters/infrastructure/cache"
    click GC "https://github.com/luissouza/flight-booking-clean-architecture/tree/main/src/main/java/org/pt/flightbooking/adapters/configuration"
    click IC "https://github.com/luissouza/flight-booking-clean-architecture/tree/main/src/main/java/org/pt/flightbooking/adapters/infrastructure/configuration"

    classDef client fill:#f9e79f,stroke:#d4ac0d,stroke-width:2px;
    classDef presentation fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef application fill:#d5f5e3,stroke:#28b463,stroke-width:2px;
    classDef domain fill:#fadbd8,stroke:#c0392b,stroke-width:2px;
    classDef infrastructure fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
    classDef cross fill:#f6ddcc,stroke:#cd6133,stroke-width:2px;
```
