This project is a Pigeon Racing Management System designed to help loft owners and administrators manage pigeons, lofts, and competitions effectively. The system utilizes Domain-Driven Design (DDD), following best practices to ensure a scalable, maintainable, and secure application.
- Project Overview
- Features
- Architecture and Technologies
- Domain Concepts
- Domain Events
- Bounded Contexts
- Aggregate Roots
- Endpoints
- Getting Started
The Pigeon Racing Management System is built for pigeon racing enthusiasts and administrators to register pigeons, manage lofts, organize competitions, and calculate and view competition results. The system supports role-based access control with Loft Owners and Administrators, providing tailored functionalities for each role.
- Register New Pigeon: Loft owners can register a pigeon by providing details like leg band number, gender, age, and color.
- View and Update Pigeon Details: Loft owners can view a list of pigeons in their loft, update their details, or delete them if necessary.
- Register New Loft: Loft owners can register a loft with unique details including GPS coordinates.
- Manage Lofts: Administrators can view, update, or delete lofts as needed.
- Create Competition: Administrators can create new competitions with a name, GPS release point, date, and distance.
- Assign Pigeons to Competitions: Administrators can add pigeons to competitions by leg band number. Loft owners can view and confirm the participation of their pigeons.
- Close Competition: Competitions can be closed after pigeons have returned to their lofts.
- Upload Results: Administrators can upload arrival times and leg band numbers for each pigeon in a competition.
- Calculate and View Results: The system calculates distance, speed, and points for each pigeon. Results are accessible to loft owners and administrators.
- Export Results: Results can be exported as PDFs for external use.
- User Registration and Login: Loft owners and administrators can securely register and log in.
- Role-Based Access Control: Access is tailored based on user roles for secure and organized functionality.
The application adheres to Domain-Driven Design (DDD) principles and implements:
- Spring Data MongoDB: For seamless data persistence in a NoSQL database.
- Spring IoC: For dependency injection and management of the application’s components.
- Spring MVC: To create RESTful web services.
- Spring REST Controller Advice: For consistent exception handling across the application.
- JUnit and Mockito: For writing unit tests and mocking dependencies.
- MapStruct: For mapping between domain entities and DTOs
- RESTful API: All interactions are based on REST APIs.
- Exception Handling: Custom exception handling using
@RestControllerAdvice. - Security: Role-based access and data protection with Spring Security.
- Responsive Design: Accessible on both mobile and desktop.
The main domain concepts in this system include:
- Pigeon
- Attributes:
Pigeon ID,Leg Band Number,Gender,Age,Color,Image (optional).
- Attributes:
- Loft
- Attributes:
Loft ID,Name,Owner,GPS Coordinates.
- Attributes:
- Competition
- Attributes:
Competition ID,Name,Release Point GPS Coordinates,Date and Time,Distance.
- Attributes:
- Competition Result
- Attributes:
Competition Result ID,Pigeon ID,Arrival Time,Distance Traveled,Flight Speed,Competition Points.
- Attributes:
The system’s domain events include:
- PigeonRegisteredEvent
- CompetitionCreatedEvent
- PigeonAddedToCompetitionEvent
- CompetitionClosedEvent
- CompetitionResultsCalculatedEvent
- CompetitionResultsViewedEvent
- Pigeon Management: Handles all operations related to pigeons.
- Loft Management: Manages lofts and associated details.
- Competition Management: Manages creation, assignment, and closure of competitions.
- Results Management: Handles result calculation, storage, and display.
- Pigeon
- Loft
- Competition
- Result
Below are some key REST endpoints for each module:
- POST
/api/auth/register: Register a new user. - POST
/api/auth/login: User login.
- POST
/api/pigeons: Register a new pigeon. - GET
/api/pigeons: List pigeons in a loft. - PUT
/api/pigeons/{pigeonId}: Update pigeon details. - DELETE
/api/pigeons/{pigeonId}: Delete a pigeon.
- POST
/api/lofts: Register a new loft. - GET
/api/lofts: List all lofts (admin). - PUT
/api/lofts/{loftId}: Update loft details (admin). - DELETE
/api/lofts/{loftId}: Delete a loft (admin).
- POST
/api/competitions: Create a new competition (admin). - POST
/api/competitions/{competitionId}/pigeons: Add pigeons to competition (admin). - PUT
/api/competitions/{competitionId}/close: Close a competition (admin).
- POST
/api/results/upload: Upload competition data (admin). - GET
/api/results/{competitionId}: View competition results. - GET
/api/results/{competitionId}/export: Export results as PDF.
- Java 21
- MongoDB
- Maven
-
Clone the repository:
git clone https://github.com/yourusername/pigeon-management-system.git cd pigeon-management-system -
Set up MongoDB and configure
application.properties:spring.data.mongodb.uri=mongodb://localhost:27017/pigeon_db -
Install dependencies and run the application:
mvn install mvn spring-boot:run
-
Access the API documentation: Visit
http://localhost:8080/swagger-ui/for API documentation and testing.
This system is designed with growth and flexibility in mind, ensuring clean code and modular components for easy maintenance. It leverages Spring IoC for dependency management, with each feature following RESTful principles for scalable and efficient interactions.
For further questions or contributions, feel free to open an issue or submit a pull request.
(link jira)[https://bouananisfn.atlassian.net/jira/software/projects/PIG/boards/39]