elifbasboga/java-parcel-sort

ParcelSortX - Smart Package Sorting and Routing Simulation

ParcelSortX is a simulation project developed in Java with a Swing-based GUI. It was created for an academic Data Structures course and demonstrates the effective use of classic data structures such as Queue, Stack, AVL Tree, Hash Table, and Circular Linked List.

---

📦 Project Overview

In each simulation tick, new parcels are randomly generated and first placed into a queue. They are then sorted into destination cities using an AVL tree structure. Misrouted parcels are sent to a stack and reprocessed at intervals. All parcel data is tracked via a hash table, and terminal rotation (active city) is managed through a circular linked list.

---

🧱 Data Structures Used

• Queue (ArrivalBuffer): Stores newly arriving parcels.
• Stack (ReturnStack): Holds misrouted parcels to be reprocessed.
• AVL Tree (CityBST): Organizes parcels based on destination city, each city has its own priority queue.
• Hash Table: Tracks parcel status and enables quick access.
• Circular Linked List: Manages the rotation of active terminal cities.

---

🚀 How to Use

1. Open the project with IntelliJ IDEA.
2. In the src/ directory, run the ParcelSortXGUI.java main method.
3. (Optional) Create a config.txt file to customize the simulation. Example:

   MAX TICKS=30
   QUEUE CAPACITY=20
   TERMINAL ROTATION INTERVAL=5
   PARCEL PER TICK MIN=1
   PARCEL PER TICK MAX=3
   MISROUTING RATE=0.1
   CITY LIST=Istanbul,Ankara,Izmir,Bursa
   

4. Monitor the simulation via the GUI.
5. Upon completion, the system generates two output files: report.txt and log.txt.

---

🔄 Simulation Flow

• Parcels are randomly generated and added to the arrival queue.
• They are sorted into the AVL tree based on destination city.
• Highest-priority parcels are dispatched to the currently active terminal.
• Misrouted parcels are pushed to the return stack.
• Return parcels are retried up to 3 times before being canceled.
• Parcel statuses are continuously tracked via a hash table.
• At the end, summary and logs are exported automatically.

---

🖥️ Interface Features

• Dark-themed Swing-based graphical user interface.
• Real-time visual simulation of parcel flow and data structures.
• ASCII-based structural representation.
• Final simulation report displayed in a separate window in HTML format.

---

📁 File Structure

src/
├── ParcelSortX.java       # Simulation engine and core logic
├── ParcelSortXGUI.java    # GUI entry point and layout
config.txt                 # (Optional) Simulation configuration file
report.txt                 # Automatically generated summary report
log.txt                    # Step-by-step simulation log

---

👩‍💻 Author

• elifbasboga | Hugging Face Profile

---

📄 License

This project is intended for educational use only. Not for commercial distribution.