OrderFlow API

Transactional ecommerce backend for handling product catalog, shopping cart, order creation, inventory reservation, and mock payment confirmation.

Features

• User registration and JWT authentication
• Role-based access control for customers and admins
• Product catalog with admin-only product management
• Shopping cart with quantity management
• Transactional order creation from cart
• Inventory reservation and stock restoration on cancellation
• Mock payment confirmation with idempotency support
• Global error responses with validation details
• OpenAPI documentation with Swagger UI
• Integration tests with PostgreSQL Testcontainers

Tech Stack

• Java 21 + Spring Boot 4
• PostgreSQL + Flyway
• Docker / Docker Compose
• JUnit 5 + Testcontainers
• OpenAPI / Swagger UI

Requirements

• Docker Desktop
• Java 21
• Git

Project Structure

src/main/java/com/ktrubilo9/orderflow
├── auth        # registration, login, JWT generation and verification
├── cart        # customer cart and cart items
├── common      # shared exceptions and API error handling
├── config      # security, password encoder and OpenAPI configuration
├── inventory   # stock validation, reservation and release logic
├── order       # orders, order items and order state transitions
├── payment     # mock payment flow and idempotency handling
├── product     # product catalog and admin product management
└── user        # user entity, roles and repository

Running with Docker Compose

Create an environment file from the example:

cp .env.example .env

Start the application and database:

docker compose up --build

The API should be available at:

http://localhost:8080

Swagger UI should be available at:

http://localhost:8080/swagger-ui/index.html

Health check endpoint:

http://localhost:8080/actuator/health

Environment Variables

Example variables used by the application:

POSTGRES_DB=orderflow
POSTGRES_USER=orderflow
POSTGRES_PASSWORD=orderflow
POSTGRES_PORT=5432

SPRING_DATASOURCE_URL=jdbc:postgresql://postgres:5432/orderflow
SPRING_DATASOURCE_USERNAME=orderflow
SPRING_DATASOURCE_PASSWORD=orderflow

JWT_SECRET=replace-with-a-strong-random-secret
JWT_EXPIRATION_SECONDS=3600
SERVER_PORT=8080

Running Tests

Run the full test suite:

./mvnw test

The tests use Testcontainers, so Docker must be running.

The test suite covers:

• authentication flow
• JWT verification
• request validation
• product management permissions
• cart operations
• order creation from cart
• stock reservation
• insufficient stock handling
• order cancellation and stock restoration
• mock payment flow
• payment idempotency
• repository behavior

API Overview

Authentication:

• POST /api/auth/register
• POST /api/auth/login
• GET /api/auth/me

Products:

• GET /api/products
• GET /api/products/{id}
• POST /api/products - admin only
• PUT /api/products/{id} - admin only
• PATCH /api/products/{id}/deactivate - admin only

Cart:

• GET /api/cart
• POST /api/cart/items
• PATCH /api/cart/items/{itemId}
• DELETE /api/cart/items/{itemId}
• DELETE /api/cart/items

Orders:

• GET /api/orders
• POST /api/orders
• GET /api/orders/{orderId}
• GET /api/orders/{orderId}/payments
• PATCH /api/orders/{orderId}/cancel

Payments:

• GET /api/payments
• POST /api/payments

Demo Data

Flyway seeds several demo products:

• KEYBOARD-001
• MOUSE-001
• MONITOR-001

This allows the customer flow to be tested immediately after startup.

Notes

• Payments are mocked and always create a successful payment if the order is payable.
• Public registration creates customer accounts. Admin-only product endpoints require a user with the ADMIN role.
• Product stock is reserved when an order is created.
• Cancelling a pending order restores stock.
• Reusing the same payment idempotency key for the same order returns the existing payment.
• Reusing an idempotency key for another order returns a conflict.