GATHER

A full-stack event management application built with Spring Boot, Angular, and Keycloak for authentication. Users can browse events by city and continent, create and manage events, participate in events, and more.

📖 Overview

GATHER is a modern, full-featured Event Management web application designed to connect event organizers with attendees. The platform enables users to discover events based on categories (Music, Learn, Create, Connect, Chill), browse events by geographic location (continents and cities), and participate in events that match their interests.

Key Highlights:

🎯 Smart Event Discovery: Browse events by category vibes (Music, Learn, Create, Connect, Chill) with intelligent tagging system
🌍 Geographic Exploration: Discover events organized by continents and cities with interactive maps powered by Leaflet
🔐 Secure Authentication: OAuth2/OIDC authentication via Keycloak with support for social login (Google, GitHub)
📝 Rich Event Creation: Create events with Markdown-supported descriptions, custom posters, tags, and flexible locations (physical or virtual)
👥 Event Participation: Join events, track participation status (pending, joined, cancelled), and view attendee lists
📱 Responsive Design: Modern, mobile-friendly UI built with Tailwind CSS

User Journey:

Landing Page: Visitors are greeted with trending events and category cards showcasing different event vibes
Authentication: Users can sign in via Keycloak (with optional Google/GitHub OAuth)
Home Dashboard: Authenticated users see featured events, trending events, and personalized recommendations
Event Discovery: Browse events by category tags or explore by continent → city → specific events
Event Details: View comprehensive event information including location maps, organizer details, and participation options
Event Creation: Organizers can create events with rich descriptions, poster uploads, pricing, and capacity limits
Profile Management: Users can view their hosted events, attended events, and manage participation status
Event Participation: Request to join events, track approval status, and cancel participation

The application uses a modern tech stack with Spring Boot 3.5 backend, Angular 20 frontend, MySQL database, and Flyway migrations for database versioning. Security is handled through Keycloak integration with JWT tokens, and the platform supports both physical and virtual events with integrated mapping capabilities.

� Features

User Authentication: Secure OAuth2/OIDC authentication via Keycloak
Event Management: Create, update, and delete events with rich text descriptions
Geographic Organization: Browse events by continent and city
Live Event Status: Real-time indication of ongoing events
Event Participation: Users can register and participate in events
User Profiles: Manage user profiles with avatars
Responsive Design: Modern UI with Tailwind CSS
Bilingual Support: English and French localization

🏗️ Tech Stack

Backend

Java 17
Spring Boot 3.5.7
Spring Security with OAuth2 Resource Server
Spring Data JPA with Hibernate
MySQL 8 database
Flyway for database migrations
Keycloak for authentication and authorization
Lombok for boilerplate reduction
Maven for dependency management

Frontend

Angular 20.3.0 (Standalone Components)
TypeScript
Tailwind CSS for styling
Keycloak Angular 20.0.0 for auth integration
Leaflet for maps
Marked for Markdown rendering
Angular Material & CDK

📋 Prerequisites

Before you begin, ensure you have the following installed:

Java Development Kit (JDK) 17 or higher
Node.js 18+ and npm
MySQL 8.0+
Keycloak 26+ (or use Docker)
Maven 3.6+ (or use the included wrapper)
Git

⚙️ Setup Instructions

1. Clone the Repository

git clone https://github.com/chaymaa09/Event_Management_Project.git
cd Event_Management_Project

2. Database Setup

Docker Approach

The docker-compose.yml automatically creates a fresh MySQL database:

docker-compose up -d

Database Initialization Flow:

Docker creates MySQL container with empty event-management database
When backend starts, Flyway migrations automatically run (V1-V8):
- Creates all tables (events, users, cities, continents, participations, etc.)
- Seeds initial data (continents and cities)
You can then create events through the UI

Import Pre-Populated Database (Optional)

If you want to use the database with sample events already created, import the backup:

# Make sure MySQL container is running
docker-compose up -d

# Import the database backup
mysql -u root -p -h localhost -P 3306 event-management < database-backup/latest.sql

When prompted, enter the password: root

Manual Database Setup

If not using Docker, create the database manually:

mysql -u root -p

