Skip to main content

​
Prerequisites

The backend requires the following tools:
  • Java 17 - Required Java version
  • Maven 3.6+ - Build tool and dependency management
  • PostgreSQL 16 - Database (or use Docker)
  • IDE - IntelliJ IDEA or Eclipse recommended

​
Project Structure

The backend follows a standard Spring Boot project structure: 
backend/
├── src/main/java/com/productdistribution/backend/
│   ├── config/          # Configuration classes (CORS, WebClient)
│   ├── controllers/     # REST API endpoints
│   ├── dtos/           # Data Transfer Objects
│   ├── entities/       # JPA entities
│   ├── enums/          # Enumeration types
│   ├── exceptions/     # Custom exception classes
│   ├── mappers/        # MapStruct mappers
│   ├── repositories/   # Spring Data JPA repositories
│   ├── schedulers/     # Scheduled tasks
│   ├── services/       # Business logic layer
│   └── utils/          # Utility classes
├── src/main/resources/
│   ├── application.properties        # Main configuration
│   ├── application-dev.properties    # Dev profile
│   ├── application-prod.properties   # Production profile
│   └── db/migration/                 # Flyway migrations
├── src/test/java/                    # Test files
└── pom.xml                           # Maven dependencies

​
Dependencies

Key dependencies from pom.xml:

​
Core Framework

  • Spring Boot 3.4.5 - Main framework
  • Spring Web - REST API support
  • Spring Data JPA - Database access
  • Spring WebFlux - Reactive HTTP client
  • Spring Validation - Request validation
  • Spring Cache - Caching abstraction
  • Spring Actuator - Health checks and monitoring

​
Database

  • PostgreSQL - Production database driver
  • H2 - In-memory database for testing
  • Flyway - Database migrations

​
Development Tools

  • Lombok 1.18.42 - Reduce boilerplate code
  • MapStruct 1.6.3 - DTO mapping
  • Spring DevTools - Hot reload during development

​
Testing

  • Spring Boot Test - Testing support
  • JUnit 5 - Test framework
  • Mockito - Mocking framework
  • AssertJ - Fluent assertions
  • Testcontainers 1.21.4 - PostgreSQL containers for integration tests

​
Code Quality

  • JaCoCo 0.8.12 - Code coverage
  • SonarQube Scanner - Code quality analysis

​
Building the Project

​
Install Dependencies

mvn clean install

​
Build Without Tests

mvn clean package -DskipTests
Build artifacts are stored in the target/ directory.

​
Build with Code Coverage

mvn clean test jacoco:report
Coverage report: target/site/jacoco/index.html

​
Running Locally

​
Default Profile (Dev)

mvn spring-boot:run
The application starts at http://localhost:8080.

​
Specific Profile

# Development profile
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# Production profile
mvn spring-boot:run -Dspring-boot.run.profiles=prod

​
Using JAR File

# Build the JAR
mvn clean package

# Run the JAR
java -jar target/backend-0.0.1-SNAPSHOT.jar

​
Configuration

​
Application Properties

Key configuration in application.properties: 
# Application name
spring.application.name=backend

# Active profile
spring.profiles.active=${SPRING_PROFILES_ACTIVE:dev}

# JPA settings
spring.jpa.hibernate.ddl-auto=validate

# Distribution strategy
distribution.strategy.warehouse-selection=distanceWithToleranceStrategy

# Caching
spring.cache.type=simple
spring.cache.cache-names=globalMetrics,detailedMetrics

# Server port
server.port=${PORT:8080}

​
Environment Variables

Set these environment variables: 
# Database connection
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/productdistribution
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=yourpassword

# Frontend URL for CORS
export APP_FRONTEND_URL=http://localhost:4200

​
IDE Setup

  1. Import Project
    • Open IntelliJ IDEA
    • File → Open → Select backend/pom.xml
    • Import as Maven project
  2. Enable Annotation Processing
    • Settings → Build, Execution, Deployment → Compiler → Annotation Processors
    • Check “Enable annotation processing”
    • Required for Lombok and MapStruct
  3. Install Lombok Plugin
    • Settings → Plugins
    • Search for “Lombok”
    • Install and restart
  4. Run Configuration
    • Run → Edit Configurations
    • Add new Spring Boot configuration
    • Main class: com.productdistribution.backend.BackendApplication
    • Environment variables: Set database credentials

​
Eclipse

  1. Import Project
    • File → Import → Existing Maven Projects
    • Select backend directory
  2. Install Lombok
    • Download lombok.jar
    • Run: java -jar lombok.jar
    • Select Eclipse installation directory
  3. Enable Annotation Processing
    • Project Properties → Java Compiler → Annotation Processing
    • Enable project specific settings

​
VS Code

  1. Install Extensions
    • Extension Pack for Java
    • Spring Boot Extension Pack
    • Lombok Annotations Support
  2. Open Folder
    • Open backend directory
    • VS Code auto-detects Maven project

​
Database Setup

​
Using Docker

# From project root
docker-compose up -d postgres

​
Using Local PostgreSQL

CREATE DATABASE productdistribution;
Flyway automatically creates tables on startup.

​
Health Check

Once running, verify the application: 
# Health endpoint
curl http://localhost:8080/actuator/health

# API test
curl http://localhost:8080/api/products

​
Common Issues

​
Port Already in Use

Change the port in application.properties: 
server.port=8081

​
Lombok Not Working

Ensure:
  • Annotation processing is enabled
  • Lombok plugin is installed
  • IDE is restarted after plugin installation

​
MapStruct Compilation Errors

Run Maven install to generate mapper implementations: 
mvn clean install

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us