A polished JavaFX desktop experience for exploring music, publishing songs, and improving lyrics together.
VerseVault began as an Advanced Programming midterm and grew into a complete, portfolio-ready desktop application. It combines an editorial music experience with secure authentication, role-aware workflows, durable local persistence, and a modular Java architecture.
The catalog contains fictional artists and original demo lyrics, making the project safe to explore and present without relying on copyrighted material.
| Listener | Artist | Administrator |
|---|---|---|
| Discover songs, albums, and artists | Publish songs and build albums | Review artist applications |
| Follow favorite creators | Edit owned lyrics | Approve publishing access |
| Comment on songs | Review lyric suggestions | Protect privileged registration |
| Suggest lyric improvements | Manage a personal catalog | Maintain role boundaries |
- Three real user journeys with listener, artist, and administrator access.
- Secure local authentication using salted PBKDF2 password hashes while retaining compatibility with legacy SHA-256 records.
- Moderated artist onboarding with pending applications and administrator approval before publishing access is granted.
- A complete music catalog with songs, albums, artists, genres, tags, follows, comments, views, and lyric-edit requests.
- Reliable persistence through flat JSON records and atomic file replacement.
- A cohesive JavaFX design system with strong hierarchy, keyboard focus, validation states, styled dialogs, and confirmation for destructive actions.
- Automated service tests covering authentication and a full catalog workflow.
- Desktop packaging through Gradle and
jlink, with no separate Java install required for the generated runtime image.
flowchart LR
UI["JavaFX Views"] --> CTX["AppContext"]
CTX --> AUTH["AuthService"]
CTX --> CATALOG["CatalogService"]
AUTH --> ACCOUNTS["Account Models"]
CATALOG --> DOMAIN["Catalog Models"]
AUTH --> USERS["Local Account Store"]
CATALOG --> JSON["Atomic JSON Store"]
src/main/java/org/example/musicapp/
├── Main.java Application entry point
├── AppContext.java Shared service wiring
├── models/ Accounts and catalog domain types
├── services/
│ ├── AuthService.java Authentication and artist approval
│ └── CatalogService.java Catalog operations and persistence
└── views/ Programmatic JavaFX screens
Views receive the shared JavaFX Stage and typed domain context. Business rules
live in services, while models remain flat and serialization-friendly. This keeps
navigation straightforward without coupling the interface directly to file I/O.
| Area | Technology |
|---|---|
| Language | Java 17 |
| Desktop UI | JavaFX 17 |
| Build | Gradle 8.10 Wrapper |
| Persistence | Gson 2.10.1 and local files |
| Testing | JUnit Jupiter 5.10.2 |
| Packaging | Badass JLink Plugin |
- JDK 17 or newer
- A Windows, macOS, or Linux desktop environment
- Internet access for the first dependency download
Windows PowerShell:
.\gradlew.bat run --no-daemon --console=plainmacOS or Linux:
./gradlew run --no-daemon --console=plainThe first launch creates the local catalog automatically. Listener and artist accounts can be created from the sign-up screen; new artist accounts remain pending until approved by an administrator.
Administrator registration is intentionally unavailable in the public sign-up flow. For a local review session, provide temporary bootstrap credentials through environment variables:
$env:MUSICAPP_ADMIN_USERNAME = "reviewer-admin"
$env:MUSICAPP_ADMIN_EMAIL = "admin@example.com"
$env:MUSICAPP_ADMIN_PASSWORD = "ChooseYourOwnStrongPassword123"
.\gradlew.bat run --no-daemon --console=plainThe administrator is provisioned only if the username is not already present. Clear the variables after the first successful launch. Local account and catalog files are intentionally excluded from version control.
# Compile and run the JUnit suite
.\gradlew.bat test --no-daemon --console=plain
# Run the complete build
.\gradlew.bat build --no-daemon --console=plain
# Generate a self-contained desktop runtime ZIP
.\gradlew.bat jlinkZip --no-daemon --console=plainThe test suite covers listener registration, pending artist restrictions, administrator provisioning, legacy authentication compatibility, persistence, song and album creation, follows, comments, and lyric-edit approval.
- Role-based access is represented with explicit domain types instead of loose UI state.
- Public input cannot create administrator accounts.
- Password verification avoids storing or logging plaintext credentials.
- Catalog records reference stable IDs and usernames rather than circular object graphs.
- Persistence errors are propagated, and catalog writes replace files atomically.
- Scene navigation preserves the authenticated account and shared application services.
Designed and built a modular JavaFX music and lyrics platform with Java 17, role-based access control, PBKDF2 authentication, moderated artist onboarding, atomic JSON persistence, automated JUnit workflows, and a packaged desktop runtime.
VerseVault is an educational portfolio project demonstrating object-oriented design, inheritance, encapsulation, validation, service boundaries, persistence, exception handling, event-driven interfaces, and automated testing. It is not affiliated with or intended to replace any commercial music platform.