DeliverEase

Overview

DeliverEase is a delivery dispatch and inventory management system built for small distribution operations. Managers use it to create orders, plan delivery routes, manage inventory, and assign drivers. Drivers use it to see their assigned routes, track stops, and mark deliveries complete.

The system is split into two role-based dashboards — one for Managers and one for Drivers — and includes a Mapbox-powered map for visualizing and optimizing delivery routes.

---

Purpose & Scope

DeliverEase is designed to streamline delivery dispatch for small-to-medium distribution operations. It covers the full lifecycle of a delivery: from order creation and inventory reservation, through route planning and driver assignment, to final delivery confirmation. The system supports two user roles — Managers and Drivers — each with a dedicated interface tailored to their responsibilities. It does not handle customer-facing ordering, payment processing, or real-time GPS tracking. All operations are performed through a web browser with no additional software required beyond Docker for initial setup.

---

Primary Use Case

A Manager receives incoming orders, reserves inventory, builds a delivery route, assigns a driver, and publishes the route. The Driver logs in, reviews their assigned stops on a map, and marks each stop complete as they make deliveries. The system reflects status changes in real time across both dashboards.

---

What It Does

Managers can:

• Create and manage customer orders with line items
• Build delivery routes, assign drivers, and set stop order
• Optimize route stop order automatically via Mapbox
• Publish routes to drivers when ready
• Track inventory levels and adjust stock with a reason log
• Monitor driver and order status in real time

Drivers can:

• View their assigned routes and stop details
• See delivery stops on an interactive Mapbox map
• Mark stops as Delivered, Failed, or Skipped
• Track route progress from start to completion

---

Core Features

Order Management

Purpose: Track and manage customer delivery requests from creation to completion.
Inputs: Customer name, phone, delivery address, and one or more product line items with quantity and price.
Outputs: A saved order with a unique ID, geocoded coordinates, and an initial status of NEW.

Each order moves through a status flow: NEW → READY → ASSIGNED → OUT_FOR_DELIVERY → DELIVERED / FAILED / CANCELLED. Addresses are automatically geocoded on creation if a Mapbox token is configured.

Route Planning

Purpose: Organize multiple orders into an efficient delivery run and assign it to a driver.
Inputs: Route date, driver selection, and one or more orders added as stops.
Outputs: A published route visible to the assigned driver, with stops ordered for efficient delivery.

Managers create delivery routes, assign a driver and date, then add orders as stops. Before publishing, the route can be optimized — the backend calls the Mapbox Optimization API to reorder stops into the most efficient sequence. Routes move through: DRAFT → PUBLISHED → IN_PROGRESS → COMPLETED.

Inventory Tracking

Products have inventory levels tracked with a full transaction log. Adjustments are made with a reason code (e.g., RECEIVE, DAMAGE, ORDER_RESERVE). Stock is automatically reserved when an order is created and deducted on delivery.

Driver Dashboard

Once a route is published, the assigned driver can see it in their dashboard. Each stop shows the customer info, address, and a map marker. Drivers mark stops complete as they go, and the route status updates accordingly.

---

👥 Team Members

• zhamby
• ctcriswe
• jccrutsi
• cammy1403

---

Tech Stack

Frontend

• React
• HTML5
• CSS3

Backend

• Go (Golang)

Database

• PostgreSQL

DevOps / Infrastructure

• Docker
• Docker Compose
• GitHub Actions (CI/CD)

---

Project Architecture

The application consists of three main services:

• Frontend: React-based UI served on port 5173
• Backend: Go API server running on port 8080
• Database: PostgreSQL running on port 5432

All services are orchestrated using Docker Compose.

---

Getting Started

Prerequisites

• Docker Desktop — required to run all services
• Git

No need to install Go or Node locally — Docker handles everything.

---

1. Clone the Repository

git clone https://github.com/zhamby/DeliverEase.git
cd DeliverEase

---

2. Set Up Environment Variables

cp .env.example .env

Open .env and fill in the following:

Variable	Required	Description
DB_USER	Yes	PostgreSQL username
DB_PASSWORD	Yes	PostgreSQL password
DB_NAME	Yes	Database name
JWT_SECRET	Yes	Secret key for signing JWTs — set this to anything random
ADMIN_EMAIL	Yes	Email for the seeded manager account (used to log in on first run)
ADMIN_PASSWORD	Yes	Password for the seeded manager account
MAPBOX_TOKEN	No	Enables map display and route optimization. Without it, maps won't load but everything else works.

The defaults in .env.example work for local development as-is. You mainly need to set ADMIN_EMAIL, ADMIN_PASSWORD, and optionally MAPBOX_TOKEN if you want the full map experience.

