Event Management System 🎉

A RESTful API built with Spring Boot for managing events with comprehensive validation, exception handling, and real-time data persistence.

---

📋 Table of Contents

• Overview
• Features
• Tech Stack
• Getting Started
• API Endpoints
• Project Structure
• Validation Rules
• Error Handling
• Database
• API Documentation

---

Overview

This Event Management System provides a robust backend API for creating, retrieving, and filtering events. Built with Spring Boot 3.2.0 and Java 17, it demonstrates best practices in REST API design, data validation, and exception handling.

Key Highlights:

• ✅ Bean validation with custom annotations
• ✅ Global exception handling with meaningful error responses
• ✅ JPA repository pattern with custom queries
• ✅ H2 in-memory database for rapid development
• ✅ Swagger/OpenAPI documentation
• ✅ RESTful API design principles

---

Features

Core Functionality

• Create Events - Add new events with validation
• Retrieve Events - Get all events, by ID, or by registration code
• Filter Events - Search events by category (sorted by capacity)
• Data Validation - Comprehensive input validation with custom constraints
• Exception Handling - Centralized error handling with detailed messages

Business Rules

• Event dates must be in the future
• Registration codes follow pattern: EVT-XXXX
• Capacity must be a positive number
• All fields are mandatory and validated

---

Tech Stack

Technology	Version	Purpose
Java	17	Programming language
Spring Boot	3.2.0	Application framework
Spring Data JPA	3.2.0	Data persistence
H2 Database	Runtime	In-memory database
Spring Validation	3.2.0	Bean validation
SpringDoc OpenAPI	2.3.0	API documentation
Maven	-	Build tool

---

Getting Started

Prerequisites

• Java 17 or higher
• Maven 3.6+

Installation

1. Clone the repository

git clone https://github.com/idlefor/EventManagement.git
cd EventManagement

2. Build the project

mvn clean install

3. Run the application

mvn spring-boot:run

The application will start on http://localhost:8080

Quick Test

# Create an event
curl -X POST http://localhost:8080/api/events \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Conference 2024",
    "category": "Technology",
    "capacity": 500,
    "eventDate": "2024-12-15",
    "registrationCode": "EVT-1001"
  }'

---

API Endpoints

Base URL

http://localhost:8080/api/events

Endpoints

Method	Endpoint	Description	Request Body
POST	/	Create a new event	Event JSON
GET	/	Get all events	-
GET	/{id}	Get event by ID	-
GET	/code/{code}	Get event by registration code	-
GET	/filter?category={category}	Filter events by category	-

Request/Response Examples

Create Event

Request:

POST /api/events
Content-Type: application/json

{
  "name": "Spring Boot Workshop",
  "category": "Technology",
  "capacity": 100,
  "eventDate": "2024-06-20",
  "registrationCode": "EVT-2024"
}

Response: 201 Created

{
  "id": 1,
  "name": "Spring Boot Workshop",
  "category": "Technology",
  "capacity": 100,
  "eventDate": "2024-06-20",
  "registrationCode": "EVT-2024"
}

Get All Events

Request:

GET /api/events

Response: 200 OK

[
  {
    "id": 1,
    "name": "Spring Boot Workshop",
    "category": "Technology",
    "capacity": 100,
    "eventDate": "2024-06-20",
    "registrationCode": "EVT-2024"
  }
]

Filter by Category

Request:

GET /api/events/filter?category=Technology

Response: 200 OK (sorted by capacity descending)

[
  {
    "id": 2,
    "name": "Tech Conference",
    "category": "Technology",
    "capacity": 500,
    "eventDate": "2024-12-15",
    "registrationCode": "EVT-1001"
  },
  {
    "id": 1,
    "name": "Spring Boot Workshop",
    "category": "Technology",
    "capacity": 100,
    "eventDate": "2024-06-20",
    "registrationCode": "EVT-2024"
  }
]

---

Project Structure

EventManagement/
├── src/
│   ├── main/
│   │   ├── java/com/sample/event/
│   │   │   ├── controller/
│   │   │   │   └── EventController.java       # REST endpoints
│   │   │   ├── model/
│   │   │   │   └── Event.java                 # Entity class
│   │   │   ├── repository/
│   │   │   │   └── EventRepository.java       # JPA repository
│   │   │   ├── service/
│   │   │   │   └── EventService.java          # Business logic
│   │   │   ├── exception/
│   │   │   │   ├── GlobalExceptionHandler.java
│   │   │   │   ├── NoEventsFoundException.java
│   │   │   │   └── ResourceNotFoundException.java
│   │   │   ├── validation/
│   │   │   │   └── FutureDate.java            # Custom validator
│   │   │   └── EventApplication.java          # Main class
│   │   └── resources/
│   │       └── application.properties          # Configuration
│   └── test/
├── pom.xml
└── README.md

---

Validation Rules

The system enforces the following validation constraints:

Field	Validation	Error Message
name	@NotBlank	"Name is mandatory"
category	@NotBlank	"Category is mandatory"
capacity	@Positive	"Capacity must be positive"
eventDate	@FutureDate	"Event date must be in future"
registrationCode	@Pattern(EVT-\d{4})	"Code must match EVT-XXXX"

Custom Validation: @FutureDate

A custom annotation that ensures event dates are always in the future:

@FutureDate
private LocalDate eventDate;

This prevents creating events with past dates, maintaining data integrity.

---

Error Handling

The application uses centralized exception handling with meaningful HTTP status codes:

Exception Types

Exception	HTTP Status	When It Occurs
NoEventsFoundException	400 Bad Request	No events match the criteria
ResourceNotFoundException	404 Not Found	Event not found by ID or code
MethodArgumentNotValidException	400 Bad Request	Validation failure

Error Response Format

Validation Error:

{
  "name": "Name is mandatory",
  "capacity": "Capacity must be positive",
  "registrationCode": "Code must match EVT-XXXX"
}

Resource Not Found:

"Event not found with id: 999"

---

Database

H2 In-Memory Database

The application uses H2 for development and testing:

Database Console:

• URL: http://localhost:8080/h2-console
• JDBC URL: jdbc:h2:mem:eventdb
• Username: sa
• Password: password

Schema

CREATE TABLE events (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    category VARCHAR(255) NOT NULL,
    capacity INTEGER NOT NULL,
    event_date DATE NOT NULL,
    registration_code VARCHAR(255) NOT NULL
);

Repository Queries

Custom JPA queries implemented:

• findAllByCategoryOrderByCapacityDesc(String category)
• findByRegistrationCode(String code)
• findByName(String name)

---

API Documentation

Swagger UI

Access interactive API documentation at:

http://localhost:8080/swagger-ui.html

OpenAPI Spec

Raw OpenAPI specification available at:

http://localhost:8080/v3/api-docs

---

Development

Running Tests

mvn test

Build JAR

mvn clean package

The executable JAR will be created in target/EventManagement-1.0-SNAPSHOT.jar

Run JAR

java -jar target/EventManagement-1.0-SNAPSHOT.jar

---

Configuration

Key configuration properties in application.properties:

# H2 Console
spring.h2.console.enabled=true
spring.h2.console.path=/h2-console

# Database
spring.datasource.url=jdbc:h2:mem:eventdb
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

# Swagger
springdoc.swagger-ui.path=/swagger-ui.html


## Future Enhancements

- [ ] User authentication and authorization
- [ ] Event registration/attendance tracking
- [ ] Email notifications
- [ ] File upload for event images
- [ ] Search by date range
- [ ] Pagination for large result sets
- [ ] PostgreSQL/MySQL support for production
- [ ] Dockerization
- [ ] CI/CD pipeline