App Store Application

A comprehensive technical document covering the Store REST API application's architecture, endpoints, design patterns, SOLID principles, and implementation details.

---

Table of Contents

1. Project Summary
2. Technology Stack
3. Architecture Overview
4. API Endpoints Reference
5. Design Principles
6. How It Works
7. Configuration
8. Running & Testing

---

1. Project Summary

App Store Application is a Spring Boot REST API that implements an e-commerce store backend with the following capabilities:

Feature	Description
User Management	Registration and login with BCrypt password hashing
Product Catalog	Browse available products with stock information
Shopping Cart	Session-based cart (add, modify, remove items)
Checkout	Order creation with stock validation and inventory deduction
Session Management	In-memory sessions with 30-minute expiration

The application follows layered architecture, SOLID principles, and industry-standard design patterns for maintainability and scalability.

---

2. Technology Stack

Component	Technology
Language	Java 17+
Framework	Spring Boot 3.2.0
Web	Spring Web (REST)
Persistence	Spring Data JPA
Database	H2 (in-memory)
Security	Spring Security (password hashing only)
Validation	Jakarta Validation
API Docs	SpringDoc OpenAPI / Swagger UI
Testing	JUnit 5, Mockito
Build	Maven

---

3. Architecture Overview

3.1 Layered Architecture

The application follows a strict layered architecture:

┌─────────────────────────────────────────────────────────────┐
│                    REST Controllers                         │
│         (UserController, ProductController, CartController, │
│                       OrderController)                      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Service Layer                            │
│    (UserService, ProductService, CartService, OrderService, │
│                    SessionService)                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  Repository Layer                           │
│     (UserRepository, ProductRepository, OrderRepository)    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                 H2 In-Memory Database                       │
└─────────────────────────────────────────────────────────────┘

3.2 Package Structure

com.store/
├── controller/     # REST API entry points
├── service/        # Service interfaces (abstractions)
├── service/impl/   # Service implementations
├── repository/     # Spring Data JPA repositories
├── model/          # JPA entities & domain models
├── dto/            # Request/Response DTOs
├── mapper/         # Entity ↔ DTO adapters (GOF Adapter)
├── adapter/        # EntityAdapter interface (GOF Adapter)
├── builder/        # OrderBuilder (GOF Builder)
├── factory/        # CartItemFactory (GOF Factory Method)
├── strategy/       # PasswordEncodingStrategy (GOF Strategy)
├── config/         # Configuration (Security, etc.)
└── exception/      # Custom exceptions & GlobalExceptionHandler

---

4. API Endpoints Reference

Base URL: http://localhost:8081
Swagger UI: http://localhost:8081/docs

4.1 User Endpoints

Method	Endpoint	Description
POST	/api/users/register	Register a new user
POST	/api/users/login	Login and get session ID

Register User

POST /api/users/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Response: 200 OK (empty body)
Error: 409 Conflict - {"error": "User already exists"}
Error: 400 Bad Request - Validation errors (field-level)

Login

POST /api/users/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Response: 200 OK
{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000"
}

Error: 401 Unauthorized - {"error": "Invalid credentials"}

---

4.2 Product Endpoints

Method	Endpoint	Description
GET	/api/products	Get all available products

Get All Products

GET /api/products

Response: 200 OK
[
  {
    "id": 1,
    "title": "Nail gun",
    "available": 8,
    "price": 23.95
  },
  ...
]

---

4.3 Cart Endpoints

All cart endpoints require the sessionId header (from login).

Method	Endpoint	Description	Auth
POST	/api/cart	Add item to cart	sessionId
GET	/api/cart	Get cart contents	sessionId
PUT	/api/cart	Modify cart item quantity	sessionId
DELETE	/api/cart/{position}	Remove cart item	sessionId

Add to Cart

POST /api/cart
Header: sessionId: <uuid-from-login>
Content-Type: application/json

{
  "id": 1,
  "quantity": 2
}

Response: 200 OK
Error: 400 Bad Request - {"error": "Insufficient stock"}
Error: 401 Unauthorized - {"error": "Session not found or expired"}

Get Cart

GET /api/cart
Header: sessionId: <uuid-from-login>

