🏆 Hackathon Management System

A Clean Architecture backend for managing the entire hackathon lifecycle

Modular • Testable • Extensible • Event-driven

Overview

Hackathon Management System is a backend platform designed to manage realistic hackathon scenarios from creation to winner assignment.

The system supports multiple actors and workflows, including:

• Hackathon administration
• Team management
• Project submissions
• Evaluation processes
• Winner selection
• Support requests
• User moderation
• Notifications
• External service integrations

The architecture follows Clean Architecture to keep business rules independent from technical implementations.

---

Features

🏆 Hackathon Management

• Create and manage hackathons
• Configure schedules and lifecycle states
• Assign managers and staff members

Team Management

• Create teams
• Invite members
• Participate in hackathons

Project Submissions

• Submit projects
• Evaluate submissions
• Select winners using business policies

Support & Moderation

• Open support requests
• Track request lifecycle
• Report users and moderation issues

Notifications

• Automatic event-driven notifications
• User communication workflows

External Integrations

• Calendar services
• Payment providers

---

Architecture

The project follows Clean Architecture.

core            → business domain and rules
application     → use cases and orchestration
infrastructure  → technical implementations
presentation    → REST API layer

Project Structure

application/
├── ports/
│   ├── repositories/
│   └── strategies/
├── services/
├── scheduler/
├── factory/
├── listeners/
└── config/

core/
├── entities/
├── enums/
├── events/
├── state/
└── policies/

infrastructure/
├── jpa/repositories/
└── strategies/

presentation/
├── controller/
├── dto/
├── mapper/
└── error/

---

Domain Model

Main entities:

• Hackathon
• User
• Manager
• StaffMember
• Team
• TeamParticipation
• Submission
• Notification
• SupportRequest
• StaffAssignment
• ModerationReport

---

Design Patterns

Strategy Pattern

Used for external service integrations.

Strategies:

• CalendarStrategy
• PaymentStrategy

Implementations:

• Google Calendar
• PayPal

---

Builder Pattern

Used to create hackathons.

Components:

• HackathonBuilder
• HackathonBuilderDirector

---

State Pattern

Used to manage lifecycle transitions without large conditional blocks.

Applied to:

• Support requests
• User accounts

Examples:

SupportRequest:
Open → In Progress → Resolved / Rejected

Account:
Active → Suspended → Revoked

Components:

• SupportRequestLifecycleStateMachine
• AccountLifecycleStateMachine
• StateRegistry

Each state encapsulates its own allowed transitions.

---

Observer Pattern (Spring Events)

Used to decouple business actions from secondary reactions such as notifications.

Components:

• DomainEventPublisher
• SpringDomainEventPublisher
• NotificationDomainEventListener

Observed events:

• TeamCreatedEvent
• TeamDeletedEvent
• TeamMemberAddedEvent
• UserSuspendedEvent
• WinnerPrizePaidEvent
• HackathonConcludedEvent
• SupportRequestCreatedEvent
• SupportRequestAcceptedEvent
• SupportRequestRejectedEvent

Spring automatically manages event subscription and dispatching.

---

Requirements

• JDK 21
• Maven or Maven Wrapper

Verify installation:

java -version
./mvnw -v

---

Installation

git clone <repository-url>

cd HackathonManagementSystem

./mvnw clean compile

---

Run Application

Start Spring Boot:

./mvnw spring-boot:run

Build executable JAR:

./mvnw clean package

java -jar target/Progetto_IdS_Hackathon-0.0.1-SNAPSHOT.jar

---

API Documentation

Swagger UI:

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

OpenAPI JSON:

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

---

Database

Default configuration:

URL: jdbc:h2:file:~/hackathon-db;AUTO_SERVER=TRUE

Username: sa

Password: (empty)

Development setup:

• Database is recreated at every startup
• Automatic seed execution
• Database file stored in:

~/hackathon-db.mv.db

---

Testable Clock

The application uses a centralized Clock.

Modes:

System Clock

app.clock.mode=SYSTEM
app.clock.zone=Europe/Rome

Fixed Clock

app.clock.mode=FIXED
app.clock.zone=Europe/Rome
app.clock.fixed-instant=2026-04-10T10:00:00Z

Useful for:

• deterministic tests
• lifecycle simulations
• scheduler demonstrations

---

Scheduler

Available jobs:

app.scheduler.hackathon-lifecycle-cron=0 */5 * * * *

app.scheduler.team-invitation-expiration-cron=0 */10 * * * *

---

Web Interface

Frontend:

https://marvelous-cajeta-1a68ff.netlify.app/

Running Frontend + Backend

1. Start the backend:

./mvnw spring-boot:run

2. Open the frontend.

3. Allow browser access to local services when prompted.

4. The frontend will connect to:

http://localhost:8080

---

Authors

• Matteo Vittori
• Alejandro Innocenzi

---

License

MIT License