Skip to content
BranchesTags

Repository files navigation

TravelXP Logo

TravelXP — Travel Like a Pro

A feature-rich JavaFX desktop travel platform for browsing properties, planning trips, booking accommodations, and engaging with a vibrant travel community — powered by AI, real-time maps, and gamification.

Java 25 JavaFX 25 Maven MySQL Stripe Gemini AI OpenCV

20 Controllers 24 Services 14 Models 8 Repositories 10 Utilities 25 Views 7 APIs

Table of Contents

Overview

TravelXP is a comprehensive desktop travel management application built with JavaFX and Maven. It provides a complete ecosystem for travelers to discover accommodations, plan multi-destination trips, manage bookings with dynamic pricing, and interact with an AI-powered assistant — all within a modern, themeable UI.

The platform supports two roles — User and Admin — each with tailored dashboards and capabilities.

Highlights at a Glance

🔐 3-Layer Auth

Password + Face ID + TOTP 2FA

🤖 AI Assistant

Gemini 2.5 Flash Chatbot

💰 Smart Pricing

Season · Demand · Discounts

🏆 Gamification

XP · Levels · 12+ Titles

🗺️ Geolocation

Geocoding + Route Planning

💳 Stripe Payments

Checkout + Wallet System

🌍 Multi-language

Auto-detect & Translate 10 langs

🎨 Themes

Dark / Light with smooth transitions

Features

Authentication & Security

  • Email/Password Login with BCrypt-hashed credentials
  • Face ID Login — biometric authentication using OpenCV (LBPH face recognition via webcam)
  • TOTP Two-Factor Authentication — RFC 6238 compliant, compatible with Google Authenticator and Authy (QR code setup via ZXing)
  • Password Management — secure password change flow
  • Session Management — persistent user sessions across views

Trip Planning

  • Full CRUD for trips with origin, destination, dates, budget, and status tracking (PLANNED → ONGOING → COMPLETED / CANCELLED)
  • Trip Participation — join or leave public trips; participant tracking
  • Activity Management — add activities (with type, date, cost, status) linked to trips
  • Trip Milestones — track progress landmarks within a trip
  • XP Rewards — earn experience points for completing activities

Property & Accommodation

  • Browse and manage properties with detailed listings (type, address, city, country, bedrooms, bathrooms, max guests, price/night, images)
  • Geolocation — automatic lat/long resolution with Nominatim (OpenStreetMap) geocoding
  • Property Recommendations — smart suggestions highlighting properties with active offers ≥ 30% discount
  • Offers System — time-bound discount offers on properties

Booking Engine

  • Complete booking flow with date selection, guest count, and extra services
  • Dynamic Pricing Engine with transparent breakdowns:
    • Seasonal multipliers (Peak Summer ×1.30, Winter Holiday ×1.25, Shoulder ×1.10, Off-Peak ×0.90)
    • Demand-based pricing (high demand ×1.20, medium ×1.10)
    • Extra guest surcharges ($15/night per guest beyond 2)
    • Length-of-stay discounts (weekly 10%, monthly 20%)
  • Cancellation Policy Engine — tiered refund system (100% within 24h, 50% if > 3 days out, 0% otherwise)
  • Email Confirmations — automated booking, cancellation, and modification emails via SMTP

Payments & Wallet

  • Stripe Checkout integration for secure online payments
  • In-app Wallet — balance management with top-up (via Stripe) and automatic deductions on booking
  • Currency Exchange — live conversion rates from ExchangeRate-API for any ISO 4217 currency pair

AI-Powered Features

  • Gemini AI Chat Assistant — Google Gemini 2.5 Flash-powered chatbot with full platform knowledge, multi-turn conversation support, and contextual guidance
  • Trip AI Assistant — generates personalized trip-specific advice based on route, dates, and budget
  • Sentiment Analysis — automatic keyword-based scoring (POSITIVE / NEGATIVE / NEUTRAL) on user feedback

Communication

  • Real-time Messaging — 1-to-1 conversations between users, optionally linked to feedback items
  • Unread Indicators — per-conversation unread message counts
  • Email Notifications — transactional emails for key booking events

Gamification

  • XP & Leveling System — earn XP from trips, activities, and engagement
  • 12+ Titles — progress from Novice → Explorer → Traveler → Globetrotter → Adventurer → … → Beyond Limits
  • Level Thresholds — L1 (0 XP), L2 (50), L3 (120), L4 (200), L5 (300), then +100/level
  • Dashboard Progress Bar — visual rank, level, and title display

