*Built with Java 21 · JavaFX 21 · H2/MySQL *
- Project Overview
- Architecture
- Tech Stack
- Modules
- Database Schema
- External Integrations
- Getting Started
- Configuration
- Screenshots
- Team
VoyagePlatform is a desktop travel management application developed as an academic project at ESPRIT (Tunisia). It provides a complete ecosystem for managing travel services — from transport booking and guided tours to accommodation reservations, destination discovery, and AI-powered travel recommendations.
The application supports two distinct user roles:
| Role | Access |
|---|---|
| 🛡️ Admin | Full dashboard: manage users, transports, destinations, tours, guides, accommodations, recommendations, and reservations |
| 👤 Client | Browse tours & transport, make reservations, submit feedback, receive recommendations |
| 🧭 Guide | Personal dashboard: manage availability, view bookings, chat with clients, access AI analytics |
VoyagePlatform uses a hybrid architecture — combining direct database access with external REST API consumption:
┌──────────────────────────────────────────────────────────┐
│ JavaFX Desktop Client │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │ Controllers │ │ Services │ │ Entities │ │
│ │ (FXML/UI) │──│ (Business) │──│ (Data Model) │ │
│ └──────────────┘ └──────┬───────┘ └───────────────┘ │
│ │ │
│ ┌────────────────┴────────────────┐ │
│ │ │ │
│ ┌──────▼──────┐ ┌────────▼───────┐ │
│ │ Direct JDBC │ │ HTTP REST API │ │
│ │ H2/MySQL │ │ (OkHttp/Gson) │ │
│ └──────┬──────┘ └────────┬───────┘ │
└───────────│─────────────────────────────────│────────────┘
│ │
┌────────▼────────┐ ┌────────▼────────┐
│ H2 Embedded DB │ │ Symfony 6 API │
│ (voyage_ │ │ (XAMPP/MySQL) │
│ platform.db) │ │ :8000 │
└─────────────────┘ └─────────────────┘
Modules using direct JDBC (H2/MySQL):
- Destinations, Recommendations & Feedback, Reservations, Users (admin CRUD), Accommodations
Modules consuming Symfony REST API:
- Transport (
/api/transports), Guides (/BackOffice/guide/api), Tours (/BackOffice/tour/api)
| Technology | Version | Purpose |
|---|---|---|
| Java | 21 | Primary language |
| JavaFX | 21 | Desktop UI framework |
| Apache Maven | 3.11 | Build & dependency management |
| H2 Database | 2.2.224 | Embedded database (primary) |
| MySQL Connector/J | 8.0.33 | MySQL support (optional) |
| Library | Purpose |
|---|---|
| ControlsFX 11.2.1 | Extended JavaFX controls |
| Ikonli 12.3.1 | Icon packs for JavaFX |
| BootstrapFX 0.4.0 | Bootstrap-style CSS for JavaFX |
| ValidatorFX 0.6.1 | Form validation |
| JavaFX WebView | Embedded HTML (map picker, chat) |
| JavaFX Media | Audio/video support |
| Library | Purpose |
|---|---|
| OkHttp 4.12.0 | HTTP client for API calls |
| Gson 2.10.1 | JSON serialization/deserialization |
| org.json 20231013 | JSON utilities |
| Jsoup 1.17.2 | HTML/web scraping (price scraper) |
| Library | Purpose |
|---|---|
| jBCrypt 0.4 | Password hashing |
| Stripe Java 24.3.0 | Payment processing |
| javax.mail / jakarta.mail | Email (SMTP / password reset) |
Controllers: LoginController, RegisterController, UserManagementController, UserFormController, ForgotPasswordController, UserHomeController
Service: UserService
- Authentication — Login with role-based redirect (Admin / Client / Guide). Hardcoded admin fallback for offline demonstration.
- Registration — New user creation with email uniqueness validation.
- Admin Panel — Full CRUD on users with search by name, email, or phone.
- Password Reset — Email-based reset via Gmail SMTP with SSL.
- Role Management — Stored as JSON arrays (
["ROLE_ADMIN"],["ROLE_USER"]). - Dynamic Column Detection —
UserServiceauto-detects schema variations (roles/role,password/mot_de_passe) for cross-environment compatibility. - Email Validation — Format and uniqueness checks before persisting.
users (id, email, roles, password, nom, prenom, tel, created_at, updated_at)
Controllers: TransportController, TransportFormController, TransportDetailController, TransportClientController, TransportClientDetail, ReservationFormController
Service: TransportService, TransportValidator, ReservationService
- REST API Consumer — Reads transport data from a Symfony backend (
/api/transports). Write operations (create/update/delete) are delegated to the web back-office. - Client Browsing — Filterable, searchable transport list with type, price range, and route filters.
- Transport Detail — Full details view with schedule information and booking option.
- Statistics Dashboard — Count by type, price distribution charts.
- Schedule Management —
TransportScheduleentities with departure/arrival times and seat tracking. - Validation —
TransportValidatorenforces business rules (non-negative prices, seat limits, etc.) - Image Support — Images stored locally in
uploads/transports/with lazy loading viaImageCellFactory.
transport (id, type, company_name, departure_city, arrival_city,
price, duration_minutes, available_seats, image_url, status)
transport_schedule (id, transport_id, departure_time, arrival_time,
available_seats, status)
Controllers: DestinationsListController, DestinationFormController, MapPickerController
Service: DestinationService, WeatherService
- Full CRUD — Create, read, update, delete destinations with auto-generated SEO slugs.
- Image Management — Upload destination cover images stored in
src/main/resources/images/destinations/, timestamped to avoid conflicts. - Map Picker — Embedded Leaflet.js map inside a
WebView(map_picker.html) to pick precise GPS coordinates (latitude/longitude) for each destination. - Weather Integration — Real-time weather data via
WeatherService(external weather API). - Country Tracking — Destinations tagged with country for filtering.
- Slug Generation — Automatic URL-safe slug from the destination name.
destination (id, name, slug, country, description, image_name,
latitude, longitude, created_at, updated_at)
Controllers: GuideController, GuideDashboardController, GuideDashboardHomeController, GuideLoginController, GuideProfileController, GuideAvailabilityController, GuideBookingsController, GuideChatController, GuideAIStatsController, TourController, DashboardTourController, CategoryController, ScheduleAdminController, ClientTourListController, ClientTourDetailController, BookingDialog, ScheduleDialog, StatsDialog
Services: GuideService, TourService, BookingTourService, GuideAvailabilityService, ScheduleService, TourPhotoService, TourViewService, CategoryService
Guide Portal:
- Dedicated Login — Separate authentication flow for guides (
GuideSessionManager). - Guide Dashboard — Home overview with bookings, availability calendar, and earnings.
- Profile Management — Edit bio, languages, photo, contact info.
- Availability Management — Set available date/time slots with max group size.
- Booking Management — View and manage client bookings; confirm or decline.
- AI-Powered Stats —
GuideAIStatsController— AI-driven tour performance analytics. - Chat — Real-time chat interface between guides and clients (
GuideChatController).
Tour Management (Admin):
- REST API Consumer — Reads tours from Symfony (
/BackOffice/tour/api). - Categories — Tours organized into categories (Adventure, Culture, Luxury) with price ranges.
- Tour Scheduling — Admin-managed schedules with status workflow (
PENDING→APPROVED/REJECTED), meeting points, guide notes. - Photo Gallery — Multiple photos per tour (
TourPhoto). - View Tracking —
TourViewrecords every view for analytics. - Statistics — Most-viewed, most-booked, trending tours.
Client Tour Experience:
- Tour Listing — Filterable by category, price, location.
- Tour Detail — Full description, photos, guide profile, available schedules.
- Booking — Client booking dialog with traveler info, group size, total price calculation.
- Checkout — Stripe-integrated payment flow.
guide (id, first_name, last_name, email, phone, photo, bio, languages)
tour (id, title, description, price, duration, location, lat, lng,
views, guide_id, category_id, image_path)
tour_category (id, name, min_price, max_price)
tour_schedule (id, tour_id, guide_id, schedule_date, start_time,
end_time, max_participants, status, meeting_point)
booking_tour (id, tour_id, guide_id, traveler_name, traveler_email,
number_of_people, total_price, status)
guide_availability (id, guide_id, date, start_time, end_time,
max_people, is_available)
Controllers: RecommendationListController, RecommendationFormController, RecommendationEditController, RecommendationFeedbackController, FeedbackAdminController, RecomAdminController
Services: RecommendationService, RecommendationFeedbackService, BadWordService, SpellCheckService
Recommendations:
- Admin CRUD — Create, edit, delete destination recommendations with a 0–100 score.
- Score Engine — Dynamic score adjustment:
score = 50 + (likes × 10) − (dislikes × 10), clamped to [0, 100]. - Destination Linking — Each recommendation links to a destination with country info.
- Client View — Browsable recommendation cards with live scores.
Feedback System:
- Like / Dislike — Clients react to recommendations; reactions persist per user.
- Comment Submission — Free-text comments linked to recommendations.
- Moderation — Admin approves/rejects feedback with moderation reasons.
- Bad Word Filter —
BadWordServiceauto-screens submitted comments for inappropriate content. - Spell Check —
SpellCheckServicevalidates comment text quality. - Admin Dashboard —
FeedbackAdminController/RecomAdminController— aggregate view of all feedback with approve/reject actions. - Notifications —
AdminNotificationtable for flagged content alerts.
recommendation (id, destination_id, score, reason, created_at)
recommendation_feedback (id, liked, comment, approved,
moderation_reason, recommendation_id, user_id)
admin_notification (id, message, type, is_read, created_at)
Controllers: ReservationController, ReservationFormController, ClientBookingController, ClientDashboardController, AccommodationFormController, AccommodationsListController, RoomFormController, RoomsListController, VoucherFormController, VouchersListController, StatisticsDashboardController
Services: ReservationService, ReservationValidator, AccommodationService, AccommodationReservationService, RoomService, VoucherCodeService, AmenityService, AccommodationAmenityService, StripeService
Trip Reservations:
- Full CRUD — Create, update, cancel reservations tied to trips (
Voyage). - Duplicate Detection — Prevents double-booking for the same trip/date/person count.
- Multi-Payment Methods — Carte Bancaire, PayPal, Stripe integration.
- Status Workflow —
pending→confirmed→cancelled. - Revenue Stats — Total reservations count and revenue summary.
- Search & Filter — Filter by status keyword.
Accommodation Reservations:
- Hotel/Resort/Apartment Management — Admin CRUD for accommodations with GPS coordinates, images, city/destination linking.
- Room Management — Per-accommodation room types, capacities, amenities, availability status.
- Amenity System — Predefined amenities (WiFi, Pool, Spa, etc.) linked to accommodations via junction table.
- Voucher/Discount Codes — Apply
VoucherCodediscounts at checkout (value, expiry, active flag). - Reservation Code — Unique alphanumeric booking reference per accommodation reservation.
- Stripe Payment —
StripeServicehandles card payment for premium bookings. - Statistics Dashboard — Visual charts for occupancy, revenue, room type breakdown.
- Client Checkout — Full checkout flow with guest details, special requests, and final price calculation.
trip (id, destination, price, devise_cible, start_date, end_date)
reservation (id, trip_id, date_reservation, nb_persons,
total_price, payment_method, status, user_id)
accommodation (id, name, type, address, city, price,
latitude, longitude, destination_id, status)
room (id, accommodation_id, room_number, room_type,
price, capacity, amenities, is_available)
voucher_code (id, code, value, is_active, expiry_date)
accommodation_reservation (id, reservation_code, accommodation_id,
room_id, check_in, check_out,
total_price, final_price, voucher_code_id)
The database contains 20 tables across all modules:
users ← User accounts & roles
trip ← Travel packages
destination ← Travel destinations
guide ← Guide profiles
tour_category ← Tour classification
tour ← Tour listings
tour_schedule ← Tour session scheduling
tour_photo ← Tour image gallery
tour_view ← Analytics: view tracking
guide_availability ← Guide calendar slots
booking_tour ← Client tour bookings
transport ← Transport listings
transport_schedule ← Departure/arrival schedules
reservation ← Trip reservations
recommendation ← AI/admin recommendations
recommendation_feedback ← Client reactions & comments
admin_notification ← Moderation alerts
accommodation ← Hotels/resorts/apartments
room ← Rooms per accommodation
voucher_code ← Discount codes
amenity ← Accommodation amenities
accommodation_amenity ← Amenity junction table
accommodation_reservation ← Accommodation bookings
Database is initialized automatically on first launch via SchemaInitializer.init() using schema.sql. Seed data (sample users, destinations, tours, etc.) is included.
| Service | Usage | Config Key |
|---|---|---|
| Symfony REST API | Transport, Guide & Tour data (read) | http://[::1]:8000 |
| Stripe | Tour & accommodation payments | StripeService.java |
| Gmail SMTP | Password reset emails | mail.smtp.* in config.properties |
| Weather API | Real-time weather per destination | WeatherService.java |
| Leaflet.js (WebView) | Interactive map for GPS picking | html/map_picker.html |
| Jsoup (PriceScraper) | Live price comparison scraping | PriceScraperService.java |
| Speech Recognition | Voice input support | SpeechRecognitionService.java |
| Text-to-Speech | Audio output for accessibility | SpeechService.java |
| Claude / AI | Guide analytics & recommendations | ApiService.java |
| Requirement | Version |
|---|---|
| Java JDK | 21+ |
| Apache Maven | 3.8+ |
| (Optional) XAMPP | For Symfony back-office features |
git clone https://github.com/your-org/VoyagePlatform-JavaFX.git
cd VoyagePlatform-JavaFXCopy and edit the configuration file:
cp src/main/resources/config.example.properties src/main/resources/config.propertiesEdit config.properties (see Configuration section below).
# Using Maven Wrapper (recommended)
./mvnw javafx:run # Linux/macOS
mvnw.cmd javafx:run # Windows
# Or standard Maven
mvn javafx:runThe database is auto-initialized on first launch — no manual SQL import required.
| Role | Password | |
|---|---|---|
| Admin | admin@trava.com |
admin |
| Client | client@test.tn |
123456 |
| Guide | siouarkhalfaoui@gmail.com |
guide123 |
⚠️ The admin account uses a hardcoded offline fallback for demonstration. SeeUserService.authenticate().
Edit src/main/resources/config.properties:
# ── Database (H2 Embedded — works out of the box) ──────────────
db.url=jdbc:h2:./data/voyage_platform;MODE=MySQL;DATABASE_TO_LOWER=TRUE;NON_KEYWORDS=VALUE
db.username=sa
db.password=
# ── Database (MySQL — uncomment when XAMPP is running) ─────────
# db.url=jdbc:mysql://127.0.0.1:3306/voyage_platform
# db.username=root
# db.password=
# ── Email / Password Reset (Gmail SMTP) ────────────────────────
mail.smtp.host=smtp.gmail.com
mail.smtp.port=465
mail.smtp.username=YOUR_GMAIL@gmail.com
mail.smtp.password=YOUR_APP_PASSWORD
mail.smtp.ssl.enable=true
mail.from=YOUR_GMAIL@gmail.com
# ── Symfony API Backend (for Transport/Guide/Tour) ─────────────
# Start XAMPP and the Symfony server at http://[::1]:8000
# If offline, the JavaFX app falls back to H2 seed data💡 Gmail App Passwords: Go to Google Account → Security → 2-Step Verification → App Passwords, and generate a 16-character app password.
Split-panel design with a travel photo backdrop and role-based redirect on login.
Full tour CRUD with integrated Leaflet.js map showing tour locations in real time.
High-level KPIs: total tours, active tours, guides count, average price, tours by category, status donut chart, and price range distribution.
Personalized guide home with monthly booking chart, revenue KPIs, and AI-generated smart suggestions.
AI-powered analytics: total views, conversion rate, average booking value, trend analysis chart (views vs bookings), and booking status pie chart.
Client-facing transport detail page showing flight info, price, duration, capacity, and description — with a "Réserver ce transport" CTA.
Full booking flow: traveler info, date/time selection, group size spinner, and Stripe payment section — with live total calculation.
This project was developed by a team of 6 students at ESPRIT School of Engineering, Tunisia, as part of the Java Desktop Development module.
| Module | Developer |
|---|---|
| 👤 User Management | (your name) |
| 🚌 Transport | (your name) |
| 🗺️ Destinations | (your name) |
| 🧭 Guides & Tours | Siouar Khalfaoui |
| ⭐ Recommendations & Feedback | (your name) |
| 📋 Reservations & Accommodations | (your name) |
VoyagePlatform-JavaFX/
├── src/main/java/tn/esprit/
│ ├── MainApp.java # Application entry point
│ ├── controllers/ # JavaFX Controllers (UI logic)
│ ├── entities/ # JPA-style entity classes
│ ├── services/ # Business logic & data access
│ └── utils/ # Helpers (DB, Email, Stripe, etc.)
├── src/main/resources/
│ ├── tn/esprit/ # FXML view files
│ │ ├── views/ # Guide & Tour views
│ │ ├── fxml/ # Accommodation & Map views
│ │ ├── styles/ # CSS stylesheets
│ │ └── *.fxml # Core module views
│ ├── html/map_picker.html # Leaflet.js map for GPS picking
│ ├── schema.sql # Database DDL + seed data
│ └── config.properties # App configuration (gitignored)
├── data/
│ └── voyage_platform.mv.db # H2 embedded database file
├── uploads/
│ └── transports/ # Uploaded transport images
├── exports_voyage/
│ └── Catalogue_Voyages.txt # Exported voyage catalogue
├── pom.xml # Maven build configuration
└── README.md
- The application ships with seed data for all modules — no setup required for demonstration.
- The Symfony REST API back-office is required only for Transport, Guide, and Tour write operations. All modules remain functional in read-only mode using the embedded H2 database.
- H2 Console is available at
jdbc:h2:./data/voyage_platformfor direct database inspection during development. - Crash logs are written to
crash_log.txtin the project root if the application fails to start.
Developed at ESPRIT School of Engineering · Tunisia · 2024–2025