Logo VicenteDev
Back to Projects
Modern Full Stack Web Platform

Modern Full Stack Web Platform

Complete and scalable web solution built with modern architecture, responsive UI, and advanced features.

Royal Enfield REST API v1.0.0

REST API developed in Java 21 and Spring Boot for the Royal Enfield brand's digital ecosystem. The project provides complete management of the motorcycle catalog, trim versions/variants, image gallery for carousels, detailed technical specifications, dealership network, test ride scheduling, interactive OpenAPI 3 / Swagger UI documentation, and role-based access control (RBAC) with two-factor authentication (2FA via email) and JWT tokens.

Detailed endpoint documentation, request structures, cURL examples, and response formats are also available in markdown format in the API Contract.

🔗 Links & Resources

🛠️ Technologies & Tools

  • Language: Java 21 (LTS)
  • Framework: Spring Boot 4
  • Interactive Documentation: OpenAPI 3 / Swagger UI (springdoc-openapi)
  • Data Persistence: Spring Data JPA / Hibernate
  • Database: PostgreSQL 16
  • Database Versioning: Flyway Migration
  • Security & Authentication: Spring Security + JJWT (JSON Web Token)
  • Two-Factor Authentication (2FA) & Emails: Spring Boot Starter Mail (SMTP)
  • Validation: Jakarta Bean Validation
  • Productivity: Lombok
  • Containerization: Docker and Docker Compose
  • CI/CD: GitHub Actions + GitHub Container Registry (GHCR)
  • Infrastructure / Deploy: Oracle Cloud Infrastructure (OCI - Compute Instance)
  • Error Format: RFC 7807 (ProblemDetail)

🏗️ Architecture & Folder Structure

The project adopts a strict Layered Architecture with separation of concerns and Clean Code and SOLID principles:

src/main/java/com/vicentedev/api_re
├── config/              # Configurations (Security, Swagger/OpenAPI, WebMvc ResourceHandlers)
├── controller/          # Application REST controllers
├── dto/                 # Data Transfer Objects
│   ├── request/         # Input payloads with validation and Swagger schemas
│   └── response/        # Immutable responses with Swagger schemas
├── entity/              # JPA entities mapped to PostgreSQL
├── exception/           # Global exception handling (@RestControllerAdvice)
├── mapper/              # Decoupled mappers between DTOs and Entities
├── repository/          # Spring Data JPA interfaces and Specifications
│   └── specification/   # Dynamic query filters
└── service/             # Interfaces and business rules
    └── impl/            # Service implementations and local storage

🚀 Deploy & Continuous Integration (CI/CD)

The project's continuous delivery lifecycle is fully automated:

  • CI/CD Pipelines: Implemented via GitHub Actions, running compilation, static validations, automated test suites, Docker image builds, publishing to GHCR, and automatic deployment via SSH on Oracle Cloud on every push to the main branch.
  • Production Infrastructure: The application and PostgreSQL database are hosted on an Oracle Cloud (OCI) compute instance, orchestrated via Docker Compose containers with persistent volumes for the database and uploads.

🖼️ File & Media Storage

The application features a decoupled service (FileStorageService) for storing images physically on the local disk:

  • Base directory: ./uploads/ (with /variants/ and /gallery/ subfolders).
  • Supported formats: .jpg, .jpeg, .png, .webp.
  • Public access: The /uploads/** route is served directly by Spring Web MVC.
  • Lifecycle and deletion: When deleting a variant, gallery photo, or motorcycle, the corresponding physical files are automatically removed from the disk.

💻 How to Run the Project Locally

Prerequisites

  • Java Development Kit (JDK) 21 installed
  • Docker and Docker Compose installed

1. Clone the Repository

git clone git@github.com:VicenteAlef/api-royal-enfield-spring-boot.git
cd api-royal-enfield-spring-boot
git checkout dev

2. Run via Docker Compose (Recommended)

Generate the .jar package and start all containers:

./mvnw clean package -DskipTests
docker compose up -d --build

Access:

  • Swagger UI: http://localhost:3001/swagger-ui/index.html
  • Base API: http://localhost:3001/api/v1

3. Run Automated Tests

Validate the integrity of all flows and endpoints using the test database:

./mvnw test

🌿 Branching Strategy (Git Flow)

  • main: Production code and consolidated stable version v1.0.0 (automatic production deployment trigger).
  • dev: Continuous development and feature validation branch.

🗺️ Development Roadmap

  • Phase 1 (Planning & Setup): Relational modeling, Docker Compose, PostgreSQL configuration, and initial migration with Flyway. [Completed]
  • Phase 2 (Catalog, Variants, Gallery, Technical Specs & Uploads): JPA Entities, DTOs, Mappers, Repositories with Specification, FileStorageService, REST controllers, and integration tests. [Completed]
  • Phase 3 (Dealerships & Test Rides): Dealerships CRUD and Test Ride scheduling flow with business rule validation. [Completed]
  • Phase 4 (Security, 2FA & RBAC): JWT authentication with email 2FA, automatic Admin alerts, access tracking (last_login_at), 3 roles (VISITOR, USER, ADMIN), and user management. [Completed]
  • Phase 5 (Testing, OpenAPI / Swagger Documentation & Containerization): Interactive documentation via OpenAPI 3 / Swagger UI with Bearer JWT, suite of 41 integration tests, Dockerfile, and automated deployment via CI/CD. [Completed]

Gallery

Modern Full Stack Web Platform
Modern Full Stack Web Platform
Modern Full Stack Web Platform
Modern Full Stack Web Platform