OnTheGoRentals Part 1: Architecture & Domain Design — Building a Production-Ready Rental SaaS

Why We Built This

OnTheGoRentals started as an exploration of how far you can push a Spring Boot monolith before needing to split into microservices. We wanted to build a realistic domain — car rental has temporal availability, complex state machines, and concurrent access patterns — while creating something genuinely useful.

The result is a production-deployed platform that’s live and functional. It’s also a reusable template: the booking engine, authentication system, and admin dashboard can be adapted for bicycles, houses, tools, or any rentable asset with minimal changes. The car data you see in the screenshots is placeholder content, but the infrastructure is production-grade.

What makes this project interesting from an architecture standpoint is that it forced us to confront problems that simpler CRUD applications never surface: temporal overlap detection, immutable state transitions, dual-token JWT security, and a full observability stack baked into Docker from day one.

The Domain Model: Immutable Entities and Builder Patterns

The foundation of OnTheGoRentals is a carefully designed domain model where entities are immutable once created. Every Booking, Car, and User is built using the Builder pattern, ensuring that once an object enters the system, it cannot be accidentally mutated. This design choice forced us to think deeply about state transitions from the very beginning.

The Booking Entity

The Booking entity is the heart of the system. It tracks who rented what, when, and in what state the reservation currently sits:

The @Builder(toBuilder = true) annotation is critical. It allows us to create new instances from existing ones without mutation — essential for status transitions. When a booking moves from PENDING to CONFIRMED, we don’t modify the existing object; we build a new one with the updated status.

Notice the deleted field. We use soft deletes throughout the system. Instead of physically removing rows from the database, we set deleted = true and filter queries with WHERE deleted = false. This preserves audit trails and makes data recovery trivial.

The Car Entity: More Than Fields

The Car entity is more complex than Booking because it manages a collection of images through JPA’s @OneToMany relationship:

The tricky part here is the orphanRemoval = true setting. When we update a car’s images, we can’t just replace the list — JPA would throw a “collection was no longer referenced” error. Instead, the Builder’s applyTo() method clears the managed list and re-populates it:

This pattern — clear then add-all — is the standard way to handle orphanRemoval collections in JPA without triggering the reference error. It’s one of those things that seems simple but causes hours of debugging if you get it wrong.

The User Entity: Spring Security Integration

The User entity implements Spring Security’s UserDetails interface, which means it directly integrates with the authentication framework:

The key design decision here is the authProvider field. Users can register via email/password (LOCAL) or through Google OAuth2 (GOOGLE). The googleId field links the OAuth2 identity to the local user record. When a Google user first logs in, the GoogleOAuth2UserService creates a new User entity with authProvider = GOOGLE and stores the Google subject ID.

The roles relationship uses FetchType.EAGER because roles are needed on every authenticated request for authorization checks. The @ManyToMany(cascade = CascadeType.MERGE) ensures that when a user is saved, existing role associations aren’t duplicated.

The Booking Status Lifecycle

Bookings flow through a defined state machine:

This lifecycle is enforced in BookingServiceImpl, where each status transition is validated before execution. You can’t jump from PENDING to RENTAL_COMPLETED — you must go through CONFIRMED and RENTAL_INITIATED first. The confirmBooking() method checks that the current status isn’t USER_CANCELLED, ADMIN_CANCELLED, RENTAL_INITIATED, or NO_SHOW before allowing the transition:

The copy() method on the Builder is what makes immutability work in practice. We start with a copy of the existing booking, change only the status field, and build a new instance. The original booking object remains unchanged — this is essential for thread safety in concurrent environments.

The REST API: Controllers, DTOs, and Validation

The API layer follows a clean separation of concerns. Controllers handle HTTP concerns (request parsing, response formatting, status codes), Services handle business logic, and DTOs isolate the internal domain model from the public API surface.

BookingController: The Full CRUD Surface

The BookingController exposes a complete REST API for booking management:

Every endpoint extracts the current user from the Spring Security context via SecurityUtils.getRequesterIdentifier(), which returns the authenticated user’s email. This means users can only access their own bookings — the controller checks booking.getUser().getEmail().equals(requesterId) before returning data.

The BookingRequestDTO and BookingUpdateDTO classes use Jakarta Validation annotations (@Valid) to enforce input constraints at the controller level. Invalid requests are rejected before they ever reach the service layer.

CarController: Date-Aware Availability

The CarController goes beyond simple CRUD. Its /available endpoint supports date-range queries that check for booking conflicts in real-time:

This means the frontend can show “Available for your dates” without making separate API calls. The date filtering happens at the repository level using the same JPQL overlap query we’ll discuss in Part 2.

The Vue 3 Frontend: Composition API in Practice

The frontend is a Vue 3 Single Page Application using the Composition API. It’s organized into two main areas: Main (customer-facing) and Admin (back-office).

Component Architecture

The frontend has over 80 Vue components, organized by domain:

The AdminSidebar.vue provides navigation across all admin sections: Dashboard, Staff Daily Operations, Cars, Bookings, Rentals, Users, Drivers, Damage Reports, FAQ, Help Center, File Management, and Settings. Each admin section has its own management component with full CRUD operations.

State Management and API Communication

The frontend communicates with the Spring Boot backend through a centralized API layer. Authentication tokens are managed via HttpOnly cookies (refresh token) and in-memory storage (access token). The OAuth2RedirectHandler.vue component handles the Google OAuth2 callback, extracting the access token from the redirect URL and storing it for subsequent API calls.

The MyBookings.vue component demonstrates the typical data flow: it calls /api/v1/bookings/my-bookings, receives a list of BookingResponseDTO objects, and renders them with status badges, date ranges, and action buttons (confirm, cancel, update). The component uses Vue 3’s ref() and onMounted() lifecycle hooks for reactive data loading.

The Live Interface

Here’s the live homepage — clean, focused, and ready for customers:

The homepage uses a category-based layout: Economy Cars starting at R550/day, Luxury Cars at R800/day, and Special Offers at R450/day. Each category links to a filtered car listing page.

The car listing page showing the fleet with search, filtering, and date-based availability:

And the car detail page with image carousel, specifications, and booking form:

The car detail page shows the full specification: make, model, year, category, price group, daily rate, transmission type, and fuel type. The image carousel pulls from the MinIO storage bucket via pre-signed URLs generated by the FileStorageService.

The user profile page showing account details and rental history:

And the “My Bookings” page where users track their reservations:

The rental history page showing completed rentals:

The About Us page:

Help Center for customer support:

FAQ page with common questions:

Related Reading

• TorqueBooks: Workshop Management System Case Study — Exploring similar modular architectures using PocketBase.
• Vue 3 Composition API: Real-World Patterns — How we structured the Vue 3 frontend for OnTheGoRentals.
• From Rebuilding Auth to a Shared Identity Layer — Deeper strategies for structuring robust login services.