📦 GoStock

A RESTful API for managing products and stocks
Built with Go · Hexagonal Architecture · Production-ready

---

🚀 Tech Stack

Layer	Technology
Language	Go 1.25+
HTTP Framework	Fiber v3
ORM / Query Builder	Bun
Database	SQLite (via sqliteshim)
Dependency Injection	Uber FX
Validation	go-playground/validator
API Documentation	Swaggo + Swagger UI
Logging	log/slog + slog-betterstack
Testing	testify + uber/mock
Linting	golangci-lint
Containerization	Docker (multi-stage build)

✨ Features

• Product management — Create, read, update, and delete products
• Stock management — Create, read, update, and delete stocks with capacity control
• Capacity enforcement — Products can only be added to a stock if space is available
• Health check endpoint with service status reporting
• Swagger UI served at /api/v1/docs
• Rate limiting, request ID, CORS, and recovery middlewares out of the box
• Structured logging with Betterstack integration
• Database migrations via a standalone migrator binary

📋 Prerequisites

• Go 1.25+
• Docker (optional, for containerized run)
• Make

⚙️ Environment Variables

Tip

Create a .env file at the root of the project before running.

APP_SERVER_PORT=8080
APP_DATABASE_URI=./database/app.db
APP_SERVER_ORIGIN_FRONT=http://localhost:3000

# Optional – Betterstack log ingestion
APP_BETTERSTACK_TOKEN=your_token_here
APP_BETTERSTACK_INGESTING_HOST=https://in.logs.betterstack.com

🛠️ Running Locally

Install dependencies

go mod download

Run database migrations

make migrate-up

Start the server

make run

Note

The API will be available at http://localhost:8080/api/v1. Swagger UI is available at http://localhost:8080/api/v1/docs.

---

🐳 Running with Docker

# Build and start
make docker-up

# Stop
make docker-down

Note

The Docker setup uses a multi-stage build:

1. Builder — compiles the API binary and the migrator, generates Swagger docs
2. Runtime — minimal Alpine image with only the compiled binaries

---

🧪 Testing

# Run all tests with race detector
make test

# Generate HTML coverage report
make cover

📐 API Endpoints

🏥 Health

Method	Path	Description
GET	/api/v1/health	Returns service health status

📦 Stocks

Method	Path	Description
GET	/api/v1/stocks	List all stocks
POST	/api/v1/stocks	Create a new stock
GET	/api/v1/stocks/:id	Get a stock by ID
PUT	/api/v1/stocks/:id	Update a stock
DELETE	/api/v1/stocks/:id	Delete a stock

🛍️ Products

Method	Path	Description
GET	/api/v1/products	List all products
POST	/api/v1/products	Create a new product
GET	/api/v1/products/:id	Get a product by ID
GET	/api/v1/products/stock/:stock_id	List products by stock
PUT	/api/v1/products/:id	Update a product
DELETE	/api/v1/products/:id	Delete a product

Full request/response schemas are available in the Swagger UI at /api/v1/docs.

🗄️ Database Migrations

The project ships a standalone migrator binary with the following commands:

make migrate-init    # Initialize the migrations table
make migrate-up      # Apply pending migrations
make migrate-down    # Roll back the last migration
make migrate-create  # Scaffold a new migration file

🧹 Development Utilities

make fmt       # Format all Go files
make vet       # Run go vet
make lint      # Install and run golangci-lint
make tidy      # Tidy go.mod / go.sum
make mock      # Regenerate mocks with mockgen
make swagger   # Regenerate Swagger docs
make clean     # Remove build artifacts and coverage files

🔄 CI/CD

GitHub Actions workflows are currently manual-only because account billing limits can make hosted runs fail before project checks execute. Until hosted CI is available again, validate changes locally before pushing:

go test ./...
go test -cover ./internal/core/service/... ./internal/in/http/api/handlers/... ./internal/out/database/sql/repository/handlers/...
go vet ./...

When Actions are enabled again, the CI workflow covers:

1. golangci-lint — static analysis
2. govulncheck — vulnerability scanning
3. tests — make test

Dependabot is configured to keep DevContainer features up to date weekly.

🧑‍💻 Dev Container

A fully configured Dev Container is included for VS Code and GitHub Codespaces, based on the official go:2-1.26-trixie image and featuring:

• Fish shell
• Docker-outside-of-Docker
• act for running GitHub Actions locally

📄 License

This project is licensed under the MIT License.

_{Built with ❤️ using Go & Hexagonal Architecture}