Delivery Hubs Service

A lightweight, production-ready Golang HTTP backend for managing delivery location hubs.
It supports full CRUD operations on hubs with polygon boundaries, real-time location validation (point-in-polygon), and automatic convex hull computation for optimal delivery zone boundaries — all backed by SQLite.

Built with clean architecture (Gin + GORM) and optimized for delivery management systems.

✨ Features

• Full CRUD for Delivery Hubs (single or multiple polygons per hub)
• Location Checking – POST /check-locations returns whether each point falls inside any hub’s polygon(s)
• Convex Hull Endpoint – POST /boundary-polygon computes the minimal enclosing polygon using Andrew’s Monotone Chain
• Bearer Token Authentication (simple secret-token for demo/production)
• SQLite Persistence with automatic migrations
• Health Check endpoint
• Input Validation & meaningful error messages
• GeoJSON-ready polygons (closed, counter-clockwise)
• Handles edge cases: collinear points, degenerate hulls, boundary points

🛠 Tech Stack

• Language: Go (1.21+)
• Framework: Gin
• ORM / DB: GORM + SQLite
• Convex Hull: Andrew’s Monotone Chain (O(n log n))
• Point-in-Polygon: Ray Casting (Jordan curve) with boundary support
• Testing: testing + httptest

🚀 Quick Start

1. Clone & Install

git clone <your-repo>
cd delivery-hubs-service
go mod tidy

2. Run the Server

go run main.go --command start

Server starts at http://localhost:8080

3. Test Health

curl -X GET http://localhost:8080/health

🔑 Authentication

All endpoints except /health require:

-H "Authorization: Bearer secret-token"

📋 API Endpoints Overview

Delivery Hubs CRUD (/delivery-hubs)

• POST – Create hub (single or multi-polygon)
• GET – List all or filter by ?business_id=xxx
• GET /:id – Get single hub
• PUT /:id – Partial update
• DELETE /:id – Delete hub

Detailed docs: delivery-hubs-api-tests.md

Check Locations (POST /check-locations)

Check multiple delivery points against all hubs for a business.
Returns found: true/false + full hub data when inside.

Detailed docs: check-locations.md

Boundary Polygon (Convex Hull) (POST /boundary-polygon)

Computes the minimal convex hull from any set of coordinates.
Perfect for generating optimized delivery zones.

Detailed docs: boundary-polygon.md

📁 Project Structure

delivery-hubs-service/
├── main.go
├── internal/
│   ├── models/
│   ├── repository/
│   ├── service/
│   ├── handler/
│   └── middleware/
├── docs/
│   ├── delivery-hubs-api-tests.md
│   ├── check-locations.md
│   └── boundary-polygon.md
└── go.mod

🧪 Testing

Run the complete test flows provided in the documentation files:

1. Health check
2. Create → List → Get → Update → Delete hubs
3. Check locations (inside/outside)
4. Boundary polygon (normal + degenerate cases)

All curl examples are ready to copy-paste.

📝 Important Notes

• Polygons must be closed (first = last coordinate)
• Minimum 3 points per polygon
• Collinear points are automatically filtered in convex hull
• The service is designed to work with the convex hull + convex-optimized PIP combination for maximum performance

🔧 Future Enhancements (ready for extension)

• Add PostgreSQL support
• GeoJSON response format
• Multi-tenant business isolation
• Rate limiting & JWT auth
• Docker & Kubernetes manifests

📄 License

MIT – feel free to use, modify, and deploy in production.

---

Made for delivery optimization
Questions or contributions? Open an issue or PR!

Happy delivering! 🚀