E‑Commerce Auction System – Microservice Backend

This repository contains a small auction platform built as four Spring Boot microservices:

• auth-service – users, sign‑up / sign‑in, HTML UI pages.
• catalogue-auction-service – catalogue items and auction logic (Forward & Dutch).
• payment-service – simple payment placeholder / receipt.
• gateway – Spring Cloud Gateway front‑end on port 8080.

The system supports Forward bidding and Dutch “buy now” auctions, with a simple HTML UI (Thymeleaf) and separate PostgreSQL databases for each service when running under Docker.

---

Tech Stack

• Java 21, Spring Boot 3.5.x
• Spring Web, Spring Data JPA, Validation, Security
• Spring Cloud Gateway (reactive) on the gateway service
• Thymeleaf server‑side templates (auth‑service UI)
• PostgreSQL 16 (Docker profile), H2 in‑memory for local dev
• JWT via com.auth0:java-jwt

---

Project Layout

AuctionProject/
  auth-service/                   # UI + auth + orchestration
  catalogue-auction-service/      # catalogue items + auction engine
  payment-service/                # payment placeholder
  gateway/                        # edge API gateway on 8080

docs/                             # diagrams / notes
docker-compose.yml                # multi-container environment
.env.example                      # example env overrides

Each service is a standalone Spring Boot application with its own pom.xml and application[-docker].properties.

---

Services, Ports, and Databases

HTTP ports (host → container):

• 8080:8080 – gateway
  • Public entry point. Routes:
    • /api/auth/** → auth-service:8081
    • /api/catalogue/**, /api/auctions/** → catalogue-auction-service:8082
    • /api/payments/** → payment-service:8083
    • everything else (/**) → auth-service:8081 (HTML UI).
• 8081:8081 – auth-service
  • Handles sign‑up/sign‑in, catalogue page, auction page, payment pages.
• 8082:8082 – catalogue-auction-service
  • JSON APIs only (no HTML at /), e.g. /api/catalogue/items, /api/auctions/{id}.
• 8083:8083 – payment-service
  • JSON APIs for payments, e.g. /api/payments/**. No HTML UI on /.

PostgreSQL containers (host → container):

• postgres-auth – 5433:5432, DB authdb, user auth.
• postgres-catalogue – 5434:5432, DB cataloguedb, user catalogue.
• postgres-payment – 5435:5432, DB paymentdb, user payment.

Each service connects to its DB using the SPRING_DATASOURCE_URL set in docker-compose.yml.

To inspect data directly you can connect with any SQL client to:

• localhost:5433 / authdb / auth
• localhost:5434 / cataloguedb / catalogue
• localhost:5435 / paymentdb / payment

---

Auction Behaviour (Forward vs Dutch)

Forward Auctions

• Seller sets a starting price and an end time.
• Bidders can see the current highest bid and time remaining.
• Each new bid must be an integer strictly higher than the current price.
• The auction ends when the fixed time L elapses; the highest bidder wins.
• If no bids are placed before L, the item is removed/marked ended.

Implementation highlights:

• Entity: CatalogueItem in catalogue-auction-service.
• Validation: AuctionService.validateForwardBid enforces type, active status, end time, and strictly increasing bids.
• Updates: AuctionService.attemptForwardBid stores the new currentPrice and highestBidder transactionally.

Dutch Auctions

• Seller sets a high starting price, a reserve price, and an end time.
• A scheduler (DutchAuctionScheduler) periodically decrements the price down to the reserve.
• Any bidder may accept the current price via “Buy Now”, which ends the auction immediately at that price.
• If no one buys before time L elapses, the item is ended and removed.

Implementation highlights:

• Periodic price decrement: CatalogueRepository.decrementDutchPrices() called by DutchAuctionScheduler.
• Buy Now validation: AuctionService.validateDutchBuy (type, active, not ended).
• Buy Now update: AuctionService.attemptDutchBuy sets active=false, records highestBidder, and stamps the final end time.

End Times and Time Zones

• Item creation requires a future end time:
  • API DTO CreateItemRequest uses @Future on endTime.
  • UI form ItemForm also uses @Future so users cannot submit past times.
• Both auth-service and catalogue-auction-service set a consistent JVM time zone (e.g. America/Toronto) to ensure that browser times and server validation line up.

---

Running with Docker (recommended)

From the repo root (the directory containing docker-compose.yml):

# Build all services
docker compose build

# Start services and Postgres
docker compose up

Then visit the gateway:

• UI entry point: http://localhost:8080
  • Sign up / sign in.
  • Access the active catalogue.
  • Create Forward / Dutch auction items.
  • Place bids or use Buy Now.

The individual service ports (8081, 8082, 8083) are available for API testing (e.g. with Postman), but they are not intended to serve HTML on / – a plain / request will return the default Spring “Whitelabel Error Page (404)” for those services.

---

Running Individual Services Locally (without Docker)

Each service can also run against its default in‑memory H2 database:

cd AuctionProject/auth-service
mvn spring-boot:run

cd AuctionProject/catalogue-auction-service
mvn spring-boot:run

cd AuctionProject/payment-service
mvn spring-boot:run

cd AuctionProject/gateway
mvn spring-boot:run

In this mode:

• auth-service, catalogue-auction-service, and payment-service use their application.properties (H2 URLs).
• gateway still listens on http://localhost:8080 and forwards to the other services on 8081–8083.

Make sure each service is started with the correct SERVER_PORT (via properties or env) if you run them outside Docker.

---

Environment Configuration

• .env.example contains example overrides for ports, DB URLs, and secrets.
• To customize, copy it to .env and adjust values, then re‑run docker compose.

Key environment variables (per service):

• SERVER_PORT – HTTP port inside the container.
• SPRING_DATASOURCE_URL, SPRING_DATASOURCE_USERNAME, SPRING_DATASOURCE_PASSWORD – DB connection.
• AUTH_SERVICE_URL, CATALOGUE_SERVICE_URL, PAYMENT_SERVICE_URL – service‑to‑service URLs.
• SECURITY_JWT_SECRET, SECURITY_JWT_EXP_MIN – JWT configuration for auth/gateway.

---

Notes

• Data is persisted in the Postgres volumes (pgdata-*) when running via Docker; stopping containers does not wipe data unless you remove the volumes.
• When running with in‑memory H2 (non‑Docker), data is lost on restart.
• The payment service is intentionally simplified: it demonstrates the flow (including a “payment placeholder” and receipt page) but does not integrate with a real payment provider.

This README reflects the current microservice layout and auction behaviour after recent changes (validation, time‑zone handling, and updated bidding/Buy Now logic).