Product Catalog Spring Boot API

Project Overview

This project implements a comprehensive, enterprise-grade RESTful API for product catalog management using Spring Boot 3.5.4. It demonstrates modern Java application development with JWT authentication, advanced inventory management, soft delete patterns, audit logging, and comprehensive testing. The API is production-ready with role-based authorization, database optimization, and full observability, including an advanced integration with Spring AI's MCP Server.

Technologies Used

• Language: Java 21
• Framework: Spring Boot 3.5.4 with Spring Security
• AI Framework: Spring AI
• Build Tool: Maven
• Database: PostgreSQL with advanced indexing and user management
• Schema Migration: Flyway (4 migrations)
• Authentication: JWT (JSON Web Tokens)
• Containerization: Docker & Docker Compose
• Testing: JUnit 5, Mockito, Testcontainers, RestAssured
• Code Quality: Spotless (Google Java Format)
• Documentation: Swagger/OpenAPI 3
• Validation: Bean Validation with custom validators
• ORM: Hibernate with soft delete patterns
• Logging: Structured logging with audit trails

🚀 Key Features

• 🔐 Secure by Design: Database-managed users with JWT authentication and granular role-based access control (ADMIN, USER, MANAGER, READONLY).
• 📊 Advanced Product Management: Soft deletes, optimistic locking, inventory tracking, and custom validations.
• 🔍 Powerful API: Pagination, sorting, and advanced filtering capabilities.
• 🤖 Comprehensive AI Integration: Natural language interface for catalog management via Spring AI's MCP Server.
• 🏗️ Robust Database: Optimized queries with strategic indexing and versioned schema migrations using Flyway.
• 🧪 Enterprise-Grade Testing: Full coverage with unit, integration, and E2E tests.
• 📖 Excellent Observability: Interactive documentation with Swagger, custom health indicators, and business metrics.
• 🌍 Multi-Environment Ready: Pre-configured for local, staging, and production deployments using Docker.

🚀 Quick Start (Local)

1. Prerequisites: Java 21, Docker, Maven.
2. Clone the repository:

   git clone https://github.com/your-repo/product-catalog.git
   cd product-catalog

3. Configure environment:

   cp .env.local.example .env.local

4. Run the application:

   docker compose -f docker-compose.local.yml up -d

5. The API will be available at http://localhost:8080 and the Swagger UI at http://localhost:8080/swagger-ui/index.html.

📚 Full Documentation

For a detailed guide on every aspect of this project, please refer to the documents below:

• Getting Started: Complete installation guide and your first API calls.
• Environments & Deployment: Configuration for local, stage, production, and VPS environments.
• API Reference: Detailed endpoints, request/response formats, and cURL examples.
• AI Integration (MCP Server): In-depth guide to the Spring AI integration and its capabilities.
• Architecture & Design: Overview of the software architecture, security, and testing strategy.
• Development Guide: Comprehensive guide for developers including Git Flow, automated workflows, testing strategies, and troubleshooting.

📝 Project Status

✅ Completed Features

• Full CRUD API with advanced filtering
• Database-managed users with JWT authentication and enhanced role-based authorization (ADMIN/USER/MANAGER/READONLY)
• Comprehensive test suite (28+ tests)
• Database optimization with indexing, soft deletes, and user management audit trails
• Custom actuator endpoints for business metrics and health monitoring
• Docker containerization and multi-environment deployment
• Interactive API documentation and enhanced error handling

🎯 Ready for Production

This Spring Boot application demonstrates enterprise-grade development practices and is production-ready.

🔄 Development Workflow

This project uses a fully automated three-branch Git Flow strategy:

• integration → Feature integration with automated PR creation to develop
• develop → Stage deployment with RC versioning + automated PR creation to main
• main → Production deployment with semantic versioning

Automated Workflow: Feature branches → integration → auto-PR → develop → auto-PR → main

Both integration and develop branches automatically create pull requests to the next branch when CI/deployment succeeds, maintaining proper review gates while maximizing development velocity.

📋 Known Issues / TODOs

• 3 integration tests temporarily disabled pending investigation into database constraint edge cases. These issues do not affect core functionality or security.