Skip to main content

​
Prerequisites

Before you begin, ensure you have:
  • Docker & Docker Compose installed on your system
Optional: Node.js (v18+) and Java 17 are only needed if you want to run tests, linting, or builds outside of Docker.

​
Start the Application

The fastest way to run the Product Distribution Dashboard is with Docker Compose, which starts all services (PostgreSQL, backend, frontend, and pgAdmin) in one command.
1

Clone the Repository

First, clone the project repository:
git clone <repository-url>
cd product-distribution
2

Start the Stack

From the project root, run:
docker compose up --build
This command will:
  • Build the backend Spring Boot application
  • Build the Angular frontend application
  • Start PostgreSQL 16 with the configured database
  • Start pgAdmin for database administration
  • Connect all services together
The --build flag ensures the latest code changes are included. For subsequent starts without code changes, you can use docker compose up.
3

Wait for Services to Initialize

The first startup takes a few minutes as Docker builds the images and initializes the database. Watch for these indicators:
  • PostgreSQL health check passes
  • Backend starts and runs Flyway migrations
  • Frontend compilation completes
  • Data loading from JSON sources completes

​
Access the Application

Once all services are running, you can access:

Frontend Dashboard

URL: http://localhost:4200The main application interface with maps, metrics, and data tables

Backend API

URL: http://localhost:8080RESTful API endpoints and Spring Boot actuator

pgAdmin

URL: http://localhost:5050Email: [email protected]
Password: adminDatabase administration interface

Health Check

URL: http://localhost:8080/actuator/healthBackend health status endpoint

​
What Happens on First Startup

When the application starts for the first time, the following automatic processes occur:
1

Database Schema Creation

Flyway runs migrations to create the database schema:
  • products and product_sizes tables
  • stores table with geolocation and capacity fields
  • warehouses table with geolocation data
  • product_items table for inventory
  • stock_assignments table for distribution results
  • unfulfilled_demands table for tracking shortages
2

JSON Data Loading

The backend loads initial data from JSON sources:
  • Products: Product catalog with brands and sizes
  • Stores: Store locations with coordinates, capacity, and demand
  • Warehouses: Warehouse locations with available inventory
By default, these are loaded from the GitHub repository’s /data/current/ directory.
3

Distribution Algorithm Execution

The system automatically runs the distribution algorithm to:
  • Calculate optimal warehouse assignments for each store’s demand
  • Respect store capacity constraints and expected return rates
  • Generate stock assignments and track unfulfilled demands
  • Populate the database with distribution results
4

Frontend Initialization

The Angular application loads and displays:
  • Interactive map with warehouse and store markers
  • Distribution routes as polylines with arrows
  • Global metrics dashboard
  • Filterable data tables
The initial data load can take 30-60 seconds depending on the size of the JSON files. The stores.json file contains over 5MB of data with detailed demand information.

​
Verify the Installation

To confirm everything is working correctly:
  1. Check the Frontend: Open http://localhost:4200 and verify you see the dashboard with a map
  2. View Stock Assignments: Click on the “Stock Assignments” tab to see distribution data
  3. Inspect Metrics: Look for global metrics showing fulfillment rates and total assignments
  4. Test Filtering: Use the filters to select specific warehouses, stores, or products

​
Docker Compose Configuration

The docker-compose.yml file defines the following services: 
services:
  postgres:
    image: postgres:16-alpine
    container_name: product-distribution-postgres
    environment:
      POSTGRES_DB: product_distribution_db
      POSTGRES_USER: product_distribution
      POSTGRES_PASSWORD: product_distribution
    ports:
      - "5432:5432"

  backend:
    build:
      context: .
      dockerfile: ./backend/Dockerfile
    container_name: product-distribution-backend
    ports:
      - "8080:8080"
    environment:
      SPRING_PROFILES_ACTIVE: dev
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/product_distribution_db

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    container_name: product-distribution-frontend
    ports:
      - "4200:4200"

  pgadmin:
    image: dpage/pgadmin4
    container_name: pgadmin
    ports:
      - "5050:80"

​
Environment Profiles

The backend uses Spring Boot profiles to manage different environments:

​
Development Profile (dev)

Used by default in Docker Compose:
  • Connects to local PostgreSQL container
  • Loads data from GitHub raw JSON URLs (configurable)
  • Enables Spring Boot DevTools for hot reload
  • Uses environment variables for database connection

​
Production Profile (prod)

Used for Render deployment:
  • Connects to external PostgreSQL with SSL
  • Configurable via DATABASE_HOST, DATABASE_PORT, DATABASE_NAME
  • Optimized HikariCP connection pool settings
  • Configurable scheduler cron expressions

​
Stopping the Application

To stop all services: 
docker compose down
To stop and remove all data (including the PostgreSQL volume): 
docker compose down -v
Using the -v flag will delete all database data. Use this only when you want a complete reset.

​
Troubleshooting

Ensure the PostgreSQL container is healthy before the backend starts. The docker-compose.yml includes a health check dependency. Check logs with:
docker compose logs postgres
docker compose logs backend
Verify the backend is running and accessible at http://localhost:8080. The frontend is configured to connect to this URL by default.
Check that the backend can access the JSON data URLs. By default, it fetches from GitHub. You can override with environment variables:
  • DATA_PRODUCTS_URL
  • DATA_STORES_URL
  • DATA_WAREHOUSES_URL
If ports 4200, 8080, 5432, or 5050 are already in use, modify the port mappings in docker-compose.yml.

​
What’s Next?

Architecture Overview

Learn about the system architecture, data flow, and core components

API Reference

Explore the backend REST API endpoints

Frontend Guide

Understand the Angular components and services

Configuration

Customize data sources, strategies, and deployment settings

Build docs developers (and LLMs) love

Get started for freeTalk to us