MS Event Manager

Overview

MS Event Manager is a Spring Boot microservice designed for managing events within the Heiji Events ecosystem. This service provides comprehensive event management capabilities including creation, retrieval, updating, and soft deletion of events, with automatic address resolution through ZIP code integration and ticket management coordination.

Features

• Event Management: Full CRUD operations for events
• Address Integration: Automatic address resolution via Brazilian ZIP code (CEP) service
• Ticket Coordination: Integration with MS Ticket Manager for ticket validation
• Soft Delete: Events are soft-deleted to maintain data integrity
• Pagination Support: Paginated event listings
• Validation: Comprehensive input validation with custom error messages
• API Documentation: Swagger/OpenAPI 3.0 documentation
• Test Coverage: JaCoCo integration for code coverage reporting

Technology Stack

• Java 17
• Spring Boot 3.5.4
• Spring Data MongoDB
• Spring Cloud OpenFeign - For external service communication
• MongoDB - Primary database
• MapStruct - Object mapping
• Lombok - Boilerplate code reduction
• SpringDoc OpenAPI - API documentation
• JaCoCo - Code coverage
• Maven - Dependency management and build tool

Architecture

This microservice follows a layered architecture pattern:

├── Controller Layer    # REST endpoints and request handling
├── Service Layer      # Business logic and orchestration
├── Repository Layer   # Data access and persistence
├── Client Layer       # External service integration
├── DTO Layer         # Data transfer objects
├── Model Layer       # Domain entities
└── Exception Layer   # Custom exception handling

API Endpoints

Events API (/v1/events)

Method	Endpoint	Description
POST	/v1/events	Create a new event
GET	/v1/events/{id}	Get event by ID
GET	/v1/events	Get all events (paginated)
PUT	/v1/events/{id}	Update an existing event
DELETE	/v1/events/{id}	Soft delete an event

Request/Response Examples

Create Event

POST /v1/events
{
  "eventName": "Spring Conference 2025",
  "dateTime": "2025-12-15T14:00:00",
  "cep": "01310-100",
  "price": 299.99
}

Event Response

{
  "id": "64f5a1b2e4b0d1a2b3c4d5e6",
  "eventName": "Spring Conference 2025",
  "dateTime": "2025-12-15T14:00:00",
  "cep": "01310-100",
  "logradouro": "Avenida Paulista",
  "bairro": "Bela Vista",
  "cidade": "São Paulo",
  "uf": "SP",
  "price": 299.99,
  "deleted": false
}

Project Structure

src/
├── main/
│   ├── java/br/com/shiroshima/mseventmanager/
│   │   ├── MsEventManagerApplication.java     # Main application class
│   │   ├── client/                            # External service clients
│   │   │   ├── MsTicketManagerClient.java     # Ticket service integration
│   │   │   └── ZipCodeClient.java             # Address service integration
│   │   ├── configs/                           # Configuration classes
│   │   │   └── OpenAPIConfig.java             # Swagger configuration
│   │   ├── controller/                        # REST controllers
│   │   │   └── EventController.java           # Event endpoints
│   │   ├── dtos/                              # Data Transfer Objects
│   │   │   ├── AddressDTO.java
│   │   │   ├── EventCreateDTO.java
│   │   │   ├── EventEditDTO.java
│   │   │   ├── EventPageableDTO.java
│   │   │   └── EventResponseDTO.java
│   │   ├── exceptions/                        # Custom exceptions
│   │   │   ├── ApiExceptionManager.java
│   │   │   ├── ErrorMessage.java
│   │   │   ├── EventNotFoundException.java
│   │   │   └── EventWithPendingTicketsException.java
│   │   ├── mapper/                            # MapStruct mappers
│   │   │   └── EventMapper.java
│   │   ├── model/                             # Domain entities
│   │   │   └── Event.java
│   │   ├── openapi/                           # OpenAPI specifications
│   │   ├── repository/                        # Data repositories
│   │   └── service/                           # Business logic
│   │       └── EventService.java
│   └── resources/
│       ├── application.yml                    # Application configuration
│       ├── static/                            # Static resources
│       └── templates/                         # Template files
└── test/                                      # Test classes
    └── java/br/com/shiroshima/mseventmanager/
        ├── MsEventManagerApplicationTests.java
        ├── controller/                        # Controller tests
        ├── dtos/                              # DTO tests
        └── service/                           # Service tests

Configuration

Environment Variables

Variable	Default	Description
MONGO_URI	mongodb+srv://admin:admin@cluster0.bzpkqgg.mongodb.net/db_event?retryWrites=true&w=majority&appName=Cluster0?ssl=true&sslInvalidHostNameAllowed=true	MongoDB connection string
PORT	8081	Application server port
MS_TICKET_URL	http://localhost:8082/v1	MS Ticket Manager service URL

Application Configuration

The application uses application.yml for configuration:

spring:
  application:
    name: ms-event-manager
  data:
    mongodb:
      uri: ${MONGO_URI}
      authentication-database: admin

server:
  port: ${PORT:8081}

clients:
  ms-ticket-manager:
    url: ${MS_TICKET_URL:http://localhost:8082/v1}
  cep-service:
    url: https://viacep.com.br/ws

Getting Started

Prerequisites

• Java 17 or higher
• Maven 3.6+
• MongoDB instance (local or remote)

Installation

1. Clone the repository

   git clone https://github.com/heiji-events/ms-event-manager.git
   cd ms-event-manager

2. Set environment variables (optional)

   export MONGO_URI="your-mongodb-connection-string"
   export PORT="8081"
   export MS_TICKET_URL="http://localhost:8082/v1"

3. Build the project

   ./mvnw clean compile

4. Run tests

   ./mvnw test

5. Start the application

   ./mvnw spring-boot:run

API Documentation

Once the application is running, you can access the API documentation at:

• Swagger UI: http://localhost:8081/swagger-ui.html
• OpenAPI JSON: http://localhost:8081/v3/api-docs

Validation Rules

Event Creation/Update

• Event Name: 3-35 characters
• Date Time: Must be in the future
• CEP (ZIP Code): Brazilian format (12345-678 or 12345678)
• Price: Positive number or zero, max 6 digits with 2 decimal places

External Dependencies

ViaCEP Service

• Purpose: Brazilian ZIP code to address resolution
• URL: https://viacep.com.br/ws
• Format: GET /{zipCode}/json

MS Ticket Manager

• Purpose: Ticket management integration
• Default URL: http://localhost:8082/v1
• Endpoint: GET /tickets/with-event-id/{id}

Development

Code Quality Tools

• JaCoCo: Code coverage reporting
• MapStruct: Compile-time object mapping
• Lombok: Reduces boilerplate code
• Spring Boot DevTools: Hot reloading during development

Building and Testing

# Compile the project
./mvnw compile

# Run all tests
./mvnw test

# Generate code coverage report
./mvnw jacoco:report

# Package the application
./mvnw package

# Run with specific profile
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

Changelog

Version 0.0.1-SNAPSHOT

• Initial release
• Basic CRUD operations for events
• ZIP code address integration
• Ticket manager integration
• Soft delete functionality
• Comprehensive validation
• API documentation with Swagger