// github.com/Darkus39/StudyPlannerFX

BRACU Study Planner v2.0

Academic management system for BRACU students — Java 21 · Spring Boot 3.2 · JavaFX 21

Java 21 Spring Boot 3.2.4 JavaFX 21.0.2 Lombok 1.18.38 Gson 2.10.1 Platform Win · Mac · Linux

// what it does

📊

Dashboard

Live CGPA tracker, semester overview, and progress stats at a glance.

📚

Course Manager

Add, edit and track courses from a built-in BRACU database of ~340 courses.

🗓️

Study Schedule

Auto-generated study schedules and topic roadmaps per course.

🎯

CGPA Forecast

Target CGPA simulation — see exactly what grades you need to hit your goal.

💾

Local Persistence

All data saved locally as JSON. Never leaves your device.

💡

Light UI

Fully custom light theme with Syne + JetBrains Mono typography.

🌑

Dark UI

Fully custom dark theme with Syne + JetBrains Mono typography.

// what's new in v2.0

Area	Before (v1)	Now (v2)
Architecture	Plain JavaFX MVC	Spring Boot + JavaFX — full DI, service layer
UI	Basic JavaFX styling	Fully redesigned dark theme
Persistence	Working dir JSON	`Documents/BRACUStudyPlanner/` (cross-platform)
Distribution	`mvn javafx:run` only	jpackage native installer (.exe / .dmg / .rpm / .deb)
Bug fix (Fedora 43)	Freeze on "Initialize Profile"	Fixed with `Platform.runLater()`

// architecture

View

SetupScreenMainScreenDashboardTabCoursesTabScheduleTabSettingsTab

Services

StudentServiceCgpaServiceCourseRepositoryScheduleServicePersistenceService

Model

StudentCourseEntrySemesterInfo

Core

Spring Boot 3.2JavaFX 21LombokGson

// one-click installers

For non-terminal users — Three scripts are included in the repo root. Download the one for your OS, place it in the StudyPlannerFX/ folder, and run it. Java and Maven will be installed automatically if missing, then the app will launch.

🪟 Windows

Get the script

File: install-windows.bat (in repo root)

Right-click → Run as Administrator

Required for winget to install JDK/Maven if not present

App launches automatically ✓

First run downloads Maven dependencies (~2 min)

Manual terminal commands

:: Install JDK 21
winget install Microsoft.OpenJDK.21

:: Install Maven
winget install Apache.Maven

:: Launch app
cd StudyPlannerFX
mvn javafx:run

🍎 macOS

Get the script

File: install-macos.sh (in repo root)

Open Terminal, run:

chmod +x install-macos.sh && ./install-macos.sh

Installs Homebrew, JDK 21, Maven if needed. Works on Intel & Apple Silicon.

App launches automatically ✓

Manual terminal commands

# Install Homebrew (skip if present)
/bin/bash -c "$(curl -fsSL \
https://raw.githubusercontent.com/Homebrew\
/install/HEAD/install.sh)"

brew install --cask temurin@21
brew install maven
cd StudyPlannerFX && mvn javafx:run

🐧 Linux

Get the script

File: install-linux.sh (in repo root)

Open Terminal, run:

chmod +x install-linux.sh && ./install-linux.sh

Auto-detects apt (Ubuntu/Debian) or dnf (Fedora/RHEL). Sudo required.

App launches automatically ✓

Manual — Ubuntu / Debian

sudo apt update
sudo apt install openjdk-21-jdk maven
cd StudyPlannerFX && mvn javafx:run

Manual — Fedora / RHEL

sudo dnf install java-21-openjdk-devel maven
cd StudyPlannerFX && mvn javafx:run

// developer commands

bash

# Run in dev mode (fastest)
mvn javafx:run

# Build fat JAR then run
mvn clean package
java -jar target/StudyPlannerFX-2.0.0.jar

# Build native installer — Linux / macOS
chmod +x build-installer.sh && ./build-installer.sh

# Build native installer — Windows
.\build-installer.bat

// native installer (no java required for end users)

Use build-installer.sh / .bat to produce a platform-native package with a bundled JRE — end users don't need Java installed.

Platform	Output	Install
Windows	`.exe` installer	Double-click to install
macOS	`.dmg` disk image	Open → drag to Applications
Fedora / RHEL	`.rpm` package	`sudo dnf install *.rpm`
Ubuntu / Debian	`.deb` package	`sudo dpkg -i *.deb`

// data storage

Privacy — All student data is saved locally as human-readable JSON. Nothing is ever sent to any server.

OS	Location
Windows	`%USERPROFILE%\Documents\BRACUStudyPlanner\student_data.json`
macOS	`~/Documents/BRACUStudyPlanner/student_data.json`
Linux	`~/BRACUStudyPlanner/student_data.json`

// project structure

tree

StudyPlannerFX/
├── install-windows.bat          ← one-click installer — Windows
├── install-macos.sh             ← one-click installer — macOS
├── install-linux.sh             ← one-click installer — Linux
├── build-installer.sh / .bat    ← jpackage native installer builder
├── pom.xml
└── src/main/java/com/bracu/studyplanner/
    ├── app/
    │   ├── Launcher.java            ← true entry point
    │   ├── StudyPlannerApp.java      ← bootstraps Spring + JavaFX
    │   └── SpringConfig.java
    ├── model/
    │   ├── Student.java
    │   ├── CourseEntry.java
    │   └── SemesterInfo.java
    ├── service/
    │   ├── StudentService.java       ← main orchestrator
    │   ├── CgpaService.java
    │   ├── CourseRepository.java
    │   ├── PersistenceService.java
    │   └── ScheduleService.java
    └── view/
        ├── screens/
        │   ├── SetupScreen.java
        │   ├── MainScreen.java
        │   └── tabs/
        │       ├── DashboardTab.java
        │       ├── CoursesTab.java
        │       ├── ScheduleTab.java
        │       └── SettingsTab.java
        └── components/
            ├── FormField.java
            ├── StatCard.java
            └── StatusBadge.java

// bug fix — fedora 43 freeze

On Linux/GTK JavaFX builds, swapping the scene root inside an active event dispatch caused the pulse scheduler to deadlock.

java

// Before — causes freeze on Linux/GTK:
onComplete.run();

// After — deferred to next FX pulse, safe everywhere:
Platform.runLater(onComplete);