---

3. Run the Application (Docker)

docker compose up --build

This starts all three services (frontend, backend, database). First run takes a minute while Docker pulls images and builds containers.

---

4. Access the Application

Service	URL
Frontend (UI)	http://localhost:5173
Backend API	http://localhost:8080
PostgreSQL	localhost:5432

---

5. First Login

On startup, the backend automatically creates a Manager account using ADMIN_EMAIL and ADMIN_PASSWORD from your .env. Use those credentials to log in as a Manager. To add Driver accounts, register them through the app or send a POST /api/auth/register request with "role": "DRIVER".

---

Docker Services

Service	Description	Port
frontend	React application	5173
backend	Go API server	8080
db	PostgreSQL database	5432

---

Operating Instructions

The following workflows cover day-to-day system operation for each user role. Follow these steps in order for a complete delivery cycle.

Manager Workflow

The typical flow for getting an order out for delivery:

1. Create a product — Inventory tab → add SKU, name, unit
2. Add stock — Inventory tab → Adjust → Reason: RECEIVE → enter quantity
3. Create an order — Orders tab → fill in customer info and address → add line items
4. Mark the order Ready — Orders tab → update status to READY
5. Create a route — Routes tab → set date, assign a driver
6. Add stops — Open the route → add orders as stops
7. Optimize (optional) — click Optimize to reorder stops via Mapbox
8. Publish — publish the route so the driver can see it

Driver Workflow

1. Log in with your Driver account
2. View your routes — only published routes assigned to you appear
3. Open a route to see the stop list and map
4. Mark stops as Delivered, Failed, or Skipped as you go
5. Route status automatically updates to IN_PROGRESS on the first stop and COMPLETED when all stops are resolved

---

Error Handling & Troubleshooting

Issue	Cause	Resolution
JWT token expired / logged out unexpectedly	No token refresh mechanism; tokens expire after 24 hours	Log out and log back in to receive a new token
Map won't render or Optimize button fails	MAPBOX_TOKEN is missing or invalid in .env	Add a valid Mapbox public token to .env and restart with docker compose up --build
Backend crashes on first run	Database container wasn't fully ready before the backend started	Re-run docker compose up --build — the DB health check passes on retry
Driver can call Manager API endpoints	Role-based auth middleware is not applied to all routes yet	Known limitation — planned fix for a future release; avoid sharing Driver credentials

---

Running Tests

Run from the project root:

go test ./backend/internal/service/ -v

Current tests cover service-layer input validation (auth, orders, routes, inventory). Integration tests against a real database are still needed to cover full business logic flows — including the route publish state machine, the login credential flow, and inventory deduction on delivery.

---

API Reference

The full API reference (all endpoints, request bodies, and response examples) is documented in backend/README.md.

---

Project Structure

.
├── frontend/        # React app
├── backend/         # Go API
├── database/        # SQL init scripts
├── .github/         # GitHub Actions workflows
├── compose.yml      # Docker Compose config
└── README.md

---

Continuous Integration (CI)

We use GitHub Actions to automatically:

• Build the backend (Go)
• Run backend tests
• Install and build the frontend (React)

CI runs on:

• Every pull request
• Every push to dev, test, and main

---

Branching Strategy

We use a structured multi-branch workflow:

• main → Production-ready code
• test → Testing / staging environment
• dev → Active development integration

Workflow

feature/* → dev → test → main

Rules

• No direct commits to dev, test, or main
• All changes must go through Pull Requests
• CI must pass before merging

---

Development Workflow

1. Create a new branch from dev:

   git checkout dev
   git pull
   git checkout -b feature/your-feature-name

2. Make your changes and commit:

   git add .
   git commit -m "Add: description of feature"

3. Push your branch:

   git push -u origin feature/your-feature-name

4. Open a Pull Request → dev

---

Future Improvements

• Add token refresh (JWTs currently expire after 24 hours with no renewal path)
• Add role-based authorization middleware to all routes

---

Glossary

Term	Definition
Order	A customer delivery request containing one or more product line items
Route	A scheduled delivery run assigned to a specific driver for a given date
Stop	A single order added to a route, representing one delivery location
Inventory	The tracked stock levels of products available for order fulfillment
Publish	The action that makes a route visible and active for the assigned driver
JWT	Session credential returned on login — valid for 24 hours, then requires re-login
MANAGER	User role with full access to orders, routes, inventory, and driver management
DRIVER	User role restricted to viewing and completing their assigned routes

---

License

This project is for educational purposes as part of a senior design course.

---