Content Moderation

  • Profanity Filter — regex-based blacklist with automatic masking (e.g., f***)
  • Grammar Checking — LanguageTool API integration for real-time spelling and grammar correction
  • Multi-language Translation — MyMemory Translation API with auto-detection (supports French, Spanish, Italian, German, Portuguese, Russian, Japanese, Korean, Chinese, English)
  • Feedback System — full CRUD with profanity filtering, sentiment tagging, and duplicate detection
  • Comments — threaded comments on feedback items

Admin Dashboard

  • User Management — view, search, filter, sort, create, edit, role-assign, and delete users
  • Resource Management — admin CRUD for Properties, Offers, Bookings, Trips, Activities, and Services
  • Moderation Panel — review and manage all user-generated feedback and comments

UI/UX

  • Dark / Light Theme Toggle — AtlantaFX themes (PrimerDark / PrimerLight) with smooth fade transitions
  • Responsive Full-screen Layout — adapts to screen resolution
  • Rich Dashboard — profile card, wallet balance, gamification rank, featured properties, and featured trips

Tech Stack

Frontend

Layer Technology Version Purpose
🖼️ UI Framework JavaFX + FXML 25 Declarative UI with scene graph rendering
🎨 Theming AtlantaFX 2.0.1 Modern dark/light themes (PrimerDark / PrimerLight)
🖋️ Fonts & Styling CSS + Segoe UI — Custom stylesheets with card-based layouts
📷 QR Codes ZXing (core + javase) 3.5.3 QR code generation for TOTP 2FA setup
🗺️ Maps WebView + Leaflet.js — Interactive map rendering via embedded browser

Backend

Layer Technology Version Purpose
☕ Language Java 25 Core platform with JPMS module system
🔧 Build Tool Apache Maven 3.x Dependency management & build lifecycle
🗄️ Database MySQL 8.x Relational data storage
🔌 DB Connector MySQL Connector/J 8.3.0 JDBC driver for MySQL
🔐 Password Hashing jBCrypt 0.4 BCrypt credential hashing
📷 Face Recognition JavaCV (OpenCV) 1.5.10 LBPH biometric authentication via webcam
💳 Payments Stripe Java SDK 24.18.0 Secure checkout & wallet top-up
🤖 AI Google Gemini 2.5 Flash REST API AI chatbot & trip planning assistant
📧 Email JavaMail (javax.mail) 1.6.2 SMTP transactional emails
📱 SMS Twilio — SMS notifications
📋 JSON org.json, Gson 20231013 · 2.10.1 API response parsing & serialization
📄 PDF iTextPDF — Booking confirmation & report generation
🌐 HTTP java.net.http, OkHttp — REST API consumption

Architecture

The project follows a layered MVC architecture with a clean separation of concerns:

com.travelxp
├── ai/                  # AI service layer (Gemini, Trip AI) — 2 classes
├── controllers/         # JavaFX FXML controllers — 20 classes
├── models/              # Data models / POJOs — 14 classes
├── repositories/        # Data access layer — 8 classes
├── services/            # Business logic layer — 24 classes
└── utils/               # Utilities (DB, theming, profanity, sentiment, etc.) — 10 classes

Design Patterns Used:

  • Repository Pattern — clean data access abstraction
  • Service Layer — encapsulated business logic
  • MVC — Model-View-Controller via JavaFX + FXML
  • Singleton — database connection (MyDB), user session (UserSession)
  • Strategy — dynamic pricing and cancellation policy engines

Application Flow

flowchart LR
    A[🚀 Launch App] --> B{Authenticate}
    B -->|Password| C[Login]
    B -->|Face ID| C
    B -->|New User| D[Register]
    D --> C
    C --> E[🏠 Dashboard]
    E --> F[🗺️ Trips]
    E --> G[🏡 Properties]
    E --> H[🤖 AI Chat]
    E --> I[👤 Profile]
    F --> J[📋 Activities]
    G --> K[📅 Booking]
    K --> L{Payment}
    L -->|Wallet| M[✅ Confirmed]
    L -->|Stripe| M
    M --> N[📧 Email Sent]
    J --> O[⭐ Earn XP]
    O --> P[🏆 Level Up!]
Loading

Authentication Flow

