Customer Management System

A lightweight, full-stack business management platform built with Spring Boot & PrimeFaces.

---

What is CMS?

Customer Management System (CMS) is a self-hosted, multi-entity business management tool designed for small to medium organizations. It ships a ready-to-use web UI and a JSON REST API to manage clients, contacts, and custom analytics dashboards — all from a single deployable JAR.

Key capabilities:

• 📋 Entity management — full CRUD for clients, persons, industries, types, and countries
• 📊 Custom dashboards — define SQL-backed bar, horizontal-bar, and pie charts through the admin UI; no code changes required
• 🔒 Built-in authentication — Spring Security login with BCrypt-hashed passwords
• 🔗 Dual interface — every feature is accessible via both the PrimeFaces web UI and the REST API simultaneously
• 📤 Data export — one-click XLS, CSV, and XML export on every list view

---

Table of Contents

1. Architecture
2. Getting Started
3. REST API Examples
4. Built With
5. Contributing
6. Versioning
7. Authors
8. License
9. Donation

---

Architecture

The application exposes two parallel interaction layers backed by the same Spring beans:

┌──────────────────────────────────────────────────────────────┐
│                         Client Layer                         │
│   Browser (JSF / PrimeFaces UI)  │  REST client / cURL       │
└───────────────┬──────────────────┴──────────────┬────────────┘
                │  Facelets / EL                  │  JSON HTTP
┌───────────────▼─────────────────────────────────▼────────────┐
│            Controller Layer  (@RestController + @ManagedBean) │
│   PersonController · UnitController · DashboardController    │
│              AbstractController<T>  (CRUD base)              │
└────────────────────────────┬─────────────────────────────────┘
                             │
┌────────────────────────────▼─────────────────────────────────┐
│            Service Layer  (AbstractService<T>)               │
│      JPQL findByName  ·  CrudRepository delegation           │
└────────────────────────────┬─────────────────────────────────┘
                             │
┌────────────────────────────▼─────────────────────────────────┐
│          Repository Layer  (Spring Data CrudRepository)      │
└────────────────────────────┬─────────────────────────────────┘
                             │
                    PostgreSQL  /  MySQL

Key design constraint: AbstractController derives entity class names at runtime via ParameterizedType reflection. The Java entity class name must match the .xhtml file prefix — e.g. Person → personList.xhtml, personView.xhtml. Violating this breaks both JSF navigation and JPQL queries.

---

Getting Started

Prerequisites

Requirement	Version
Java (JDK)	1.8
Maven	3.x
PostgreSQL or MySQL	9.6+ / 5.7+

1 · Clone the repository

git clone https://github.com/your-org/customer-management-system.git
cd customer-management-system

2 · Set up the database

CREATE DATABASE cms;

Seed reference data by running all .sql files in src/main/resources/:

# PostgreSQL example
psql -U postgres -d cms -f src/main/resources/chart_type.sql
psql -U postgres -d cms -f src/main/resources/country.sql
psql -U postgres -d cms -f src/main/resources/data.sql
psql -U postgres -d cms -f src/main/resources/first_name.sql
psql -U postgres -d cms -f src/main/resources/last_name.sql
psql -U postgres -d cms -f src/main/resources/unit_industry.sql
psql -U postgres -d cms -f src/main/resources/unit_type.sql

MySQL 8.0.4+ only:

ALTER USER '${USER}'@'localhost' IDENTIFIED WITH mysql_native_password BY '${PASSWORD}';

To switch to MySQL, edit src/main/resources/application.properties — comment out the PostgreSQL block and uncomment the MySQL block.

3 · Build & run

mvn clean compile package
java -jar target/customer-management-system-0.0.2-SNAPSHOT.jar

The application starts at http://localhost:8081/cms

Credential	Value
Username	admin
Password	123

---

REST API Examples

All entity endpoints follow the same convention: /{entityName} maps to full CRUD. The surface is identical for every entity (/unit, /dashboard, /country, etc.).

Create a person — POST /person

Request

POST http://localhost:8081/cms/person
Content-Type: application/json

{
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1-555-0100",
  "notes": "Key contact for Acme Corp"
}

Response 200 OK

{
  "id": 42,
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1-555-0100",
  "notes": "Key contact for Acme Corp",
  "createdDate": "2026-03-29T10:00:00.000+0000",
  "endDate": null
}

List all persons — GET /person

Request

GET http://localhost:8081/cms/person

Response 200 OK

[
  {
    "id": 42,
    "name": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1-555-0100",
    "createdDate": "2026-03-29T10:00:00.000+0000",
    "endDate": null
  }
]

Register a new user — POST /api/user/register

POST http://localhost:8081/cms/api/user/register
Content-Type: application/json

{
  "username": "alice",
  "password": "s3cur3p@ss"
}

The password is automatically BCrypt-hashed before storage. To generate a hash manually, run SecurityConfig.main() in src/main/java/com/cms/configs/SecurityConfig.java.

Common REST verbs

Method	Path	Description
GET	/{entity}	List all records
GET	/{entity}/{id}	Fetch a single record
POST	/{entity}	Create a new record
PUT	/{entity}	Update an existing record
DELETE	/{entity}/{id}	Delete a record

---

Built With

Technology	Purpose
Spring Boot 1.5.x	Application framework & embedded Tomcat
JoinFaces / PrimeFaces	JSF component library & UI widgets
Spring Data JPA	Repository abstraction over JPA / Hibernate
Spring Security	Authentication & authorization
PostgreSQL / MySQL	Relational database (switchable via config)
Apache POI	XLS / XLSX data export
iText	PDF generation
Lombok	Boilerplate reduction (security models & DTOs)
Maven	Build & dependency management

---

Contributing

Please read CONTRIBUTING.md for details on the code of conduct and the process for submitting pull requests.

---

Versioning

This project uses SemVer for versioning. For available releases, see the tags on this repository.

---

Authors

• Sergiu Drahnea — Initial work — LinkedIn

---

License

This project is licensed under the MIT License — see the LICENSE.md file for details.

---

Donation

If this project saved you time, consider a ☕ donation via PayPal. Any contribution is warmly appreciated!