CREATE DATABASE IF NOT EXISTS `event-management`;
EXIT;

The application uses Flyway for database migrations, which will automatically create and populate tables on first run.

3. Keycloak Setup

Option A: Using Docker (Recommended)

docker run -d \
  --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.2.2 \
  start-dev

Option B: Manual Installation

Download Keycloak from keycloak.org
Extract and run: bin/kc.sh start-dev (Linux/Mac) or bin\kc.bat start-dev (Windows)
Access Keycloak at http://localhost:8080
Login with admin/admin

Configure Keycloak Realm

Create a new realm named event-management-realm
Create a client named event-management-client:
- Client authentication: OFF (public client)
- Standard flow: ENABLED
- Direct access grants: ENABLED
- Valid redirect URIs: http://localhost:4200/*
- Web origins: http://localhost:4200
Create users for testing in the realm

Configure OAuth Providers (Optional)

To enable social login with Google and GitHub:

Get OAuth Credentials:
- Google OAuth Console
- GitHub OAuth Apps

Add to .env file (copy from .env.example):

GOOGLE_CLIENT_ID=your-google-client-id-here.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret-here
GITHUB_CLIENT_ID=your-github-client-id-here
GITHUB_CLIENT_SECRET=your-github-client-secret-here

In Keycloak Admin Console:
- Go to Realm → Identity Providers
- Add "Google" provider (add credentials)
- Add "GitHub" provider (add credentials)
- Map user attributes as needed
- Update client redirect URIs to include social provider callbacks
Frontend will automatically show social login buttons on the login page

4. Backend Setup

Navigate to the backend directory:

cd EventMangementProject

Update Application Properties

Ensure src/main/resources/application.properties has correct Keycloak settings:

spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:8080/realms/event-management-realm

keycloak.admin.server-url=http://localhost:8080
keycloak.admin.admin-realm=master
keycloak.admin.target-realm=event-management-realm
keycloak.admin.client-id=admin-cli
keycloak.admin.username=admin
keycloak.admin.password=admin

Build and Run

Using Maven wrapper (recommended):

# Windows
mvnw.cmd clean install
mvnw.cmd spring-boot:run

# Linux/Mac
./mvnw clean install
./mvnw spring-boot:run

Or using installed Maven:

mvn clean install
mvn spring-boot:run

The backend will start on http://localhost:8081

5. Frontend Setup

Open a new terminal and navigate to the frontend directory:

cd event-management-frontend

Install Dependencies

npm install

Update Keycloak Configuration

Ensure src/app/app.config.ts has the correct Keycloak settings:

{
  config: {
    url: 'http://localhost:8080',
    realm: 'event-management-realm',
    clientId: 'event-management-client'
  },
  initOptions: {
    onLoad: 'check-sso',
    silentCheckSsoRedirectUri: window.location.origin + '/assets/silent-check-sso.html'
  }
}

Run Development Server

npm start

The frontend will start on http://localhost:4200

🐳 Docker Setup

Docker Compose configuration for running the entire stack (MySQL, Keycloak, Backend, Frontend).

Using Docker Compose (Recommended)

docker-compose up -d

This will start:

MySQL on port 3306
Keycloak on port 8080

Then follow steps 4-5 above to run backend and frontend.

Docker Commands

# Start services
docker-compose up -d

# View logs
docker-compose logs -f keycloak
docker-compose logs -f mysql

# Stop services
docker-compose down

# Clean everything (including data)
docker-compose down -v

📁 Project Structure

Event_Management_Project/
├── EventMangementProject/          # Spring Boot Backend
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/com/example/eventmanagementproject/
│   │   │   │   ├── domain/         # Entity models
│   │   │   │   ├── dto/            # Data Transfer Objects
│   │   │   │   ├── repository/     # JPA Repositories
│   │   │   │   ├── service/        # Business logic
│   │   │   │   ├── web/            # REST Controllers
│   │   │   │   └── security/       # Security configuration
│   │   │   └── resources/
│   │   │       ├── application.properties
│   │   │       └── db/migration/   # Flyway migrations
│   │   └── test/
│   └── pom.xml
│
└── event-management-frontend/      # Angular Frontend
    ├── src/
    │   ├── app/
    │   │   ├── components/         # Reusable components
    │   │   ├── pages/              # Page components
    │   │   ├── services/           # API services
    │   │   ├── guards/             # Route guards
    │   │   ├── interceptors/       # HTTP interceptors
    │   │   └── models/             # TypeScript models
    │   ├── assets/
    │   └── environments/
    ├── angular.json
    ├── package.json
    └── tailwind.config.js