Response: 200 OK
{
  "items": [
    {
      "position": 1,
      "productName": "Nail gun",
      "quantity": 2,
      "subtotal": 47.90
    }
  ],
  "total": 47.90
}

Modify Cart Item

PUT /api/cart
Header: sessionId: <uuid-from-login>
Content-Type: application/json

{
  "position": 1,
  "quantity": 3
}

Response: 200 OK
Error: 400 Bad Request - Insufficient stock
Error: 404 Not Found - Invalid position

Remove Cart Item

DELETE /api/cart/1
Header: sessionId: <uuid-from-login>

Response: 200 OK
Error: 404 Not Found - {"error": "Cart item not found"}

---

4.4 Order Endpoints

Method	Endpoint	Description	Auth
POST	/api/orders/checkout	Checkout (create order from cart)	sessionId

Checkout

POST /api/orders/checkout
Header: sessionId: <uuid-from-login>

Response: 200 OK
{
  "id": 1,
  "date": "2026-03-02T10:30:00",
  "total": 47.90,
  "status": "CONFIRMED"
}

Error: 400 Bad Request - Empty cart or insufficient stock
Error: 401 Unauthorized - Session invalid/expired

---

4.5 Endpoint Summary Table

#	Method	Endpoint	Purpose
1	POST	/api/users/register	User registration
2	POST	/api/users/login	User login
3	GET	/api/products	List all products
4	POST	/api/cart	Add to cart
5	GET	/api/cart	Get cart
6	PUT	/api/cart	Modify cart item
7	DELETE	/api/cart/{position}	Remove cart item
8	POST	/api/orders/checkout	Checkout

---

5. Design Principles

This application follows design patterns and SOLID principles.

---

6. How It Works

6.1 Request Flow

HTTP Request
    │
    ▼
Controller (validates input, extracts sessionId if needed)
    │
    ▼
Service (business logic, calls repositories, SessionService)
    │
    ▼
Repository / SessionService (data access)
    │
    ▼
Response (DTO or void)

6.2 Session Management

• Storage: In-memory ConcurrentHashMap<UUID, Session>
• Session contents: userId, cart (list of CartItem), expirationTime
• Lifecycle:
  1. Created on successful login
  2. Validated on each cart/order request
  3. Expires after 30 minutes
  4. Cleared after checkout
• Thread safety: ConcurrentHashMap for concurrent access

6.3 Password Hashing

• Algorithm: BCrypt (Spring Security)
• Registration: Password hashed with passwordEncoder.encode() before storage
• Login: Verified with passwordEncoder.matches(rawPassword, storedHash)
• Security: Unique salt per password, one-way, timing-attack resistant

6.4 Checkout Flow (Transactional)

1. Validate session
2. Revalidate stock for all cart items
3. Create Order and OrderItem entities
4. Deduct inventory (within transaction)
5. Save order (within transaction)
6. Clear cart (after successful save)
7. If any step fails → transaction rolls back, cart unchanged

---

7. Configuration

7.1 Application Properties

Property	Value	Description
server.port	8081	HTTP server port
spring.datasource.url	jdbc:h2:mem:store_db	H2 in-memory DB
spring.jpa.hibernate.ddl-auto	create-drop	Schema recreate on startup
spring.h2.console.path	/h2-console	H2 console path
springdoc.swagger-ui.path	/docs	Swagger UI path

7.2 H2 Console Access

• URL: http://localhost:8081/h2-console
• JDBC URL: jdbc:h2:mem:store_db
• Username: sa
• Password: (empty)

8. Running & Testing

8.1 Build & Run

# Build
mvn clean install

# Run
mvn spring-boot:run

8.2 Sample Data (Auto-loaded)

Product	Available	Price
Nail gun	8	$23.95
Hammer	15	$12.50
Screwdriver set	20	$18.75
Drill	5	$89.99
Wrench set	12	$34.50

8.3 Testing

mvn test
mvn test jacoco:report   # With coverage report

Coverage report: target/site/jacoco/index.html

---

Quick Reference

Resource	URL/Path
API Base	http://localhost:8081
Swagger UI	http://localhost:8081/docs
H2 Console	http://localhost:8081/h2-console
Jacoco Report	target/site/jacoco/index.html