Store Management System

A production-ready RESTful API for managing store operations — inventory, sales orders, purchase orders, customers, suppliers, and user authentication.

Tech Stack

Component	Technology
Language	Java 17
Framework	Spring Boot 3.4.1
Security	Spring Security + JWT (jjwt 0.12.6)
Database	PostgreSQL (prod), H2 (dev)
Migrations	Flyway
ORM	Spring Data JPA / Hibernate 6
Mapping	MapStruct 1.6.3
Documentation	OpenAPI 3 / Swagger UI (springdoc 2.7.0)
Build	Maven
Monitoring	Spring Actuator

Prerequisites

• JDK 17+
• Maven 3.8+
• PostgreSQL 16+ (for postgresql / prod profiles)

Quick Start (Development)

# Run with H2 in-memory database (no setup required)
mvn spring-boot:run "-Dspring-boot.run.profiles=dev"

The app starts at http://localhost:8080.

Default Admin Credentials

Username	Password	Role
admin	admin123	ROLE_ADMIN

Profiles

Profile	Database	Flyway	Use Case
dev (default)	H2 in-memory (create-drop)	Disabled	Local development
postgresql	PostgreSQL (localhost:5432/store_db)	Enabled	Local PostgreSQL
prod	PostgreSQL (env-configured)	Enabled	Production

PostgreSQL Setup

# Ensure PostgreSQL is running, then create the database:
createdb -U postgres store_db

# Run with PostgreSQL profile:
mvn spring-boot:run "-Dspring-boot.run.profiles=postgresql"

API Endpoints

Authentication (/api/v1/auth)

Method	Path	Auth	Description
POST	/api/v1/auth/login	Public	Login, returns JWT
POST	/api/v1/auth/register	Public	Register new STAFF user
GET	/api/v1/auth/me	Authenticated	Get current user profile

Products (/api/v1/products)

Method	Path	Auth	Description
GET	/api/v1/products	Public	List products (paginated)
GET	/api/v1/products/{id}	Public	Get product by ID
GET	/api/v1/products/search?q=	Public	Search products by name
GET	/api/v1/products/low-stock	Public	Low stock alert
POST	/api/v1/products	ADMIN, MANAGER	Create product
PUT	/api/v1/products/{id}	ADMIN, MANAGER	Update product
DELETE	/api/v1/products/{id}	ADMIN	Delete product

Categories (/api/v1/categories)

Method	Path	Auth	Description
GET	/api/v1/categories	Public	List root categories
GET	/api/v1/categories/{id}	Public	Get category by ID
POST	/api/v1/categories	ADMIN, MANAGER	Create category
PUT	/api/v1/categories/{id}	ADMIN, MANAGER	Update category
DELETE	/api/v1/categories/{id}	ADMIN	Delete category

Customers (/api/v1/customers)

Method	Path	Auth	Description
GET	/api/v1/customers	Public	List customers
GET	/api/v1/customers/{id}	Public	Get customer by ID
POST	/api/v1/customers	ADMIN, MANAGER	Create customer
PUT	/api/v1/customers/{id}	ADMIN, MANAGER	Update customer
DELETE	/api/v1/customers/{id}	ADMIN	Delete customer

Suppliers (/api/v1/suppliers)

Method	Path	Auth	Description
GET	/api/v1/suppliers	Public	List suppliers
GET	/api/v1/suppliers/{id}	Public	Get supplier by ID
POST	/api/v1/suppliers	ADMIN, MANAGER	Create supplier
PUT	/api/v1/suppliers/{id}	ADMIN, MANAGER	Update supplier
DELETE	/api/v1/suppliers/{id}	ADMIN	Delete supplier

Inventory (/api/v1/inventory)

Method	Path	Auth	Description
GET	/api/v1/inventory	ADMIN, MANAGER, STAFF	List inventory
GET	/api/v1/inventory/product/{productId}	Public	Get inventory by product
PUT	/api/v1/inventory/product/{productId}	ADMIN, MANAGER	Update quantities
POST	/api/v1/inventory/product/{productId}/adjust	ADMIN, MANAGER	Adjust stock
POST	/api/v1/inventory/product/{productId}/count	ADMIN, MANAGER	Physical count

Sales Orders (/api/v1/sales-orders)

Method	Path	Auth	Description
GET	/api/v1/sales-orders	Public	List sales orders
GET	/api/v1/sales-orders/{id}	Public	Get sales order
POST	/api/v1/sales-orders	ADMIN, MANAGER, STAFF	Create order
POST	/api/v1/sales-orders/{id}/status	ADMIN, MANAGER	Update status

Purchase Orders (/api/v1/purchase-orders)

Method	Path	Auth	Description
GET	/api/v1/purchase-orders	ADMIN, MANAGER	List purchase orders
GET	/api/v1/purchase-orders/{id}	ADMIN, MANAGER	Get purchase order
POST	/api/v1/purchase-orders	ADMIN, MANAGER	Create purchase order
POST	/api/v1/purchase-orders/{id}/status	ADMIN	Update status

Users (/api/v1/users)

Method	Path	Auth	Description
GET	/api/v1/users	ADMIN	List users
GET	/api/v1/users/{id}	ADMIN	Get user
POST	/api/v1/users/{id}/toggle-enabled	ADMIN	Enable/disable user

Dashboard (/api/v1/dashboard)

Method	Path	Auth	Description
GET	/api/v1/dashboard	Authenticated	Dashboard summary

Authentication Flow

1. Login: POST /api/v1/auth/login with { "username": "admin", "password": "admin123" }
2. Response: Returns a JWT access token (24h expiry)
3. Authenticate: Include token in request header: Authorization: Bearer <token>

Role Hierarchy

• ROLE_ADMIN — Full access (manage users, all CRUD, status changes)
• ROLE_MANAGER — Operational access (CRUD products, customers, suppliers, orders)
• ROLE_STAFF — Limited access (create sales orders, view inventory)

API Documentation

Once running, visit:

• Swagger UI: http://localhost:8080/api/swagger-ui.html
• OpenAPI spec: http://localhost:8080/v3/api-docs
• Health check: http://localhost:8080/actuator/health

Project Structure

src/main/java/com/store/
├── audit/              # JPA auditing
├── config/             # Security, CORS, OpenAPI, JPA config
├── controller/         # REST controllers
├── dto/
│   ├── request/        # Incoming DTOs
│   └── response/       # Outgoing DTOs
├── entity/             # JPA entities
├── enums/              # Enumerations
├── exception/          # Custom exceptions + handler
├── mapper/             # MapStruct mappers
├── repository/         # Spring Data JPA repositories
├── security/           # JWT provider, filter, UserDetailsService
└── service/            # Business logic layer

Database

Dev (H2)

• Console: http://localhost:8080/h2-console
• JDBC URL: jdbc:h2:mem:store_db (username: sa, password: empty)
• Schema auto-created by Hibernate (ddl-auto: create-drop)

PostgreSQL

• Schema managed by Flyway migrations
• db/migration/V1__initial_schema.sql — Tables and indexes
• db/migration/V2__seed_data.sql — Default roles and admin user

Seed Data

Flyway seeds (PostgreSQL profiles):

• Roles: ROLE_ADMIN, ROLE_MANAGER, ROLE_STAFF
• Admin user: admin / admin123
• Default admin assigned ROLE_ADMIN

Build

# Build (skip tests)
mvn clean package -DskipTests

# Run tests
mvn test

# Build with PostgreSQL profile
mvn clean package -DskipTests -Ppostgresql