flowchart TD
    Start([User Opens App]) --> Login[Login Screen]
    Login --> Cred{Auth Method?}
    Cred -->|Email + Password| Verify[Verify BCrypt Hash]
    Cred -->|Face ID| Cam[📷 Webcam Capture]
    Cam --> LBPH[LBPH Recognition]
    LBPH -->|Confidence ≥ 85| TwoFA
    LBPH -->|Confidence < 85| Fail[❌ Not Recognized]
    Verify -->|Valid| TwoFA{TOTP Enabled?}
    Verify -->|Invalid| Fail2[❌ Wrong Credentials]
    TwoFA -->|Yes| TOTP[Enter 6-digit Code]
    TwoFA -->|No| Success
    TOTP -->|Valid ±1 window| Success[✅ Dashboard]
    TOTP -->|Invalid| Fail3[❌ Invalid Code]

    style Success fill:#22c55e,color:#fff
    style Fail fill:#ef4444,color:#fff
    style Fail2 fill:#ef4444,color:#fff
    style Fail3 fill:#ef4444,color:#fff
Loading

Dynamic Pricing Engine

flowchart TD
    Base["💲 Base Price / Night"] --> Season{Season?}
    Season -->|Jun-Aug| Peak["×1.30 Peak Summer"]
    Season -->|Dec-Jan| Winter["×1.25 Winter Holiday"]
    Season -->|Mar-May, Sep| Shoulder["×1.10 Shoulder"]
    Season -->|Other| Off["×0.90 Off-Peak"]
    
    Peak & Winter & Shoulder & Off --> Demand{Demand Level?}
    Demand -->|≥10 bookings| High["×1.20 High Demand"]
    Demand -->|≥5 bookings| Med["×1.10 Medium Demand"]
    Demand -->|< 5| Normal["×1.00 Normal"]
    
    High & Med & Normal --> Guests{Extra Guests?}
    Guests -->|> 2 guests| Extra["+$15/night per extra"]
    Guests -->|≤ 2| NoExtra[No surcharge]
    
    Extra & NoExtra --> Stay{Stay Length?}
    Stay -->|28+ nights| Monthly["-20% Monthly"]
    Stay -->|7+ nights| Weekly["-10% Weekly"]
    Stay -->|< 7| NoDisc[No discount]
    
    Monthly & Weekly & NoDisc --> Total["🧾 Final Price + Services"]

    style Total fill:#22c55e,color:#fff,stroke:#16a34a
    style Base fill:#3b82f6,color:#fff
Loading

Entity Relationship Overview

