E-Commerce Complaint Tracker (Spring Data JPA)

Overview

This repository contains a structured, domain-driven implementation of an E-Commerce Complaint Tracking System, purpose-built to showcase comprehensive mastery over Spring Data JPA. The project demonstrates expertise with entity modeling, associations, repository design, derived queries, service-layer workflows, validation constraints, and real-world complaint lifecycle management.

This project does not include any web or controller layers at this stage. The focus is strictly on Spring Data JPA concepts, domain logic, and end-to-end service workflows. A presentation/API layer will be incorporated after completing the Spring MVC module.

---

Key Objectives

• Demonstrate full proficiency in Spring Data JPA core and advanced topics.
• Build realistic domain entities that mirror a real-world e-commerce complaint system.
• Implement complex business workflows such as complaint creation, agent assignment, SLA calculation, refund resolution, comment handling, and status transitions.
• Show practical application of JPA relationships, cascading, timestamps, validation, and repository query capabilities.

---

Domain Summary

The system models an internal customer support workflow for managing product-related complaints raised against specific orders and order items.

Core Features

• Customers may raise complaints tied to specific orders and order items.
• Complaints are auto-assigned to support agents via a round-robin algorithm.
• SLA deadlines are computed based on priority derived from complaint categories.
• Agents manage complaint lifecycles: OPEN → IN_PROGRESS → RESOLVED → CLOSED.
• Refund requirements and statuses are handled independently of complaint statuses.
• Both customers and agents can add comments to communicate context.
• Full validation ensures ownership, authorization, and state integrity.

---

Technologies Used

• Java 21
• Spring Boot 3.x
• Spring Data JPA
• Hibernate ORM
• PostgreSQL
• Maven
• Lombok

---

Entity Model

The domain uses clean, expressive entity classes with well-defined JPA mappings.

Entities

• Customer: Basic profile with relationship to orders and complaints.
• Agent: Support representatives assigned to complaints.
• Product: Catalog items purchased via orders.
• Order: Business transactions tied to customers.
• OrderItem: Line items of an order with saved product snapshot.
• Complaint: Central domain object for managing reported issues.
• Comment: Immutable communication logs from customers or agents.

Relationship Summary

• Customer ↔ Orders (1:N)
• Order ↔ OrderItems (1:N)
• Customer ↔ Complaints (1:N)
• Agent ↔ Complaints (1:N)
• Complaint ↔ Comments (1:N)
• Complaint ↔ Order (M:1)
• Complaint ↔ OrderItem (M:1)

All relationships include field-level constraints and bidirectional integrity.

---

Enums & Business Rules

The system relies heavily on enums to support strict workflow rules.

ComplaintCategory

• Predefined categories with embedded priority mapping.
• Each category carries a default priority used during complaint creation.

Priority

• LOW, MEDIUM, HIGH, URGENT
• Used in SLA calculations.

ComplaintStatus

• OPEN → IN_PROGRESS → RESOLVED → CLOSED
• Enforced strictly by service logic.

RefundStatus

• NOT_REQUIRED, PENDING, PROCESSED, FAILED
• Managed independently of complaint status.

OrderStatus & ProductCategory

• Standard e-commerce representations.

---

Repository Layer

Each aggregate root has a repository extending JpaRepository, with selective derived queries:

• ComplaintRepository includes:

  • findByCustomerId(Long id)
  • findByAssignedAgentId(Long id)

These enable clean service-layer operations without custom JPQL.

---

Service Layer & Business Workflows

The system contains multiple services orchestrating domain rules.

1. Agent Assignment Service

• Implements round-robin agent assignment.
• Ensures fair load distribution.

2. SLA Service

• Calculates complaint resolution deadline based on priority.
• Defined in hours (e.g., URGENT: 12 hours).

3. Complaint Creation Service

Handles:

• Customer/order validation
• Order item association
• Auto-priority assignment
• Timestamp management
• SLA calculation
• Agent assignment
• Refund defaults

This is the most comprehensive domain workflow.

4. Complaint Query Service

Provides filtered access:

• Complaints by customer
• Complaints by agent
• Individual complaint access with strict ownership validation
• All complaints for administrative inspection

5. Comment Creation Service

Allows customers and agents to add comments with validation:

• Ownership/authorization checks
• Immutable comment design
• Linked to complaint and actor

6. Complaint Status Update Service

Supports lifecycle transitions:

• OPEN → IN_PROGRESS
• IN_PROGRESS → RESOLVED
• RESOLVED → CLOSED

Invalid transitions are prevented and timestamp updates are applied.

7. Refund Resolution Service

Manages refund-specific logic:

• Marking a complaint as requiring refund
• Updating refund status
• Tracking refunded date

---

Validation & Error Handling

Services enforce strict domain rules:

• Missing resources trigger runtime exceptions.
• Ownership checks prevent unauthorized actions.
• Invalid transitions produce business-rule violations.
• Empty comments or invalid refund updates are rejected.

This ensures consistent and predictable behavior.

---

Project Structure

src/main/java/org/chandra/ecommercecomplainttracker
 ├── bootstrap/
 ├── config/
 ├── domain/
 │    ├── entities/
 │    └── enums/
 ├── repository/
 ├── service/
 │    └── impl/
 └── util/

This high-level structure segregates domain modeling, data access, and business logic without introducing premature layers.

---

Database

Backed by PostgreSQL, with schema auto-generated via Hibernate.

Key configurations:

• spring.jpa.hibernate.ddl-auto=update
• spring.jpa.show-sql=true
• PostgreSQL driver & dialect

All tables, relationships, and constraints have been validated through application startup.

---

Demonstration Plan (Post-MVC)

Once Spring MVC is integrated:

• REST endpoints or a console UI will be added.
• Consumers (customers, agents) can trigger full workflows.
• Project becomes fully interactive for portfolio and interviews.

---

Future Enhancements

• Add Spring MVC controller layer.
• Introduce DTO mapping for cleaner API boundaries.
• Add exception handlers via @ControllerAdvice.
• Incorporate pagination, sorting, and specification queries.
• Add test coverage using Spring Boot Test.
• Add audit events using JPA lifecycle annotations.

---

Purpose of This Repository

This project is intentionally scoped to show-case Spring Data JPA mastery. It is not intended as a production-ready application but as a clear demonstration of:

• Complex domain modeling
• Clean service-layer design
• Real-world business workflows
• Effective usage of Spring Data JPA capabilities

The next phase (Spring MVC integration) will convert this into a fully interactive and demonstrable system.

---

Author

Chandra Sekhar

A structured and practical implementation reflecting advanced understanding of Spring Data JPA and domain-driven backend design.