🛒 3Z Insta Cart - Spring Boot E-Commerce REST API

A production-grade, Spring Boot 3 REST API for 3Z Insta Cart, an instant grocery & e-commerce shopping platform built following official Spring Boot documentation and best practices.

---

🚀 Key Features

• Product Catalog & Inventory:
  • Full CRUD operations with category filtering, keyword search, stock tracking, and pricing.
  • Pre-seeded with realistic instant grocery catalog across 7 categories (PRODUCE, DAIRY_EGGS, BAKERY, BEVERAGES, SNACKS, PANTRY, MEAT_SEAFOOD).
• 3Z Insta Cart Shopping Engine:
  • Add items to cart with automatic duplicate item quantity consolidation.
  • Real-time stock validation and error handling.
  • Item updates and removals.
  • Dynamic financial computation: item totals, subtotal, 7% sales tax, and delivery fee calculation ($3.99, free on orders over $35.00).
• Atomic Checkout & Order Management:
  • Atomically validates stock availability across all items at checkout.
  • Automatically deducts inventory and clears the user's cart upon order confirmation.
  • Unique human-readable tracking numbers (3Z-YYYYMMDDHHMMSS-XXXX).
  • Order status tracking (PENDING -> CONFIRMED -> PREPARING -> OUT_FOR_DELIVERY -> DELIVERED).
• Interactive Documentation & Observability:
  • OpenAPI 3 / Swagger UI at http://localhost:8080/swagger-ui.html.
  • Spring Boot Actuator health and metrics endpoints at http://localhost:8080/actuator/health.
  • H2 Database Console at http://localhost:8080/h2-console.

---

🛠️ Tech Stack & Requirements

• Java: OpenJDK 21 / 23
• Framework: Spring Boot 3.3.5
• Data & Persistence: Spring Data JPA, Hibernate, H2 In-Memory Database
• Validation: Jakarta Bean Validation (@Valid, @NotNull, @Min, @Email)
• Documentation: SpringDoc OpenAPI UI 2.6.0
• Build Tool: Apache Maven (wrapper ./mvnw provided)

---

📦 How to Run

1. Build and Run Tests

./mvnw clean test

2. Run Application

./mvnw spring-boot:run

Or run the packaged JAR:

java -jar target/insta-cart-1.0.0.jar

The server will start on port 8080.

---

📖 API Documentation & Endpoints

📍 Interactive Swagger UI

Open your browser at: 👉 http://localhost:8080/swagger-ui.html 👉 OpenAPI JSON Spec: http://localhost:8080/v3/api-docs

---

🛒 1. Shopping Cart API (/api/v1/carts)

Method	Endpoint	Description
GET	/api/v1/carts/{cartId}	Get cart details with calculated totals & items
GET	/api/v1/carts/customer/{customerId}	Get or create cart for customer
POST	/api/v1/carts/{cartId}/items	Add product to cart (body: {"productId": 1, "quantity": 2})
PUT	/api/v1/carts/{cartId}/items/{itemId}	Update item quantity in cart
DELETE	/api/v1/carts/{cartId}/items/{itemId}	Remove specific item
DELETE	/api/v1/carts/{cartId}/clear	Clear all items from cart

---

📦 2. Orders & Checkout API (/api/v1)

Method	Endpoint	Description
POST	/api/v1/checkout	Checkout cart, deduct stock, create order
GET	/api/v1/orders/{id}	Get order details by ID
GET	/api/v1/orders/number/{orderNumber}	Lookup order by 3Z tracking number
GET	/api/v1/orders/customer/{customerId}	View order history for a customer
PATCH	/api/v1/orders/{id}/status	Update order delivery status

---

🍎 3. Products API (/api/v1/products)

Method	Endpoint	Description
GET	/api/v1/products	List active products (supports ?category= and ?search=)
GET	/api/v1/products/{id}	Get product details
POST	/api/v1/products	Create a new product
PUT	/api/v1/products/{id}	Update product information/stock
DELETE	/api/v1/products/{id}	Soft delete product

---

👤 4. Customers API (/api/v1/customers)

Method	Endpoint	Description
GET	/api/v1/customers	List registered customers
GET	/api/v1/customers/{id}	Get customer profile
POST	/api/v1/customers	Register a new customer

---

🧪 Quick Test Walkthrough (cURL)

# 1. Fetch available products
curl http://localhost:8080/api/v1/products

# 2. Add Organic Avocados and Whole Milk to Cart 1
curl -X POST http://localhost:8080/api/v1/carts/1/items \
  -H "Content-Type: application/json" \
  -d '{"productId": 1, "quantity": 2}'

curl -X POST http://localhost:8080/api/v1/carts/1/items \
  -H "Content-Type: application/json" \
  -d '{"productId": 4, "quantity": 1}'

# 3. View Cart Summary & Totals
curl http://localhost:8080/api/v1/carts/1

# 4. Instant Checkout
curl -X POST http://localhost:8080/api/v1/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "cartId": 1,
    "deliveryAddress": "742 Evergreen Terrace",
    "deliveryCity": "Springfield",
    "deliveryZipCode": "97477",
    "deliveryInstructions": "Leave on front porch"
  }'

# 5. Track Order Status
curl http://localhost:8080/api/v1/orders/1

3Z-Insta-Cart-SpringBoot