A sophisticated JavaFX desktop application for managing cinemas, films, series, products, and user experiences
Features β’ Architecture β’ Installation β’ Usage β’ API β’ Contributing
- Overview
- Features
- Architecture
- Technology Stack
- Getting Started
- Project Structure
- Database Configuration
- Docker Deployment
- CI/CD Pipeline
- Testing
- API Integrations
- Contributing
- License
- Disclaimer
- Authors
RAKCHA is a comprehensive entertainment management platform built with JavaFX 21. It provides a complete ecosystem for managing cinemas, films, TV series, e-commerce products, and user interactions. The application features a modern UI with animations, multi-database support, OAuth authentication, payment processing, and real-time notifications.
- π₯ Cinema Management - Complete cinema, hall, seat, and movie session management
- πΊ Series Streaming - TV series catalog with seasons, episodes, and watch progress tracking
- π E-Commerce - Full shopping cart, orders, and payment processing
- π Multi-Auth - Traditional login, Google/Microsoft OAuth, and Face Recognition
- π³ Payments - Stripe and PayPal integration
- π Analytics - Sentiment analysis, statistics, and reporting
- π Multi-Database - MySQL, PostgreSQL, SQLite, and H2 support
- π³ Docker Ready - Complete containerization with Docker Compose
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β RAKCHA Desktop Application β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β PRESENTATION LAYER β β
β β βββββββββββββββ βββββββββββββββ βββββββββββββββ βββββββββββββββββββββββ β β
β β β JavaFX β β FXML β β CSS β β Controllers (MVC) β β β
β β β Views β β Layouts β β Styles β β - Users (21) β β β
β β β β β β β β β - Films (8) β β β
β β β Splash β β Sidebar β β Dashboard β β - Cinemas (11) β β β
β β β Dashboard β β Dialogs β β Modern UI β β - Products (12) β β β
β β β Forms β β Cards β β Animations β β - Series (9) β β β
β β βββββββββββββββ βββββββββββββββ βββββββββββββββ βββββββββββββββββββββββ β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β BUSINESS LAYER β β
β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β β β Services (IService<T>) β β β
β β β βββββββββββββ βββββββββββββ βββββββββββββ βββββββββββββββββββββ β β β
β β β β User β β Film β β Cinema β β Product β β β β
β β β β Services β β Services β β Services β β Services β β β β
β β β β β β β β β β β β β β
β β β β - User β β - Film β β - Cinema β β - Product β β β β
β β β β - Friend β β - Actor β β - Hall β β - Cart β β β β
β β β β - Message β β - Ticket β β - Seat β β - Order β β β β
β β β β - Notify β β - Categoryβ β - Session β β - Payment β β β β
β β β β - Watch β β β β β β β β β β
β β β βββββββββββββ βββββββββββββ βββββββββββββ βββββββββββββββββββββ β β β
β β β βββββββββββββ ββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β β β β Series β β Search Service ββ β β
β β β β Services β β - Universal search with Caffeine caching ββ β β
β β β β - Series β β - Role-based filtering (Client/Admin/Manager) ββ β β
β β β β - Season β β - Auto-suggestions and trending ββ β β
β β β β - Episode β β ββ β β
β β β β - Favoriteβ ββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β β β βββββββββββββ β β β
β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β DATA LAYER β β
β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β β β Models (Entities) β β β
β β β ββββββββββββββββββ ββββββββββββββββββ ββββββββββββββββββββββββββ β β β
β β β β Users β β Films β β Cinemas β β β β
β β β β - User β β - Film β β - Cinema β β β β
β β β β - Admin β β - Actor β β - CinemaHall β β β β
β β β β - Client β β - Ticket β β - Seat β β β β
β β β β - CinemaManagerβ β β β - MovieSession β β β β
β β β β - Friendship β β β β β β β β
β β β β - Achievement β β β β β β β β
β β β β - Notification β β β β β β β β
β β β ββββββββββββββββββ ββββββββββββββββββ ββββββββββββββββββββββββββ β β β
β β β ββββββββββββββββββ ββββββββββββββββββ β β β
β β β β Products β β Series β β β β
β β β β - Product β β - Series β β β β
β β β β - Order β β - Season β β β β
β β β β - OrderItem β β - Episode β β β β
β β β β - ShoppingCart β β - Favorite β β β β
β β β β - Payment β β β β β β
β β β ββββββββββββββββββ ββββββββββββββββββ β β β
β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β β β β
β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β β β DataSource (Multi-Database) β β β
β β β MySQL β PostgreSQL β SQLite β H2 + HikariCP Connection Pool β β β
β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β UTILITIES LAYER β β
β β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ ββββββββββββββββββββ β β
β β β Authenticationβ β Payment β β Media β β Communication β β β
β β β β β β β β β β β β
β β β SignInGoogle β β Stripe API β β CloudinaryAPIβ β UserMail β β β
β β β SignInMS β β PayPal SDK β β FilmTrailer β β UserSMS β β β
β β β FaceRecog β β β β IMDB API β β TrayNotify β β β
β β β BCrypt β β β β β β β β β
β β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ ββββββββββββββββββββ β β
β β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ ββββββββββββββββββββ β β
β β β Navigation β β Documents β β Security β β Validators β β β
β β β β β β β β β β β β
β β β Breadcrumb β β UserPDF β βSecurityConfigβ β EmailValidator β β β
β β β ScreenNav β β QR/Barcode β βSessionManagerβ β PasswordValidatorβ β β
β β β QuickNav β β iText β β β β β β β
β β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ ββββββββββββββββββββ β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
EXTERNAL INTEGRATIONS
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ β
β β Google β βMicrosoft β β Stripe β β PayPal β β Twilio β β Vonage β β
β β OAuth β β OAuth β β Payments β β Payments β β SMS β β SMS β β
β ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ β
β ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ β
β β YouTube β β IMDB β βCloudinaryβ β OpenCV β β ZXing β β VADER β β
β β API β β Scraper β β Storage β β Face β β QR/Codes β βSentiment β β
β ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
| Feature | Description |
|---|---|
| π₯ Film Catalog | Comprehensive film database with descriptions, durations, and categories |
| π¨βπ€ Actor Management | Track actors with filmographies and biographical information |
| π’ Cinema Management | Manage cinema venues, halls, and seating arrangements |
| π Movie Sessions | Schedule screenings with date, time, and cinema hall assignment |
| ποΈ Ticket Booking | Purchase and manage tickets with seat selection |
| β Ratings & Reviews | User ratings and sentiment-analyzed comments |
| Automatic trailer fetching via YouTube API | |
| π IMDB Integration | Rich film metadata from IMDB scraping |
| Feature | Description |
|---|---|
| π Series Catalog | Browse TV series with seasons and episodes |
| π Watch Progress | Track viewing progress across episodes |
| β€οΈ Favorites | Mark series as favorites for quick access |
| π Statistics | View series analytics and user engagement |
| Feature | Description |
|---|---|
| π Product Catalog | Entertainment merchandise and collectibles |
| π Shopping Cart | Full cart management with quantity updates |
| π³ Checkout | Secure payment processing via Stripe/PayPal |
| π¦ Order Tracking | Complete order lifecycle management |
| π± QR Codes | Product QR code generation via ZXing |
| π Analytics | Order and sales analytics dashboard |
| Feature | Description |
|---|---|
| π¨βπΌ Role-Based Access | Client, Admin, and Cinema Manager roles |
| π€ User Profiles | Comprehensive profile management |
| π€ Social Features | Friend system with messaging and chat |
| π Achievements | Gamification with user achievements |
| π£ Notifications | Real-time in-app and system tray notifications |
| π Watchlist | Personal watchlist management |
| Feature | Description |
|---|---|
| π Traditional Login | Username/password with BCrypt hashing |
| π OAuth 2.0 | Google and Microsoft social authentication |
| ποΈ Face Recognition | Biometric login using OpenCV |
| π Password Security | History tracking and strength validation |
| π‘οΈ Session Management | Secure session handling with cleanup |
| Feature | Description |
|---|---|
| π° Stripe Integration | Credit card processing |
| Alternative payment method | |
| π Order History | Complete transaction tracking |
| π§Ύ PDF Invoices | Automated receipt generation |
| Feature | Description |
|---|---|
| π§ Email | SMTP email with templates |
| π± SMS | Twilio and Vonage integration |
| π Push Notifications | System tray notifications |
| π¬ In-App Chat | Real-time messaging system |
| Technology | Version | Purpose |
|---|---|---|
| Java | 21 | Core language with modern features |
| JavaFX | 21.0.7 | Desktop UI framework |
| Maven | 3.6+ | Build automation and dependency management |
| Library | Version | Purpose |
|---|---|---|
| ControlsFX | 11.2.2 | Extended JavaFX controls |
| JFoenix | 9.0.10 | Material Design components |
| Ikonli | 12.4.0 | Icon packs (Material Design 2) |
| AnimateFX | 1.3.0 | UI animations |
| ValidatorFX | 0.6.1 | Form validation |
| Technology | Version | Purpose |
|---|---|---|
| MySQL | 9.3.0 | Production database |
| PostgreSQL | 42.7.1 | Alternative production database |
| SQLite | 3.50.2 | Development/embedded database |
| HikariCP | 5.1.0 | Connection pooling |
| Library | Purpose |
|---|---|
| ScribeJava 8.3.3 | OAuth 2.0 (Google, Microsoft) |
| JBCrypt 0.4 | Password hashing |
| OpenCV 4.9+ | Face recognition |
| Service | Version | Purpose |
|---|---|---|
| Stripe Java | 29.4.0 | Credit card payments |
| PayPal REST SDK | 1.14.0 | PayPal transactions |
| API | Purpose |
|---|---|
| YouTube Data API v3 | Film trailers |
| Google API Client 2.8.0 | Google services |
| IMDB Scraper | Film metadata |
| Cloudinary | Media storage |
| Service | Version | Purpose |
|---|---|---|
| Twilio | 11.0.0 | SMS notifications |
| Vonage | 9.3.1 | SMS backup |
| JavaMail | 1.6.2 | Email services |
| Library | Version | Purpose |
|---|---|---|
| iText | 5.5.13.4 | PDF generation |
| PDFBox | 3.0.5 | PDF manipulation |
| ZXing | 3.5.3 | QR/Barcode generation |
| Library | Version | Purpose |
|---|---|---|
| Caffeine | 3.1.8 | High-performance caching |
| Apache Lucene | 9.12.1 | Full-text search |
| Library | Purpose |
|---|---|
| VADER Sentiment | Review sentiment analysis |
| Tool | Version | Purpose |
|---|---|---|
| JUnit Jupiter | 6.0.0-M1 | Unit testing |
| TestFX | 4.0.18 | JavaFX UI testing |
| AssertJ | 3.27.3 | Fluent assertions |
| Monocle | 21 | Headless testing |
| Lombok | 1.18.38 | Boilerplate reduction |
| JavaFaker | 1.0.2 | Test data generation |
| Logback | 1.5.21 | Logging |
| SpotBugs | 4.8.2.0 | Static analysis |
| OpenRewrite | 5.36.0 | Automated refactoring |
- β Java JDK 21 or later
- π οΈ Maven 3.6+
- ποΈ Database (MySQL 8.0+, PostgreSQL, or SQLite)
- π» IDE with JavaFX support (IntelliJ IDEA, Eclipse, VS Code)
| Requirement | Minimum | Recommended |
|---|---|---|
| OS | Windows 10, macOS 10.15, Ubuntu 20.04 | Latest versions |
| Processor | Intel Core i3 | Intel Core i5/i7 |
| RAM | 4 GB | 8 GB+ |
| Storage | 500 MB | SSD with 2GB+ |
| Graphics | DirectX 11 support | Dedicated GPU (for Face Recognition) |
- Clone the repository
git clone https://github.com/aliammari1/rakcha-desktop.git
cd rakcha-desktop- Configure environment variables
cp .env.example .env
# Edit .env with your API keys and database credentials- Build the project
mvn clean install -DskipTests- Run the application
mvn javafx:runCreate a .env file with the following:
# Database Configuration
DB_URL=jdbc:sqlite:./data/rakcha.db
DB_USER=
DB_PASSWORD=
# OAuth (Optional)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
MICROSOFT_CLIENT_ID=your_microsoft_client_id
MICROSOFT_CLIENT_SECRET=your_microsoft_client_secret
# Payment (Optional)
STRIPE_API_KEY=your_stripe_key
PAYPAL_CLIENT_ID=your_paypal_client_id
PAYPAL_CLIENT_SECRET=your_paypal_secret
# Communication (Optional)
TWILIO_ACCOUNT_SID=your_twilio_sid
TWILIO_AUTH_TOKEN=your_twilio_token
VONAGE_API_KEY=your_vonage_key
VONAGE_API_SECRET=your_vonage_secret
# Media Storage (Optional)
CLOUDINARY_URL=cloudinary://api_key:api_secret@cloud_name
YOUTUBE_API_KEY=your_youtube_api_keyrakcha-desktop/
βββ src/
β βββ main/
β β βββ java/com/esprit/
β β β βββ MainApp.java # Application entry point
β β β βββ components/ # Reusable UI components
β β β β βββ UniversalSearchBox.java
β β β βββ controllers/ # MVC Controllers
β β β β βββ SidebarController.java
β β β β βββ SplashScreenController.java
β β β β βββ cinemas/ # Cinema management (11 controllers)
β β β β βββ films/ # Film management (8 controllers)
β β β β βββ products/ # E-commerce (12 controllers)
β β β β βββ series/ # Series management (9 controllers)
β β β β βββ users/ # User management (21 controllers)
β β β βββ enums/ # Enumerations
β β β β βββ CategoryType.java
β β β β βββ CinemaStatus.java
β β β β βββ OrderStatus.java
β β β β βββ TicketStatus.java
β β β β βββ UserRole.java
β β β βββ exceptions/ # Custom exceptions
β β β βββ models/ # Data models
β β β β βββ cinemas/ # Cinema, Hall, Seat, Session
β β β β βββ films/ # Film, Actor, Ticket
β β β β βββ products/ # Product, Order, Cart, Payment
β β β β βββ series/ # Series, Season, Episode
β β β β βββ users/ # User hierarchy (14 models)
β β β βββ services/ # Business logic
β β β β βββ IService.java # Generic service interface
β β β β βββ cinemas/
β β β β βββ films/
β β β β βββ products/
β β β β βββ search/ # Universal search service
β β β β βββ series/
β β β β βββ users/
β β β βββ utils/ # Utilities
β β β βββ DataSource.java # Database connection
β β β βββ SessionManager.java # User session handling
β β β βββ PaymentProcessor.java # Stripe integration
β β β βββ SignInGoogle.java # Google OAuth
β β β βββ SignInMicrosoft.java # Microsoft OAuth
β β β βββ FaceRecognition.java # OpenCV face auth
β β β βββ CloudinaryStorage.java
β β β βββ UserMail.java # Email service
β β β βββ UserSMSAPI.java # SMS service
β β β βββ UserPDF.java # PDF generation
β β β βββ validators/ # Input validation
β β βββ resources/
β β βββ ui/ # FXML layouts
β β β βββ sidebar.fxml
β β β βββ splash/
β β β βββ admin/
β β β βββ users/
β β β βββ films/
β β β βββ cinemas/
β β β βββ products/
β β β βββ series/
β β β βββ styles/ # CSS stylesheets
β β βββ images/ # Application assets
β β βββ haar/ # OpenCV cascade files
β β βββ *.sql # Database schemas
β βββ packaging/ # jpackage resources
β β βββ windows/
β β βββ macos/
β β βββ linux/
β βββ test/ # Test suites
βββ .github/
β βββ workflows/
β βββ ci.yml # CI pipeline
β βββ build-and-deploy.yml # Native installers
β βββ codeql.yml # Security scanning
βββ config/
β βββ mysql.cnf # MySQL configuration
βββ docs/ # JavaDoc documentation
βββ docker-compose.yml # Docker services
βββ Dockerfile # Application container
βββ pom.xml # Maven configuration
βββ README.md
No configuration needed! SQLite database is created automatically:
DB_URL=jdbc:sqlite:./data/rakcha.dbDB_URL=jdbc:mysql://localhost:3306/rakcha_db?serverTimezone=UTC
DB_USER=rakcha_user
DB_PASSWORD=your_passwordDB_URL=jdbc:postgresql://localhost:5432/rakcha_db
DB_USER=rakcha_user
DB_PASSWORD=your_password# Development mode (with Adminer UI)
docker-compose --profile dev up -d
# Production mode
docker-compose up -d
# View logs
docker-compose logs -f rakcha-app
# Stop services
docker-compose down| Service | Port | Description |
|---|---|---|
| rakcha-app | 8080 | Main application |
| rakcha-db | 3306 | MySQL database |
| rakcha-redis | 6379 | Redis cache |
| adminer | 8081 | Database admin UI (dev only) |
The project uses GitHub Actions for continuous integration and deployment:
| Workflow | Trigger | Purpose |
|---|---|---|
ci.yml |
Push/PR | Build, test, code quality, security scan |
build-and-deploy.yml |
Tags/Releases | Native installers (Windows, macOS, Linux) |
codeql.yml |
Push | Security vulnerability scanning |
βββββββββββββββ βββββββββββββββ βββββββββββββββ βββββββββββββββ
β Build & βββββΆβ Code βββββΆβ Security βββββΆβ Package β
β Test β β Quality β β Scan β β Installer β
βββββββββββββββ βββββββββββββββ βββββββββββββββ βββββββββββββββ
β β β β
βΌ βΌ βΌ βΌ
JUnit Tests SpotBugs OWASP/Trivy jpackage
JaCoCo Coverage JavaDoc CodeQL .msi/.deb/.pkg
Built automatically on release tags:
- Windows:
.msiinstaller - macOS:
.pkginstaller - Linux:
.debpackage + portable archive
# All tests
mvn test
# With coverage report
mvn test jacoco:report
# Headless mode (CI)
mvn test -Dtestfx.robot=glass -Dtestfx.headless=truesrc/test/java/com/esprit/
βββ MainAppTest.java # Application startup tests
βββ controllers/ # Controller unit tests
βββ integration/ # Integration tests
βββ tests/ # Feature tests
β βββ CinemaEnhancementsTest.java
β βββ CinemaVerification.java
βββ utils/ # Utility tests
| Service | Purpose | Documentation |
|---|---|---|
| Google OAuth | Social authentication | Google Identity |
| Microsoft OAuth | Social authentication | Microsoft Identity |
| Stripe | Payment processing | Stripe Docs |
| PayPal | Payment processing | PayPal Developer |
| YouTube Data API | Film trailers | YouTube API |
| Cloudinary | Media storage | Cloudinary Docs |
| Twilio | SMS notifications | Twilio Docs |
| Vonage | SMS backup | Vonage API |
| Role | Description | Capabilities |
|---|---|---|
| Client | Regular user | Browse content, purchase tickets/products, manage profile, social features |
| Cinema Manager | Venue administrator | Manage cinema, halls, seats, movie sessions, view statistics |
| Admin | System administrator | Full access, user management, analytics, system configuration |
We welcome contributions! Please see our Contributing Guide for details.
- π΄ Fork the repository
- πΏ Create a feature branch (
git checkout -b feature/amazing-feature) - πΎ Commit your changes (
git commit -m 'Add amazing feature') - π€ Push to the branch (
git push origin feature/amazing-feature) - π Open a Pull Request
See also:
This project is licensed under a Commercial Use License - see the LICENSE file for details.
Key Points:
- β Free for personal and educational use
- β Free for study and learning
- β Free for contributions and improvements
- β Commercial use requires explicit permission
Code Ownership: The source code in this repository is owned by the author(s). However, no ownership is claimed over any assets (images, icons, fonts, media files, or other third-party resources) used in this project. All assets remain the property of their respective owners.
Educational Purpose: This project is developed strictly for educational purposes. It is intended to demonstrate software development concepts, JavaFX application architecture, and integration with various APIs and services.
Third-Party Components: This project uses various third-party libraries and assets. Users are responsible for reviewing all third-party licenses and ensuring compliance with their terms.
Commercial Use: If you wish to use this project or any part of it for commercial purposes, please contact:
π§ ammari.ali.0001@gmail.com
- Ali Ammari - Lead Developer - @aliammari1
See the list of contributors who participated in this project.
- π All contributors and testers
- π‘ Modern entertainment platforms for inspiration
- π Open-source libraries that made this project possible
- π ESPRIT School of Engineering
Made with β€οΈ by the RAKCHA Team
