shipping-pack-optimizer

shipping-pack-optimizer Service

Table of Contents

• What is shipping-pack-optimizer?
• How does shipping-pack-optimizer work?
  • Frontend
  • API
• Configuration
• Run the service
  • Run with custom configs
• Development
  • Prerequisites
  • Running the application
  • Running tests
  • Linting
  • Code formatting
  • Vendoring

What is shipping-pack-optimizer?

shipping-pack-optimizer is a Golang based application that calculates the number of packs needed to ship to a customer.

How does shipping-pack-optimizer work?

Frontend

The shipping-pack-optimizer service also provides a user-friendly frontend, from which the aforementioned API can be conveniently accessed and tested. You can reach the frontend from your browser at:

http://localhost:8080

The frontend itself is quite minimalistic - it contains an input field for submitting the number of items to be packed.

And upon submission, it presents neatly formatted API responses. The responses are conveniently displayed, showing each pack and the corresponding quantity.

API

The application exposes its functionality through an HTTP API and accepts a JSON payload with the following structure:

{
  "items": 501
}

The items field is a positive integer that represents the number of items that need to be packed.

The application responds with a JSON payload with the following structure:

{
  "packs": [
    {
      "pack": 250,
      "quantity": 2
    },
    {
      "pack": 1,
      "quantity": 1
    }
  ]
}

It primarily runs on localhost port 8080 and acts upon POST requests to the api/v1/pack endpoint.

Below is a Curl command snippet demonstrating how to call this endpoint

curl --location --request POST 'localhost:8080/api/v1/pack' \
--header 'Content-Type: application/json' \
--data '{
    "items": 501
}'

Configuration

Application follows the 12-factor app methodology and can be configured using environment variables.

Following environment variables are supported:

Run the service

All available docker image versions can be found here: https://github.com/obalunenko/shipping-pack-optimizer/pkgs/container/shipping-pack-optimizer-server

The easiest way is to run it via docker:

  docker run -p8080:8080 -P ghcr.io/obalunenko/shipping-pack-optimizer-server:latest

Then open in browser http://localhost:8080 to test application

Run with custom configs

Create .env file (you can use .env.example as template) or create on your own, using variables from Configuration section

  docker run -p8080:8080 -P --env-file ./.env ghcr.io/obalunenko/shipping-pack-optimizer-server:latest

Development

Prerequisites

• Go 1.24 or higher
• Docker 27.5 or higher
• Docker Compose 2.32 or higher

Running the application

For development purposes, the application can be run locally using the following command:

  make build && make run

To build and run the application in a Docker container, use the following command:

  make docker-build && make docker-run

Running tests

To run the tests, use the following command:

  make test

To run tests without logs, use the following command:

  TEST_DISCARD_LOG=true make test

Linting

To run the linter, use the following command:

  make vet

Code formatting

To format the code, use the following command:

  make format-code

Vendoring

To vendor the dependencies, use the following command:

  make vendor