# mhfcodes/flight-booking-spring-boot architecture

> Architecture diagram of the GitHub repository mhfcodes/flight-booking-spring-boot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mhfcodes/flight-booking-spring-boot
- Repository: https://github.com/mhfcodes/flight-booking-spring-boot

## Overview

#### Purpose and Runtime
A Spring Boot REST backend for flight discovery, booking management, booking companions, and user profiles. It serves a static index page and exposes `/flightBooking/...` APIs. The application entry point is `src/main/java/com/hossein/FlightBooking/FlightBookingApplication.java`; static delivery begins at `src/main/resources/static/index.html`.

Core runtime stack is Spring Boot, Spring Data JPA/Hibernate persistence, Spring Security with JWT authentication, and ModelMapper. The README identifies a deployed Heroku instance; persistence database type is not established by the supplied files.

#### HTTP/API Boundary
Controllers are the inbound API layer, organized by business capability:
- Flights: `src/main/java/com/hossein/FlightBooking/controllers/flights/FlightsController.java`
- Bookings and companion operations: `src/main/java/com/hossein/FlightBooking/controllers/bookings/BookingsController.java`
- Authentication: `src/main/java/com/hossein/FlightBooking/controllers/infrastructure/login/LoginController.java`, `src/main/java/com/hossein/FlightBooking/controllers/infrastructure/signup/SignupController.java`
- Profiles and landing page: `src/main/java/com/hossein/FlightBooking/controllers/userDetails/UserDetailsController.java`, `src/main/java/com/hossein/FlightBooking/controllers/home/HomeController.java`

Requests and responses use DTOs plus response-oriented view models rather than exposing entities directly.

#### Identity, Authentication, and Authorization
Signup persists users; login authenticates credentials and returns a JWT. Subsequent requests pass through the JWT filter and Spring Security configuration before reaching protected controllers. Roles distinguish admin-only flight administration and cross-user user/booking visibility from normal user operations.
- `src/main/java/com/hossein/FlightBooking/security/config/SecurityConfiguration.java`
- `src/main/java/com/hossein/FlightBooking/security/jwt/JwtRequestFilter.java`
- `src/main/java/com/hossein/FlightBooking/security/jwt/JwtTokenUtil.java`
- `src/main/java/com/hossein/FlightBooking/services/impl/infrastructure/FlightBookingUserDetailsService.java`

#### Flight Catalog Stage
Flight APIs list/filter available flights, load individual flights, and permit admins to save or delete catalog records. The controller delegates business handling to the flights service, which accesses both standard and custom repository query paths.
- `src/main/java/com/hossein/FlightBooking/controllers/flights/FlightsController.java`
- `src/main/java/com/hossein/FlightBooking/services/impl/flights/FlightsService.java`
- `src/main/java/com/hossein/FlightBooking/dao/repositories/impl/flights/FlightsCustomRepoImpl.java`
- `src/main/java/com/hossein/FlightBooking/models/flights/Flights.java`

#### Booking and Companion Stage
Bookings are user-owned records associated with flights; users operate on their own bookings while admins can access all bookings. Companions are nested beneath a booking and support individual or bulk save/delete operations. Ownership and role checks are an important service/repository boundary for these operations.
- `src/main/java/com/hossein/FlightBooking/controllers/bookings/BookingsController.java`
- `src/main/java/com/hossein/FlightBooking/services/impl/bookings/BookingsService.java`
- `src/main/java/com/hossein/FlightBooking/dao/repositories/impl/bookings/BookingsCustomRepoImpl.java`
- `src/main/java/com/hossein/FlightBooking/dao/repositories/impl/companions/CompanionsCustomRepoImpl.java`

