---

PackTrack

PackTrack is a lightweight web-based application designed to help users organize and track their personal deliveries in one centralized platform. It streamlines delivery tracking, provides packaging tips, and adds a fun touch with motivational quotes.

---

Table of Contents

1. Problem Statement
2. Tech Stack
3. Core Features
4. Project Structure
5. User Interface
6. Setup Instructions
   • Local Setup
   • Docker Setup
7. Environment Variables
8. DevOps & CI/CD
9. Contact
10. Contributors

---

Problem Statement

Managing online deliveries is often chaotic—tracking numbers are scattered across emails and SMS, leading to missed deliveries and confusion. PackTrack solves this with a centralized dashboard, real-time status tracking, and insightful packaging tips.

---

Tech Stack

Layer	Technologies
Frontend	HTML, CSS, JavaScript
Backend	PHP
Database	MySQL
Authentication	JWT Tokens
DevOps	GitHub Actions, Docker
APIs Used	Quotable API

---

Core Features

User Features

• JWT-secured User Registration & Login
• Dashboard to manage deliveries
• Add New Deliveries (Courier, Tracking Number, Item Title, Expected Delivery Date)
• View / Filter / Search / Sort deliveries
• Delivery Status Auto-Tracking via Public API
• Eco-friendly packaging tips
• Random Motivational Quotes

Admin Features

• Admin Dashboard for managing users & logs
• Manually / Automatically Update Delivery Status
• User Management (Add/Remove Users)

---

Project Structure

PackTrack/ 
├── .github/ 
│   └── workflows/ 
│       └── ci-cd.yml 
├── app/ 
│   ├── api/
│   │   ├── admin/
│   │   │   ├── charts/
│   │   │   │   ├── categories.php
│   │   │   │   ├── delivery-overview.php
│   │   │   │   ├── delivery-trends.php
│   │   │   │   └── status-by-time.php
│   │   │   ├── admin-stats.php
│   │   │   └── users-activity.php
│   │   ├── dashboard/
│   │   │   ├── charts/
│   │   │   │   ├── package-activity.php
│   │   │   │   └── package-status.php
│   │   │   └── dashboard-stats.php
│   │   ├── random/
│   │   │   └── quotes.json
│   │   ├── check-access.php
│   │   └── protectedRoute.php
│   ├── auth/
│   │   ├── login.php
│   │   ├── logout.php
│   │   ├── register.php
│   │   └── TokenValidator.php
│   ├── connection/ 
│   │   └── db-conn.php
│   ├── Core/
│   │   ├── jwt/
│   │   │   └── JwtHandler.php
│   │   └── middlewares/
│   │       └── authMiddleware.php
│   ├── data/
│   │   ├── MOCK_Deliveries_DATA.csv
│   │   ├── MOCK_Users_DATA.csv
│   │   └── PackTrackDB_users.sql
│   ├── handlers/
│   │   └── add-package.php
│   ├── helpers/
│   │   └── response.php
│   └── composer.json
├── docker/ 
│   └── Dockerfile
├── Documents/
│   ├── images/
│   │   ├── Diagrams/
│   │   └── UI/
│   └── references/
├── public
│   ├── assets/ 
│   │   ├── css/  
│   │   │   └── style.css
│   │   └── js/ 
│   │       ├── shared/
│   │       │   ├── auth.js
│   │       │   ├── backend-conn.js
│   │       │   ├── notification.js
│   │       │   ├── quotes.js
│   │       │   ├── script.js
│   │       │   └── style-switcher.js
│   │       ├── admin.js
│   │       └── dashboard.js
│   └── views/
│       ├── errors/
│       │   ├── 403.html
│       │   ├── 404.html
│       │   └── 500.html
│       ├── shared/
│       │   ├── add-package-modal.html
│       │   ├── add-package-modal.js
│       │   ├── loading.html
│       │   ├── maintenance.html
│       │   ├──sidebar.html
│       │   └── sidebar.js
│       ├── admin-panel.html 
│       ├── dashboard.html 
│       └── index.html
├── scripts/
│   ├── insert_deliveries_data.py
│   └── insert_users_data.py
├── .env
├── .htaccess
├── docker-compose.yml 
├── LICENSE
└── README.md

---

User Interface

This section provides a visual overview of PackTrack’s user interface. Each screen has been designed to be clean, responsive, and highly functional with a modern dashboard layout that ensures great UX and security.

---

Figure 1: Login Form (JWT-Based Authentication)

A sleek, minimalist login screen for both Users and Admins.

• Security: Secured using JWT-based authentication.
• UX: Simple form with real-time validation.
• Access Control: Redirects based on user roles after login.

---

Figure 2: Registration Form with Role-Based Access

A role-aware signup form supporting User and Admin registration.

• Dynamic Fields: Shows “Admin Secret Key” only when Admin role is selected.
• Access Control: Only valid secret key holders can register as Admins.

---

Figure 3: User Dashboard

A powerful dashboard for regular users to monitor deliveries.