erDiagram
    USER ||--o{ TRIP : creates
    USER ||--o{ BOOKING : makes
    USER ||--o{ FEEDBACK : writes
    USER ||--o{ MESSAGE : sends
    USER ||--o{ GAMIFICATION : earns
    
    TRIP ||--o{ ACTIVITY : contains
    TRIP ||--o{ TRIP_MILESTONE : tracks
    TRIP ||--o{ BOOKING : "linked to"
    
    PROPERTY ||--o{ BOOKING : "booked at"
    PROPERTY ||--o{ OFFER : has
    
    BOOKING }o--o{ SERVICE : includes
    
    FEEDBACK ||--o{ COMMENT : receives
    
    CONVERSATION ||--o{ MESSAGE : contains
    USER ||--o{ CONVERSATION : participates

    USER {
        int id PK
        string username
        string email
        string password_hash
        string role
        float balance
        int xp
        boolean totp_enabled
    }
    TRIP {
        int id PK
        string name
        string origin
        string destination
        date start_date
        date end_date
        float budget
        string status
    }
    PROPERTY {
        int id PK
        string title
        string city
        string country
        float price_per_night
        float latitude
        float longitude
    }
    BOOKING {
        int id PK
        date booking_date
        int duration
        float total_price
        string status
        int num_guests
    }
Loading

Gamification Progression

gantt
    title XP Level Progression
    dateFormat X
    axisFormat %s XP

    section Levels
    L1 Novice           :done, 0, 50
    L2 Explorer          :done, 50, 120
    L3 Traveler          :active, 120, 200
    L4 Globetrotter      :200, 300
    L5 Adventurer        :300, 400
    L6 Voyager           :400, 500
    L7 Wanderer          :500, 600
    L8 Nomad             :600, 700
    L9 Pioneer           :700, 800
    L10 Trailblazer      :800, 900
Loading

Getting Started

Prerequisites

Requirement Version Notes
Java JDK 25+ Download from Oracle or use SDKMAN
Apache Maven 3.x Installation guide
MySQL Server 8.x Download
Webcam — Optional — required only for Face ID feature

Verify your setup:

java --version    # Should show 25+
mvn --version     # Should show 3.x
mysql --version   # Should show 8.x

Installation

  1. Clone the repository

    git clone https://github.com/your-org/Esprit-PIDEV-3A1-2526-Travelxp.git
cd Esprit-PIDEV-3A1-2526-Travelxp

  2. Set up the database

    mysql -u root -p < travelxp.sql

    For incremental schema updates, apply the migration files in database lifeline/ in order (see Database section).

  3. Install dependencies

    mvn clean install

  4. Configure the application (see Configuration below)

  5. Run the application

    mvn javafx:run

Configuration

Edit src/main/resources/db.properties to configure the application:

# Database
db.url=jdbc:mysql://localhost:3306/travelxp?useSSL=false&serverTimezone=UTC
db.user=root
db.password=

# Stripe (required for payments)
stripe.secret.key=sk_test_...

# Google Gemini AI (required for AI chat)
gemini.api.key=your_gemini_api_key

# SMTP Email (required for email notifications)
mail.smtp.host=smtp.gmail.com
mail.smtp.port=587
mail.smtp.user=your_email@gmail.com
mail.smtp.password=your_app_password
mail.from=your_email@gmail.com

Note: For Gmail SMTP, use an App Password rather than your account password.

Security: Never commit real API keys or credentials. Use environment variables or a local .env file (add it to .gitignore).

Quick Start Cheat Sheet

# 1. Clone & enter
git clone https://github.com/your-org/Esprit-PIDEV-3A1-2526-Travelxp.git
cd Esprit-PIDEV-3A1-2526-Travelxp

# 2. Database
mysql -u root -p < travelxp.sql

# 3. Configure (edit db.properties with your keys)
notepad src/main/resources/db.properties   # Windows
# nano src/main/resources/db.properties    # Linux/macOS

# 4. Build & Run
mvn clean javafx:run

Usage

journey
    title User Journey in TravelXP
    section Getting Started
      Register an account: 5: User
      Set up Face ID or TOTP: 4: User
      Explore the dashboard: 5: User
    section Planning a Trip
      Create a new trip: 5: User
      Add activities: 4: User
      Invite participants: 4: User
    section Booking
      Browse properties: 5: User
      Review dynamic pricing: 3: User
      Confirm & pay: 5: User, Stripe
      Receive email confirmation: 5: System
    section Engagement
      Chat with Gemini AI: 5: User, AI
      Complete activities for XP: 4: User
      Level up & earn titles: 5: User
      Leave feedback: 4: User
Loading

Step-by-Step

  1. Register a new account or log in with existing credentials
  2. Set up Face ID or TOTP 2FA from your profile for enhanced security
  3. Browse properties and explore featured listings on the dashboard
  4. Plan trips — create trips, add activities, and invite participants
  5. Book accommodations — select dates, review dynamic pricing breakdown, and confirm
  6. Recharge wallet via Stripe to fund bookings
  7. Chat with Gemini AI for personalized travel guidance
  8. Earn XP by completing trips and activities to climb the leaderboard
  9. Leave feedback and engage with the community through comments and messaging

Project Structure

Esprit-PIDEV-3A1-2526-Travelxp/
├── pom.xml                          # Maven project configuration
├── travelxp.sql                     # Main database schema
├── database lifeline/               # Incremental migration scripts
│   ├── setup.sql
│   ├── migration.sql
│   ├── role_migration.sql
│   ├── face_id_migration.sql
│   ├── totp_migration.sql
│   ├── booking_services_migration.sql
│   ├── dynamic_pricing_migration.sql
│   ├── feedback_migration.sql
│   ├── messaging_migration.sql
│   ├── property_geocoding_migration.sql
│   ├── trips_migration.sql
│   └── ...
├── faces/                           # Face ID training data & model
│   ├── face_model.yml
│   └── haarcascade_frontalface_default.xml
├── uploads/                         # User-uploaded images
└── src/
    └── main/
        ├── java/
        │   ├── module-info.java
        │   └── com/travelxp/
        │       ├── Main.java                  # Application entry point
        │       ├── UserSession.java           # Session management
        │       ├── ai/                        # AI services
        │       ├── controllers/               # 20 FXML controllers
        │       ├── models/                    # 14 data models
        │       ├── repositories/              # 8 data repositories
        │       ├── services/                  # 24 business services
        │       └── utils/                     # Utility classes
        └── resources/
            ├── db.properties                  # App configuration
            ├── style.css                      # Global stylesheet
            ├── com/travelxp/views/            # FXML view files
            └── icons/                         # UI icons

API Integrations

API Purpose Auth
Google Gemini 2.5 Flash AI chatbot assistant API Key
Stripe Checkout Online payments & wallet recharge Secret Key
ExchangeRate-API Live currency exchange rates None
Nominatim (OpenStreetMap) Forward & reverse geocoding None
OSRM Driving routes & turn-by-turn directions None
LanguageTool Grammar & spelling checking None
MyMemory Translation Multi-language text translation None

Database

The application uses a MySQL database named travelxp. The main schema is defined in travelxp.sql.

Incremental migrations are stored in the database lifeline/ directory and should be applied in chronological order for existing installations. Key tables include:

Table Description
users User accounts, roles, wallet balance, XP, TOTP & Face ID data
trips Trip itineraries with origin, destination, dates, status
activities Trip-linked activities with type, date, cost
properties Accommodation listings with geolocation
bookings Reservation records linking users, properties, and trips
booking_services Many-to-many junction for extra booking services
services Available add-on services
offers Time-bound discount offers on properties
feedback User feedback with sentiment tags
comments Threaded comments on feedback
conversations Messaging conversations
messages Individual chat messages
trip_milestones Progress milestones within trips
gamification XP, level, and title tracking

Database Schema Map

flowchart TD
    subgraph "👤 User Domain"
        U[(users)]
        G[(gamification)]
    end
    
    subgraph "✈️ Trip Domain"
        T[(trips)]
        A[(activities)]
        TM[(trip_milestones)]
    end
    
    subgraph "🏡 Property Domain"
        P[(properties)]
        O[(offers)]
    end
    
    subgraph "📅 Booking Domain"
        B[(bookings)]
        BS[(booking_services)]
        S[(services)]
    end
    
    subgraph "💬 Social Domain"
        F[(feedback)]
        C[(comments)]
        CV[(conversations)]
        M[(messages)]
    end
    
    U --> G
    U --> T
    U --> B
    U --> F
    U --> CV
    T --> A
    T --> TM
    T --> B
    P --> B
    P --> O
    B --> BS
    BS --> S
    F --> C
    CV --> M

    style U fill:#3b82f6,color:#fff
    style T fill:#f59e0b,color:#fff
    style P fill:#10b981,color:#fff
    style B fill:#8b5cf6,color:#fff
    style F fill:#ef4444,color:#fff
Loading

Screenshots

🔐 Login & Authentication

Login Face ID TOTP Setup
Login Face ID TOTP

🏠 Dashboard & Navigation

Dashboard Dark Mode Profile
Dashboard Dark Feedback

✈️ Core Features

Trip Planning Booking AI Chat
Trips Booking AI

🛠️ Admin Panel

User Management Properties Moderation
Admin Properties Offers

Contributors

Yassine Raddadi
Yassine Raddadi 		Dhia Raddaoui
Dhia Raddaoui 		Anas Nafti
Anas Nafti 		Youssef Litaiem
Youssef Litaiem 		Omar Ehlal
Omar Ehlal

Academic Context
Institution ESPRIT — School of Engineering (Tunisia)
Program Software Engineering — 3rd Year (3A)
Course PIDEV (Projet Intégré de Développement) — 3A1
Academic Year 2025–2026
Project Type Full-stack integrated development project
Team Size 5 members

The PIDEV is a capstone-style development project at ESPRIT where students design, implement, and deliver a complete software product covering the full development lifecycle — from requirements gathering and database design through backend logic, UI development, API integration, and deployment.

Acknowledgments

We would like to thank:

  • ESPRIT — for providing the academic framework and guidance throughout the PIDEV program
  • Our supervising instructors — for their mentorship, code reviews, and technical direction
  • Google Gemini — for the AI capabilities powering the chatbot and trip planning assistant
  • Stripe — for secure payment processing infrastructure
  • OpenStreetMap & Nominatim — for open geocoding and map data
  • OSRM — for open-source routing engine
  • LanguageTool — for grammar and spelling checking API
  • MyMemory — for the translation API
  • AtlantaFX — for the modern JavaFX theme library
  • The open-source community — for the libraries and tools that made this project possible

Made with Java Powered by Gemini Built at ESPRIT

Built with ❤️ at ESPRIT — 2025/2026

About

Developed at Esprit School of Engineering – Tunisia 2025-2026 - Technologies Principales

Topics

academic-projectannee-universitaireesprit-piesprit-school-of-engineeringtechnologie-principale

Resources

Readme
License
Activity

Stars

6 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages