User Management System

A Spring Boot REST API for managing users, built as a solo assignment during my Full Stack internship at pulse by solution (fka Giza Systems).

The project focuses on implementing a clean layered backend structure, CRUD operations, input validation, business rules, centralized exception handling, and PostgreSQL persistence.

Features

Create, retrieve, update, and delete users
Retrieve all users or a specific user by UUID
Request validation using Jakarta Bean Validation
Unique email enforcement
User roles through USER and ADMIN types
Business rules for administrator accounts
Centralized exception handling
DTO-based request and response models
PostgreSQL persistence using Spring Data JPA
OpenAPI / Swagger support
Docker Compose configuration for PostgreSQL

Business Rules

The assignment includes several domain-specific validation rules:

User names must be between 3 and 50 characters
Users must provide a valid email address
User age must be between 18 and 100
Email addresses must be unique
Administrators must be at least 21 years old
The system allows a maximum of five administrators
Administrator accounts cannot be deleted

Architecture

The application follows a simple layered structure:

HTTP Request
    ↓
Controller
    ↓
Service
    ↓
Repository
    ↓
PostgreSQL

The main responsibilities are separated into:

controller/
    HTTP endpoints and response handling

service/
    application logic and business rules

repository/
    database access through Spring Data JPA

model/
    entities, DTOs, and enums

exception/
    domain exceptions and centralized error handling

API Endpoints

All user endpoints are available under:

/api/v1/users

Method	Endpoint	Description
`POST`	`/api/v1/users`	Create a new user
`GET`	`/api/v1/users`	Retrieve all users
`GET`	`/api/v1/users/{id}`	Retrieve a user by UUID
`PUT`	`/api/v1/users/{id}`	Update an existing user
`DELETE`	`/api/v1/users/{id}`	Delete a user

A successful delete returns 204 No Content, while user creation returns 201 Created.

Example Request

{
  "name": "Yousef El-Ghoul",
  "email": "[email protected]",
  "age": 23,
  "userType": "USER"
}

Example Response

{
  "id": "7e79fb82-f773-4bd6-91ca-cc0c27260a01",
  "name": "Yousef El-Ghoul",
  "email": "[email protected]",
  "age": 23,
  "userType": "USER"
}

Validation

The API validates incoming requests before passing them to the service layer.

Examples include:

name
- required
- minimum 3 characters
- maximum 50 characters

email
- required
- valid email format

age
- required
- minimum 18
- maximum 100

userType
- required

Additional business validation is performed in the service layer.

Exception Handling

The application defines custom exceptions for domain-specific failures, including:

user not found
duplicate email
administrator age violation
administrator limit exceeded
administrator deletion attempt

These exceptions are handled centrally through a global exception handler instead of duplicating error handling across controllers.

Tech Stack

Java 25
Spring Boot 4
Spring MVC
Spring Data JPA
PostgreSQL
Jakarta Bean Validation
Lombok
Springdoc OpenAPI
Maven
Docker Compose

Running Locally

Requirements

Java 25
Maven
Docker and Docker Compose

Start PostgreSQL

docker compose up -d

The Compose configuration starts a PostgreSQL instance on port 5432.

Start the Application

Run the application using Maven:

./mvnw spring-boot:run

The API will then be available through the application’s configured Spring Boot port.

Database

The application uses PostgreSQL for persistence.

The included Docker Compose configuration supports the following environment variables:

POSTGRES_DB
POSTGRES_USER
POSTGRES_PASSWORD

Default development values are provided in the Compose file and can be overridden through environment variables.

Internship Context

This project was completed independently as part of my Full Stack internship at pulse by solution (fka Giza Systems).

The assignment was used to practice and apply backend concepts including:

layered Spring Boot architecture
REST API design
DTO usage
input validation
business-rule enforcement
exception handling
persistence with JPA and PostgreSQL

Notes

This repository represents an internship learning assignment rather than a production-ready user-management or authentication platform.

Authentication, authorization, password management, migrations, production deployment, and other production concerns were outside the scope of this task.