#### User and Profile Stage
Infrastructure user records and role records support authentication. A separate user-details domain stores editable personal information; users load/save their own data, while admins can retrieve a grid of all user details.
- `src/main/java/com/hossein/FlightBooking/services/impl/infrastructure/UserService.java`
- `src/main/java/com/hossein/FlightBooking/services/impl/userDetails/UserDetailsService.java`
- `src/main/java/com/hossein/FlightBooking/models/infrastructure/UserModel.java`
- `src/main/java/com/hossein/FlightBooking/models/userDetails/UserDetailsModel.java`

#### Persistence, Mapping, and Errors
JPA entities flow through repositories and services. Custom repositories likely implement filtered grid/list retrieval; `GenericRepository` provides shared repository configuration. ModelMapper adapters enforce DTO-to-entity and entity-to-view-model boundaries. Controller advice translates application failures into API error responses.
- `src/main/java/com/hossein/FlightBooking/dao/config/GenericRepository.java`
- `src/main/java/com/hossein/FlightBooking/modelMapper/config/ModelMapperBean.java`
- `src/main/java/com/hossein/FlightBooking/modelMapper/maps/bookings/DBookingsMapper.java`
- `src/main/java/com/hossein/FlightBooking/exceptions/CustomControllerAdvice.java`

Main entry points: [`src/main/java/com/hossein/FlightBooking/models/flights/Flights.java`](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/models/flights/Flights.java) (JPA domain entities), [`src/main/java/com/hossein/FlightBooking/services/impl/bookings/BookingsService.java`](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/services/impl/bookings/BookingsService.java) (Bookings service), [`src/main/java/com/hossein/FlightBooking/FlightBookingApplication.java`](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/FlightBookingApplication.java) (Spring Boot app), [`src/main/java/com/hossein/FlightBooking/security/jwt/JwtRequestFilter.java`](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/security/jwt/JwtRequestFilter.java) (JWT request filter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web/API"]
  node_static["Static landing page<br/>static UI<br/>[index.html]"]
  node_home["Home controller"]
  node_flight_api["Flights controller"]
  node_booking_api["Bookings controller"]
  node_auth_api["Login &amp; signup controllers"]
  node_profile_api["User details controller"]
  node_error_handler["Controller advice<br/>error handling"]
end

subgraph group_security["Security"]
  node_security_config["Security configuration"]
  node_jwt_filter["JWT request filter<br/>security filter"]
  node_jwt_util["JWT token utility<br/>token service<br/>[JwtTokenUtil.java]"]
  node_user_details_auth["User details auth service<br/>security service"]
end

subgraph group_domain["Domain services"]
  node_flights_service["Flights service"]
  node_bookings_service["Bookings service"]
  node_user_service["User service<br/>[UserService.java]"]
  node_profile_service["User details service"]
  node_mapping["DTO/view mapping<br/>ModelMapper"]
end

subgraph group_persistence["Persistence"]
  node_flight_repo["Flights custom repository"]
  node_booking_repo["Bookings custom repository"]
  node_companion_repo["Companions custom repository"]
  node_entities[("JPA domain entities<br/>JPA entities<br/>[Flights.java]")]
end

node_app{{"Spring Boot app"}}

node_app -->|"serves"| node_static
node_app -->|"configures"| node_security_config
node_app -->|"uses"| node_error_handler
node_security_config -->|"installs"| node_jwt_filter
node_jwt_filter -->|"validates token with"| node_jwt_util
node_jwt_filter -->|"loads principal via"| node_user_details_auth
node_auth_api -->|"issues JWT"| node_jwt_util
node_auth_api -->|"registers/authenticates"| node_user_service
node_flight_api -->|"delegates"| node_flights_service
node_booking_api -->|"delegates"| node_bookings_service
node_profile_api -->|"delegates"| node_profile_service
node_flights_service -->|"queries and writes"| node_flight_repo
node_bookings_service -->|"queries and writes"| node_booking_repo
node_bookings_service -->|"manages companions"| node_companion_repo
node_user_service -->|"persists users and roles"| node_entities
node_profile_service -->|"persists profile details"| node_entities
node_flight_repo -->|"persists flights"| node_entities
node_booking_repo -->|"persists bookings"| node_entities
node_companion_repo -->|"persists companions"| node_entities
node_flights_service -->|"maps DTOs/views"| node_mapping
node_bookings_service -->|"maps DTOs/views"| node_mapping
node_profile_service -->|"maps DTOs/views"| node_mapping

click node_app "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/FlightBookingApplication.java"
click node_static "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/resources/static/index.html"
click node_home "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/controllers/home/HomeController.java"
click node_flight_api "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/controllers/flights/FlightsController.java"
click node_booking_api "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/controllers/bookings/BookingsController.java"
click node_auth_api "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/controllers/infrastructure/login/LoginController.java"
click node_profile_api "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/controllers/userDetails/UserDetailsController.java"
click node_security_config "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/security/config/SecurityConfiguration.java"
click node_jwt_filter "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/security/jwt/JwtRequestFilter.java"
click node_jwt_util "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/security/jwt/JwtTokenUtil.java"
click node_user_details_auth "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/services/impl/infrastructure/FlightBookingUserDetailsService.java"
click node_flights_service "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/services/impl/flights/FlightsService.java"
click node_bookings_service "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/services/impl/bookings/BookingsService.java"
click node_user_service "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/services/impl/infrastructure/UserService.java"
click node_profile_service "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/services/impl/userDetails/UserDetailsService.java"
click node_mapping "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/modelMapper/config/ModelMapperBean.java"
click node_flight_repo "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/dao/repositories/impl/flights/FlightsCustomRepoImpl.java"
click node_booking_repo "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/dao/repositories/impl/bookings/BookingsCustomRepoImpl.java"
click node_companion_repo "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/dao/repositories/impl/companions/CompanionsCustomRepoImpl.java"
click node_entities "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/models/flights/Flights.java"
click node_error_handler "https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/exceptions/CustomControllerAdvice.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_static,node_home,node_flight_api,node_booking_api,node_auth_api,node_profile_api,node_error_handler toneBlue
class node_security_config,node_jwt_filter,node_jwt_util,node_user_details_auth toneAmber
class node_flights_service,node_bookings_service,node_user_service,node_profile_service,node_mapping toneMint
class node_flight_repo,node_booking_repo,node_companion_repo,node_entities toneRose
class node_app toneNeutral
```

## Components

### Web/API

- [Static landing page](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/resources/static/index.html): static UI · `src/main/resources/static/index.html`
- [Home controller](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/controllers/home/HomeController.java): controller · `src/main/java/com/hossein/FlightBooking/controllers/home/HomeController.java`
- [Flights controller](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/controllers/flights/FlightsController.java): controller · Flight discovery and admin catalog APIs. · `src/main/java/com/hossein/FlightBooking/controllers/flights/FlightsController.java`
- [Bookings controller](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/controllers/bookings/BookingsController.java): controller · Booking and nested companion APIs. · `src/main/java/com/hossein/FlightBooking/controllers/bookings/BookingsController.java`
- [Login & signup controllers](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/controllers/infrastructure/login/LoginController.java): controller · Credential authentication and user registration endpoints. · `src/main/java/com/hossein/FlightBooking/controllers/infrastructure/login/LoginController.java`
- [User details controller](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/controllers/userDetails/UserDetailsController.java): controller · `src/main/java/com/hossein/FlightBooking/controllers/userDetails/UserDetailsController.java`
- [Controller advice](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/exceptions/CustomControllerAdvice.java): error handling · Converts application failures to API errors. · `src/main/java/com/hossein/FlightBooking/exceptions/CustomControllerAdvice.java`

### Security

- [Security configuration](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/security/config/SecurityConfiguration.java): security config · Defines protected routes and role authorization. · `src/main/java/com/hossein/FlightBooking/security/config/SecurityConfiguration.java`
- [JWT request filter](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/security/jwt/JwtRequestFilter.java): security filter · `src/main/java/com/hossein/FlightBooking/security/jwt/JwtRequestFilter.java`
- [JWT token utility](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/security/jwt/JwtTokenUtil.java): token service · `src/main/java/com/hossein/FlightBooking/security/jwt/JwtTokenUtil.java`
- [User details auth service](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/services/impl/infrastructure/FlightBookingUserDetailsService.java): security service · Loads authenticated users and roles. · `src/main/java/com/hossein/FlightBooking/services/impl/infrastructure/FlightBookingUserDetailsService.java`

### Domain services

- [Flights service](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/services/impl/flights/FlightsService.java): service · `src/main/java/com/hossein/FlightBooking/services/impl/flights/FlightsService.java`
- [Bookings service](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/services/impl/bookings/BookingsService.java): service · Enforces booking ownership and companion operations. · `src/main/java/com/hossein/FlightBooking/services/impl/bookings/BookingsService.java`
- [User service](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/services/impl/infrastructure/UserService.java): service · `src/main/java/com/hossein/FlightBooking/services/impl/infrastructure/UserService.java`
- [User details service](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/services/impl/userDetails/UserDetailsService.java): service · Own-profile updates and admin user-details grid. · `src/main/java/com/hossein/FlightBooking/services/impl/userDetails/UserDetailsService.java`
- [DTO/view mapping](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/modelMapper/config/ModelMapperBean.java): ModelMapper · Maps API DTOs, entities, and response views. · `src/main/java/com/hossein/FlightBooking/modelMapper/config/ModelMapperBean.java`

### Persistence

- [Flights custom repository](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/dao/repositories/impl/flights/FlightsCustomRepoImpl.java): repository · Filtered flight retrieval and catalog persistence. · `src/main/java/com/hossein/FlightBooking/dao/repositories/impl/flights/FlightsCustomRepoImpl.java`
- [Bookings custom repository](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/dao/repositories/impl/bookings/BookingsCustomRepoImpl.java): repository · Ownership-aware booking queries. · `src/main/java/com/hossein/FlightBooking/dao/repositories/impl/bookings/BookingsCustomRepoImpl.java`
- [Companions custom repository](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/dao/repositories/impl/companions/CompanionsCustomRepoImpl.java): repository · Nested companion persistence operations. · `src/main/java/com/hossein/FlightBooking/dao/repositories/impl/companions/CompanionsCustomRepoImpl.java`
- [JPA domain entities](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/models/flights/Flights.java): JPA entities · Flights, bookings, users, roles, and user details. · `src/main/java/com/hossein/FlightBooking/models/flights/Flights.java`

### Other components

- [Spring Boot app](https://github.com/mhfcodes/flight-booking-spring-boot/blob/master/src/main/java/com/hossein/FlightBooking/FlightBookingApplication.java): application · Bootstraps the REST backend. · `src/main/java/com/hossein/FlightBooking/FlightBookingApplication.java`

## Connections

- Spring Boot app → Static landing page: serves
- Spring Boot app → Security configuration: configures
- Spring Boot app → Controller advice: uses
- Security configuration → JWT request filter: installs
- JWT request filter → JWT token utility: validates token with
- JWT request filter → User details auth service: loads principal via
- Login & signup controllers → JWT token utility: issues JWT
- Login & signup controllers → User service: registers/authenticates
- Flights controller → Flights service: delegates
- Bookings controller → Bookings service: delegates
- User details controller → User details service: delegates
- Flights service → Flights custom repository: queries and writes
- Bookings service → Bookings custom repository: queries and writes
- Bookings service → Companions custom repository: manages companions
- User service → JPA domain entities: persists users and roles
- User details service → JPA domain entities: persists profile details
- Flights custom repository → JPA domain entities: persists flights
- Bookings custom repository → JPA domain entities: persists bookings
- Companions custom repository → JPA domain entities: persists companions
- Flights service → DTO/view mapping: maps DTOs/views
- Bookings service → DTO/view mapping: maps DTOs/views
- User details service → DTO/view mapping: maps DTOs/views