Stock Engine API

Microservice for managing product stock and calculating restock priorities.

Requirements

• With Docker: Docker and Docker Compose
• Without Docker: Go 1.25+, PostgreSQL 16+

---

Running with Docker

docker compose up --build

The API will be available at http://localhost:8080 and Swagger UI at http://localhost:8080/swagger/index.html.

To stop:

docker compose down

To stop and remove the database volume:

docker compose down -v

---

Running without Docker

1. Set up PostgreSQL

Make sure you have a PostgreSQL instance running locally.

2. Configure environment variables

cp .env.example .env

Edit .env with your database credentials:

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=example
POSTGRES_DB=postgres
REPOSITORY_TYPE=POSTGRES
HANDLER_TYPE=HTTP
PAGINATION_DEFAULT_LIMIT=20
PAGINATION_MAX_LIMIT=100
PRIORITY_NEGATIVE_STOCK_FACTOR=1.5
PRIORITY_LEAD_TIME_FACTOR=1.2
PRIORITY_ZERO_SALES_FACTOR=0.5
SEED_FILE=internal/infrastructure/repository/db/seed.sql

3. Run the application

go run ./cmd

The API will be available at http://localhost:8080.

---

API Endpoints

Method	Route	Description
POST	/stock	Create a product stock
GET	/stock	List all product stocks
GET	/stock/:id	Get a product stock by ID
PUT	/stock/:id	Update a product stock
DELETE	/stock/:id	Delete a product stock
GET	/stock/category/:category	List product stocks by category
GET	/restock/priorities	Get restock priorities
GET	/swagger/index.html	Swagger UI

---

Request Examples

Create a product stock

curl -X POST http://localhost:8080/stock \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Oil Filter X",
    "category": "engine",
    "current_stock": 15,
    "minimum_stock": 20,
    "average_daily_sales": 4,
    "lead_time_days": 5,
    "unit_cost": 18.50,
    "criticality_level": 3
  }'

List all product stocks

curl "http://localhost:8080/stock?page=1&limit=10"

Get a product stock by ID

curl http://localhost:8080/stock/{id}

Update a product stock

curl -X PUT http://localhost:8080/stock/{id} \
  -H "Content-Type: application/json" \
  -d '{
    "current_stock": 25,
    "minimum_stock": 30
  }'

Delete a product stock

curl -X DELETE http://localhost:8080/stock/{id}

Get restock priorities

curl "http://localhost:8080/restock/priorities?page=1&limit=10"

---

Running Tests

Domain Restock Priority tests

go test -v ./internal/domain

Use cases unit tests

go test -v ./internal/application/tests

E2E tests

Requires the application running (docker compose up -d or go run ./cmd):

go test ./tests/e2e/ -v -count=1

---

Swagger

With the application running, access the interactive API documentation at:

http://localhost:8080/swagger/index.html

Regenerating Swagger docs

go install github.com/swaggo/swag/cmd/swag@latest
swag init -g cmd/main.go -o docs --parseInternal