Skip to content

Delivery Service API

🚚

A comprehensive logistics and delivery management REST API built with Java, Spring Boot, and PostgreSQL. Manages delivery routes, shipment tracking, driver assignments, and real-time delivery status updates.

Features

Feature Description Icon
Shipment Tracking Real-time tracking of deliveries and shipments 📍
Route Optimization Optimize delivery routes for efficiency 🗺️
Driver Management Assign and manage delivery drivers and their performance 👨‍🚗
Geolocation Services GPS tracking and geofencing capabilities 🌐
Delivery Status Updates Real-time status notifications to customers 📢
Proof of Delivery Capture signatures, photos, and delivery confirmations ✓
Multi-Tenant Support Isolate deliveries per tenant 🏢

Architecture Overview

flowchart TD
    A[Client] -->|REST API| B(DeliveryController)
    B --> C[DeliveryService]
    C --> D[RouteService]
    C --> E[TrackingService]
    D --> F[DeliveryRepository]
    D --> G[DriverRepository]
    E --> H[TrackingRepository]
    F --> I[(PostgreSQL)]
    G --> I
    H --> I
    E --> J[GPS Service]
Hold "Alt" / "Option" to enable pan & zoom

API Endpoints

Note: Real API endpoints to be provided and included here.

Method Endpoint Description Notes/Parameters
POST /api/v1/deliveries Create delivery order tenantId header, delivery data
GET /api/v1/deliveries/{id} Get delivery details
PUT /api/v1/deliveries/{id} Update delivery status New status
POST /api/v1/routes Create delivery route Delivery IDs and waypoints

Sequence: Create Delivery and Assign Route

sequenceDiagram
    participant U as User
    participant API as DeliveryController
    participant D as DeliveryService
    participant R as RouteService
    participant T as TrackingService
    participant Repo as DeliveryRepository
    U->>API: POST /deliveries (pickup, dropoff)
    API->>D: validate delivery
    D->>Repo: save delivery
    Repo-->>D: delivery created
    D->>R: create route
    R-->>D: route created
    D->>T: initialize tracking
    T-->>D: tracking started
    D-->>API: DeliveryResponse
    API-->>U: 201 Created + delivery details
Hold "Alt" / "Option" to enable pan & zoom

Database Schema

erDiagram
    deliveries {
        UUID id PK
        UUID tenant_id
        VARCHAR reference_number
        VARCHAR pickup_address
        VARCHAR dropoff_address
        VARCHAR status
        TIMESTAMP scheduled_date
        DECIMAL amount
        TIMESTAMP created
        TIMESTAMP updated
    }

    routes {
        UUID id PK
        UUID tenant_id
        VARCHAR route_name
        UUID driver_id FK
        VARCHAR status
        TIMESTAMP start_time
        TIMESTAMP end_time
        TIMESTAMP created
    }

    tracking_updates {
        UUID id PK
        UUID delivery_id FK
        DECIMAL latitude
        DECIMAL longitude
        VARCHAR status
        TIMESTAMP timestamp
        VARCHAR notes
    }

    drivers {
        UUID id PK
        UUID tenant_id
        VARCHAR driver_name
        VARCHAR phone
        VARCHAR vehicle_id
        VARCHAR status
        TIMESTAMP created
    }

    routes ||--o{ deliveries : "includes"
    routes ||--o{ drivers : "assigned_to"
    deliveries ||--o{ tracking_updates : "tracked_by"
Hold "Alt" / "Option" to enable pan & zoom

Getting Started

Prerequisites

  • Java 17+
  • PostgreSQL
  • Gradle

Setup

git clone https://github.com/Olanna-tech/delivery-service-java.git
cd delivery-service-java
./gradlew build

Database

  • Configure your PostgreSQL credentials in src/main/resources/application.yml.
  • Run Flyway migrations (auto on startup).

Run

./gradlew bootRun

Configuration

Set the following environment variables in application.yml: 

delivery:
  gps-tracking-interval-seconds: 60
  route-optimization-enabled: true
  notification-enabled: true
  driver-update-interval: 30

Contributing

Pull requests are welcome! For major changes, please open an issue first.

License

MIT

Contact