Rentify Backend is a production-grade, highly scalable RESTful API powering a modern rental marketplace and property accommodation platform. It handles the complete lifecycle of property listings, geo-spatial discovery and faceted search, conflict-free booking reservations, internal wallet transactions, direct host-guest messaging, verified guest reviews, and monetization through promotion and subscription tiers.
Engineered with Clean Architecture, Domain-Driven Design (DDD) principles, and strict enterprise security standards, Rentify Backend delivers high-throughput request processing, strict data consistency, and seamless integration with modern web and mobile frontends.
- Java 17 (Eclipse Temurin): Long-term support Java runtime utilizing modern language features.
- Spring Boot 3.4.3 (Spring Framework 6.x): Core enterprise application framework.
- Spring Web MVC: High-performance RESTful API controllers with standard HTTP semantics and OpenAPI annotations.
- Spring Security 6 & JJWT (0.11.5): Stateless authentication architecture with HMAC-SHA256 tokens and Google OAuth2 ID token verification.
- Spring Data JPA & Hibernate: ORM layer with
open-in-view=false, entity graph fetching, and query optimization. - Jakarta Bean Validation: Strict runtime validation of all request DTO payloads.
- PostgreSQL 16: Relational storage with ACID compliance, indexed multi-column filters, and transactional integrity.
- Redis 7 (Alpine): Distributed in-memory data store powering instant JWT token revocation lists (blacklisting), session state, and fast cache lookups.
- Auditing & Entity Lifecycle: Base
@MappedSuperclassmodels (AuditableEntity,CreatedAtEntity) for automated timestamping and lifecycle tracking.
- Dual-Mode Authentication Strategy: Configurable auth strategy supporting secure HTTP-only cookies (
SameSite=Lax,Secure,HttpOnly) for modern SPAs and standardAuthorization: Bearer <token>headers for mobile clients. - CSRF Token Handshake: Cookie-to-header cross-site request forgery prevention mechanism (
X-CSRF-Token) for cookie-based authentication. - Granular RBAC: Role-Based Access Control (
ROLE_GUEST,ROLE_HOST,ROLE_ADMIN) securing listing operations, booking confirmations, and wallet transactions. - BCrypt Password Hashing: Adaptive hashing algorithm securing user credentials.
- Cloudinary Java SDK (1.39.0): Cloud-native multipart image uploading, format transformations, secure deletion, and global CDN delivery for property galleries and user avatars.
- Google OAuth 2.0 Client: Token verifier for social single sign-on (SSO).
- MapStruct 1.5.5: Zero-overhead, compile-time type-safe DTO-to-entity mappers.
- Project Lombok: Boilerplate reduction for data models and dependency injection.
- SpringDoc OpenAPI 3.0 (v2.8.5): Automated OpenAPI 3.0 specification generation and interactive Swagger UI.
- Testcontainers 1.21.4: Hermetic PostgreSQL container testing ensuring exact production parity in integration test suites.
- JUnit 5, Mockito & AssertJ: 200+ unit and integration tests across services, mappers, and controllers.
- Multi-Stage Docker: Lightweight Eclipse Temurin JRE container builds.
- Docker Compose: Multi-service local environment orchestration (PostgreSQL, Backend API, Frontend SPA).
- Multi-Strategy Authentication & Google SSO: User onboarding via Email/Password or Google OAuth 2.0. Dynamic token delivery via HTTP-only secure cookies (with CSRF protection) or Bearer header tokens.
- User Profile & Avatar Management: Complete profile lifecycle with Cloudinary avatar uploads, secure password rotation, and safe account deactivation.
- Faceted Property Search & Interactive Map Pins: Multi-criteria search filters (city, district, price min/max, guest capacity, bedrooms, amenities, property type, available dates) paired with high-speed
/map-pinsendpoint for lightweight geo-coordinate clustering. - Host Property Lifecycle & Media Gallery: Host property CRUD operations, lifecycle state management (
DRAFT,ACTIVE,INACTIVE,BLOCKED), multi-photo uploads with Cloudinary CDN optimization, and ownership enforcement. - Smart Availability Engine & Collision Prevention: Unified calendar engine merging real-time guest booking reservations with host manual availability blocks, with automated date-range collision detection preventing double-bookings.
- End-to-End Booking Workflow: Multi-state reservation state machine (
PENDING,CONFIRMED,REJECTED,CANCELLED,COMPLETED), automatic price calculation (nightly rate, cleaning fee, service fee, total), and host approval/rejection workflows. - Internal Wallet & Transaction Ledger: In-app wallet management with configurable currency (
UAH), predefined top-up amounts, balance validation, booking payment execution, and paginated transaction audit history. - Monetization & Promotion Packages: TOP property placement, subscription packages, and automated promotion expiration schedulers to boost listing visibility in search results.
- Direct Host-Guest Messaging: Context-aware messaging threads tied to properties and bookings, message history, unread counters, and instant communication.
- Verified Reviews & Multi-Criteria Ratings: Post-stay feedback loop allowing guests to review completed bookings with rating categories (cleanliness, accuracy, communication, location, check-in, value) and dynamic property rating aggregates.
- Favorites & Wishlists: One-click bookmarking for properties with instant personal collection retrieval.
- Location Taxonomy & Amenity Directories: Autocomplete location suggestion service for cities, districts, metro stations, and residential complexes alongside category-grouped amenities.
Rentify Backend is designed as a modular, maintainable Clean Architecture service.
- Layered Architecture: Strict separation of concerns across Presentation (Controllers & DTOs), Domain/Service Layer (Business rules, validations, state machines), and Data Access (Spring Data JPA Repositories & Entities).
- Dual Authentication Strategy Pattern: Seamless switching between stateless Bearer header authorization and browser-native HTTP-only cookies with CSRF token validation (
AuthCookieService). - Conflict-Free Booking & Availability Matrix: Transactional date-range validation algorithm that verifies zero collisions against both active reservations and manual calendar blocks within transactional boundaries.
- Compile-Time DTO Serialization (MapStruct): High-performance DTO mapping generated at compile time, eliminating runtime reflection overhead and preventing accidental internal entity exposure.
- Database Query Optimization & Anti-N+1 Protection: Disabled
open-in-viewpattern (spring.jpa.open-in-view=false) forcing explicit transaction-scoped data fetching via@EntityGraphand custom JPQL queries. - Auditing & Entity Lifecycle Tracking: Base classes (
AuditableEntity,CreatedAtEntity) ensuring transparent timestamping and auditing across all persistent entities. - Hermetic Integration Testing with Testcontainers: Automated spin-up of containerized PostgreSQL instances (
AbstractIntegrationTest) ensuring test isolation and zero reliance on mocked databases.
The codebase undergoes rigorous automated testing and static analysis to guarantee stability, data integrity, and production readiness:
- 200+ Unit & Integration Tests: Comprehensive JUnit 5 and Mockito test suite covering business logic, domain services, custom validation rules, and error handling.
- Testcontainers PostgreSQL Integration Suite: Real PostgreSQL container test suite validating authentication flows, cookie sessions, booking lifecycles, review submissions, property creation, search queries, and wallet operations.
- Strict Jakarta Validation: Strict constraint annotations (
@Valid,@NotNull,@NotBlank,@Positive,@Future) on all incoming request payloads to eliminate invalid data at the boundary. - Multi-Stage Docker Validation: Containerized build and packaging verification.
# Run all unit and integration tests (requires Docker Desktop running)
./mvnw clean test
# Run a specific integration test class
./mvnw test -Dtest=RegistrationIntegrationTest
# Run unit tests only
./mvnw test -Dtest=*UnitTestrentify-backend/
├── .mvn/ # Maven wrapper configuration
├── docs/
│ ├── API_SURFACE.md # Complete REST API & endpoint specification
│ └── screenshots/
│ └── api-overview.png # Architecture & API overview diagram
├── src/
│ ├── main/
│ │ ├── java/com/rentify/core/
│ │ │ ├── config/ # Security, OpenAPI, Cloudinary, CORS, Cookie configs
│ │ │ ├── controller/ # REST API controllers (Auth, Booking, Property, Wallet, etc.)
│ │ │ ├── dto/ # Request & Response Data Transfer Objects
│ │ │ ├── entity/ # JPA Domain Entities (User, Property, Booking, Payment, etc.)
│ │ │ ├── enums/ # Domain Enums (BookingStatus, PropertyStatus, Roles, etc.)
│ │ │ ├── exception/ # Global exception handling & custom domain errors
│ │ │ ├── mapper/ # MapStruct compile-time DTO mappers
│ │ │ ├── repository/ # Spring Data JPA repositories with custom JPQL queries
│ │ │ ├── scheduler/ # Scheduled tasks (promotion expiries, cleanup jobs)
│ │ │ ├── security/ # JWT utilities, Custom UserDetailsService, Auth filters
│ │ │ ├── service/ # Domain business logic interfaces & implementations
│ │ │ ├── validation/ # Custom Jakarta validators and annotations
│ │ │ └── RentifyBackendApplication.java
│ │ └── resources/
│ │ ├── application.properties # Main application configuration
│ │ └── application-secret.properties # Local secret overrides (gitignored)
│ └── test/
│ └── java/com/rentify/core/
│ ├── integration/ # Testcontainers PostgreSQL full-stack integration tests
│ └── unit/ # Isolated Mockito unit tests for service layer
├── Dockerfile # Multi-stage Eclipse Temurin JRE container build
├── docker-compose.yml # Local multi-service infrastructure (PostgreSQL, Backend, Frontend)
├── pom.xml # Maven dependencies & build configuration
└── README.md # Project documentation
- Java 17+ (JDK)
- Maven 3.9+ (or use included
./mvnw) - Docker & Docker Compose (for PostgreSQL database and Testcontainers)
- Cloudinary Account (for property photo and avatar uploads)
Run PostgreSQL in Docker, and run Backend locally with hot-reloading:
# 1. Clone the repository
git clone https://github.com/polchduikt/rentify-backend.git
cd rentify-backend
# 2. Start PostgreSQL container
docker compose up -d db
# 3. Create .env file or application-secret.properties
cp .env.example .env
# 4. Start the Spring Boot application
./mvnw spring-boot:runRun PostgreSQL, Backend API, and Frontend SPA simultaneously in Docker:
docker compose up --build -dTo stop all containers:
docker compose downConfigure environment variables in .env or in src/main/resources/application-secret.properties:
# Database Configuration
DB_URL=jdbc:postgresql://localhost:5432/rentify
DB_USERNAME=postgres
DB_PASSWORD=your_secure_password
# Security & JWT
SECRET_KEY=your_base64_encoded_jwt_secret_key_min_256_bits
GOOGLE_CLIENT_ID=your_google_oauth_client_id
# Auth Strategy (cookie or bearer)
AUTH_STRATEGY=cookie
AUTH_COOKIE_NAME=rentify_access_token
AUTH_COOKIE_DOMAIN=
AUTH_COOKIE_SECURE=false
AUTH_COOKIE_SAME_SITE=Lax
CSRF_COOKIE_NAME=csrf_token
CSRF_HEADER_NAME=X-CSRF-Token
CSRF_COOKIE_SECURE=false
ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000
# Wallet & Currency
WALLET_CURRENCY=UAH
WALLET_TOP_UP_OPTIONS=300.00,500.00,1000.00
# Cloudinary CDN Integration
CLOUDINARY_CLOUD_NAME=your_cloudinary_cloud_name
CLOUDINARY_API_KEY=your_cloudinary_api_key
CLOUDINARY_API_SECRET=your_cloudinary_api_secretTo run Testcontainers integration tests smoothly on Windows:
- In Docker Desktop -> Settings -> General -> Enable
Expose daemon on tcp://localhost:2375 without TLS. - Run in PowerShell (Administrator):
[System.Environment]::SetEnvironmentVariable("DOCKER_API_VERSION", "1.47", "Machine")
New-Item -Path "$env:USERPROFILE\.testcontainers.properties" -ItemType File -Force
Set-Content "$env:USERPROFILE\.testcontainers.properties" "docker.host=npipe:////./pipe/docker_engine_linux`ntestcontainers.reuse.enable=true"- Restart your IDE and run
./mvnw test.
- Backend REST API: http://localhost:8080/api/v1
- Swagger / OpenAPI Documentation: http://localhost:8080/swagger-ui/index.html
- OpenAPI JSON Specification: http://localhost:8080/v3/api-docs
- PostgreSQL Database:
localhost:5432
The complete, versioned REST API specification, request/response payload schemas, parameter types, and security policies are documented in the dedicated reference guide:
Complete API Surface Specification (docs/API_SURFACE.md)
The backend provides real-time interactive OpenAPI 3.0 documentation generated automatically via SpringDoc:
- Swagger UI: http://localhost:8080/swagger-ui/index.html
- OpenAPI 3.0 JSON Schema: http://localhost:8080/v3/api-docs
To test secured endpoints directly in Swagger UI:
- Authenticate via
POST /api/v1/sessions(orPOST /api/v1/users). - Copy the returned
token. - Click the Authorize button at the top of the Swagger page and enter
Bearer <your_token>.
Rentify Backend is actively maintained and continuously enhanced with new features, performance optimizations, and integrations.
This project is licensed under the MIT License. See the LICENSE file for details.