• Package Activity Chart: Line graph tracking package trends over time.
• Package Status Chart: Donut chart visualizing delivery status distribution.
• Add Delivery Form: Easy input for new deliveries.
• Delivery Logs Table: searchable table with delivery history.
• Navigation Bar: Clean sidebar for fast access to all sections.

---

Figure 4: Add New Package Modal

This modal allows users to add new delivery records in a structured, user-friendly format.

• Dynamic Fields: Includes dropdowns, date pickers, and required inputs for all relevant delivery details.
• UX Design: Dark/light-mode compatible, responsive layout, and visually integrated into the dashboard flow.
• Data Entry: Supports real-time validation and direct entry of courier, route, status, dates, and package type.
• Secure Submission: Accessible only to authenticated users; validated through backend token checks to prevent unauthorized submission.

---

Figure 5: Admin Panel Overview

Admin dashboard featuring full system oversight.

• Stats Overview: Real-time system stats with trend indicators.
• Charts: Visual breakdowns of delivery patterns and delays.
• Role-Based Access: Restricted to Admins only.

---

Figure 6: Admin Panel (cont) & Recent Users Activity Log

Detailed activity tracking and user management tools.

• Recent Logs: Shows login timestamps and delivery changes.
• User List: Track users, their status, and last activity.

---

Figure 7: Daily Quote Widget

A motivational widget embedded in the dashboard.

• Quote APIs: Fetches from Quotable API and custom endpoint.
• User Options: Refresh, auto-update, or hide quotes.
• Custom Themes: Matches delivery/logistics productivity themes.

---

Figure 8: Forbidden Access (403)

Access denied screen when permissions are insufficient.

• JWT Enforcement: Ensures role-based access with token validation.
• User-Friendly Feedback: Offers quick links to login or return to dashboard.

---

Figure 9: Internal Server Error (500)

Graceful error screen for backend/server failures.

• Safe Debugging: Hides internal server info.
• Recovery Options: Prompt to reload or return to dashboard.

---

Figure 10: Not Found (404)

Displayed when users land on non-existent routes.

• Design Consistency: Keeps UX polished even in error.
• Navigation Help: Offers links to guide users back on track.

---

Figure 11: Loading Animation

Animated loader shown during data fetch or navigation.

• Dynamic Messages: Provides status updates or tips.
• Reduced Friction: Keeps users engaged during wait time.

---

These UI components together create a seamless, modern web experience that’s both secure and intuitive for delivery tracking and management. PackTrack is built for performance, clarity, and role-aware interaction.

---

Setup Instructions

Local Setup

1. Clone the Repository

git clone https://github.com/rasha-2k/PackTrack.git
cd packtrack

2. Copy .env.example and fill in credentials

cp .env.example .env

open the .env file and fill in the following details:

• DB credentials: MySQL host, port, username, and password.
• JWT secret
• Other API keys (optional for quotes API)

3. Database Set Up
   • Configure your PHP/Apache local server
   • Locate the PackTrackDB_users.sql file inside the data/ folder.
   • Import the SQL file into your local MySQL database using the following command:

mysql -u root -p PackTrackDB < data/PackTrackDB_users.sql

4. Start Frontend
   • Start from index.html (Login Page)

Docker Setup

Instead of using a local server like XAMPP, use Docker for a consistent setup:

1. Build Docker Images: Build the web (backend + frontend) and db images using Docker Compose

docker-compose build
docker-compose up -d

This will start the backend and the MySQL database on the specified ports.

2. Verify containers are running: Run the following command to check running containers:

docker ps

Expected Output:

• You should see at least two containers: one for the backend and one for the database.
• The STATUS column should show "Up" (e.g., Up 10 minutes).

Example:

CONTAINER ID   IMAGE           COMMAND                  CREATED        STATUS       PORTS                               NAMES
551eb2492fc4   packtrack-web   "docker-php-entrypoi…"   13 hours ago   Up 4 hours   0.0.0.0:8080->80/tcp                packtrack-web-1
3b25816a991f   mysql:8.0       "docker-entrypoint.s…"   13 hours ago   Up 2 hours   0.0.0.0:3306->3306/tcp, 33060/tcp   packtrack-db-1

3. Visit: http://localhost:8080/public/views/index.html

---

Environment Variables

DB_HOST=db
DB_PORT=3306
DB_NAME=PackTrackDB
DB_USER=root
DB_PASS=your_database_password

ADMIN_SECRET=admin_secret_key
JWT_SECRET=your_secret_jwt_key
QUOTES_API_URL=https://api.quotable.io/random

---

DevOps & CI/CD

• Automated Build & Deployment via GitHub Actions.
• The .github/workflows/ci-cd.yml file defines the CI/CD steps, including:
  • Code linting and testing.
  • Docker image builds.
  • Deploy to the server automatically when new changes are merged.

Workflow: .github/workflows/ci-cd.yml

---

Contact

Email: rasha.k.alsaleh@gmail.com | LinkedIn: @rasha-alsaleh
Email: awamasdra@gmail.com | LinkedIn: @sdra-awameh
Email: Saqerdalaa@gmail.com | LinkedIn: @dalaa-saqer

---

Contributors