🔌 API Endpoints

Authentication

All endpoints require Bearer JWT token (except public endpoints)

Events

GET /api/events - Get all events
GET /api/events/{id} - Get event by ID
GET /api/events/city/{cityName} - Get events by city (case-insensitive)
POST /api/events - Create new event (authenticated)
PUT /api/events/{id} - Update event (authenticated, owner only)
DELETE /api/events/{id} - Delete event (authenticated, owner only)

Cities & Continents

GET /api/continents - Get all continents
GET /api/cities/{continent} - Get cities by continent with event counts
GET /api/cities/name/{cityName} - Get city details by name

Users

GET /api/users/me - Get current user profile
PUT /api/users/me - Update current user profile
DELETE /api/users/me - Delete current user account

Participation

POST /api/participations - Register for event
DELETE /api/participations/{id} - Cancel participation
GET /api/participations/event/{eventId} - Get participants for event
GET /api/participations/user/{userId} - Get user's participations

🎨 Key Features Details

Event Creation

Users can create events with:

Title, description (Markdown supported), and category
Date, time, and duration
Location (city, address, or virtual)
Maximum participants and pricing
Tags for better discoverability
Event poster image upload

City & Continent Browsing

Browse continents with event counts
View cities grouped by continent
City detail pages show all events in that city
Dynamic map integration using Leaflet

User Authentication Flow

Users access the platform
Click "Sign In" redirects to Keycloak login
After authentication, JWT token is stored
Token is automatically attached to API requests
Protected routes require valid authentication

🔧 Development

Backend Development

cd EventMangementProject
./mvnw spring-boot:run

Hot reload is enabled via Spring Boot DevTools.

Frontend Development

cd event-management-frontend
npm start

Angular dev server supports hot module replacement.

Database Migrations

Create new Flyway migration in src/main/resources/db/migration/:

V{version}__Description.sql

Example: V9__Add_event_rating.sql

🧪 Testing

Backend Tests

cd EventMangementProject
./mvnw test

Frontend Tests

cd event-management-frontend
npm test

📝 Environment Variables

Backend (application.properties)

spring.datasource.url - MySQL connection URL
spring.datasource.username - Database username
spring.datasource.password - Database password
spring.security.oauth2.resourceserver.jwt.issuer-uri - Keycloak realm URL
keycloak.admin.* - Keycloak admin configuration
app.user-avatar-dir - Directory for user avatar uploads

Frontend (environment.ts)

Keycloak URL, realm, and client ID are configured in app.config.ts

OAuth Configuration (.env file)

Copy .env.example to .env and add your credentials:

GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Important: .env is in .gitignore and should NEVER be committed to git for security.

🐛 Troubleshooting

Backend won't start

Ensure MySQL is running and accessible
Check database credentials in application.properties
Verify Keycloak is running and accessible at http://localhost:8080
Check port 8081 is not already in use

Frontend shows CORS errors

Verify backend is running on port 8081
Check proxy.conf.json configuration
Ensure Keycloak web origins includes http://localhost:4200

Authentication fails

Verify Keycloak realm and client configuration
Check issuer-uri matches your Keycloak setup
Ensure redirect URIs are correctly configured in Keycloak client

Database migration errors

Check Flyway migration files for syntax errors
Verify database connection in application.properties
You can reset database with: source reset-database.sql (use carefully!)

👥 Contributors

📄 License

This project is created for educational purposes as part of JEE course.

🙏 Acknowledgments

Spring Boot for the excellent backend framework
Angular team for the powerful frontend framework
Keycloak for authentication and authorization
Tailwind CSS for styling utilities

FilesExpand file tree

README.md

Latest commit

History