feat(api): add complete backend infrastructure with Go/Gin REST API

Implement comprehensive backend system including:
- RESTful API with Gin framework and JWT authentication
- PostgreSQL database models for shipments, assets, events, and digital passports
- Docker containerization with multi-stage builds
- Blockchain integration support for supply chain tracking
- Real-time monitoring with geofencing capabilities
- Organization-based multi-tenancy
- Complete CRUD operations for all entities
- Webhook endpoints for IoT data ingestion
- Development tooling with Makefile and docker-compose

The API provides endpoints for:
- User authentication and authorization
- Shipment tracking and management
- Asset monitoring with IoT integration
- Digital Product Passports (DPP)
- Geofence zones and alerts
- Dashboard analytics and metrics

Author: tufstraka

api/Dockerfile

@@ -0,0 +1,41 @@
+# Build stage
+FROM golang:1.21-alpine AS builder
+
+# Install build dependencies
+RUN apk add --no-cache git
+
+# Set working directory
+WORKDIR /app
+
+# Copy go mod files
+COPY go.mod go.sum ./
+
+# Download dependencies
+RUN go mod download
+
+# Copy source code
+COPY . .
+
+# Build the application
+RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o main .
+
+# Final stage
+FROM alpine:latest
+
+# Install runtime dependencies
+RUN apk --no-cache add ca-certificates tzdata
+
+# Set working directory
+WORKDIR /root/
+
+# Copy the binary from builder
+COPY --from=builder /app/main .
+
+# Copy environment file (optional)
+COPY --from=builder /app/.env.example .env.example
+
+# Expose port
+EXPOSE 8080
+
+# Run the application
+CMD ["./main"]

api/Makefile

@@ -0,0 +1,94 @@
+.PHONY: help run build test clean docker-up docker-down docker-build migrate dev prod
+
+# Colors for output
+GREEN  := $(shell tput -Txterm setaf 2)
+YELLOW := $(shell tput -Txterm setaf 3)
+WHITE  := $(shell tput -Txterm setaf 7)
+RESET  := $(shell tput -Txterm sgr0)
+
+# Default target
+help: ## Show this help message
+	@echo ''
+	@echo 'Usage:'
+	@echo '  ${YELLOW}make${RESET} ${GREEN}<target>${RESET}'
+	@echo ''
+	@echo 'Targets:'
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  ${YELLOW}%-15s${GREEN}%s${RESET}\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+run: ## Run the application locally
+	go run main.go
+
+build: ## Build the application
+	go build -o bin/locsafe-api main.go
+
+test: ## Run tests
+	go test -v ./...
+
+test-coverage: ## Run tests with coverage
+	go test -v -cover ./...
+
+clean: ## Clean build artifacts
+	rm -rf bin/
+	go clean
+
+deps: ## Download dependencies
+	go mod download
+	go mod tidy
+
+docker-up: ## Start Docker containers
+	docker-compose up -d
+
+docker-down: ## Stop Docker containers
+	docker-compose down
+
+docker-build: ## Build Docker image
+	docker build -t locsafe-api:latest .
+
+docker-logs: ## View Docker logs
+	docker-compose logs -f
+
+migrate: ## Run database migrations
+	go run main.go migrate
+
+seed: ## Seed database with sample data
+	go run main.go seed
+
+dev: ## Start development environment
+	@echo "${GREEN}Starting development environment...${RESET}"
+	docker-compose up -d postgres redis
+	@sleep 3
+	go run main.go
+
+prod: docker-build ## Build and run production environment
+	@echo "${GREEN}Starting production environment...${RESET}"
+	docker-compose -f docker-compose.yml up -d
+
+fmt: ## Format code
+	go fmt ./...
+	gofmt -s -w .
+
+lint: ## Run linter
+	golangci-lint run
+
+vet: ## Run go vet
+	go vet ./...
+
+security: ## Run security checks
+	gosec ./...
+
+swagger: ## Generate Swagger documentation
+	swag init -g main.go
+
+db-reset: ## Reset database
+	docker-compose down postgres
+	docker volume rm locsafe_postgres_data
+	docker-compose up -d postgres
+	@sleep 5
+	go run main.go migrate
+
+install-tools: ## Install development tools
+	go install github.com/swaggo/swag/cmd/swag@latest
+	go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
+	go install github.com/securego/gosec/v2/cmd/gosec@latest
+
+.DEFAULT_GOAL := help

api/config/database.go

@@ -0,0 +1,57 @@
+package config
+
+import (
+	"fmt"
+	"os"
+
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+// InitDB initializes and returns a database connection
+func InitDB() (*gorm.DB, error) {
+	dsn := fmt.Sprintf(
+		"host=%s user=%s password=%s dbname=%s port=%s sslmode=%s TimeZone=UTC",
+		getEnv("DB_HOST", "localhost"),
+		getEnv("DB_USER", "postgres"),
+		getEnv("DB_PASSWORD", "postgres"),
+		getEnv("DB_NAME", "locsafe"),
+		getEnv("DB_PORT", "5432"),
+		getEnv("DB_SSLMODE", "disable"),
+	)
+
+	config := &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Info),
+	}
+
+	// In production, reduce logging
+	if os.Getenv("APP_ENV") == "production" {
+		config.Logger = logger.Default.LogMode(logger.Error)
+	}
+
+	db, err := gorm.Open(postgres.Open(dsn), config)
+	if err != nil {
+		return nil, fmt.Errorf("failed to connect to database: %w", err)
+	}
+
+	// Configure connection pool
+	sqlDB, err := db.DB()
+	if err != nil {
+		return nil, fmt.Errorf("failed to get database instance: %w", err)
+	}
+
+	// Set connection pool settings
+	sqlDB.SetMaxIdleConns(10)
+	sqlDB.SetMaxOpenConns(100)
+
+	return db, nil
+}
+
+// getEnv gets an environment variable with a fallback value
+func getEnv(key, fallback string) string {
+	if value, exists := os.LookupEnv(key); exists {
+		return value
+	}
+	return fallback
+}

api/docker-compose.yml

@@ -0,0 +1,75 @@
+version: '3.8'
+
+services:
+  postgres:
+    image: postgres:15-alpine
+    container_name: locsafe-postgres
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: locsafe
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
+    networks:
+      - locsafe-network
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    container_name: locsafe-redis
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+    networks:
+      - locsafe-network
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: locsafe-api
+    environment:
+      APP_ENV: development
+      PORT: 8080
+      DB_HOST: postgres
+      DB_PORT: 5432
+      DB_USER: postgres
+      DB_PASSWORD: postgres
+      DB_NAME: locsafe
+      DB_SSLMODE: disable
+      REDIS_HOST: redis
+      REDIS_PORT: 6379
+      JWT_SECRET: jwt-key
+    ports:
+      - "8080:8080"
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    volumes:
+      - ./:/app
+    networks:
+      - locsafe-network
+    restart: unless-stopped
+
+volumes:
+  postgres_data:
+  redis_data:
+
+networks:
+  locsafe-network:
+    driver: bridge

api/go.mod

@@ -0,0 +1,48 @@
+module github.com/tufstraka/Locsafe/api
+
+go 1.21
+
+require (
+	github.com/gin-contrib/cors v1.5.0
+	github.com/gin-gonic/gin v1.9.1
+	github.com/golang-jwt/jwt/v5 v5.2.0
+	github.com/google/uuid v1.5.0
+	github.com/joho/godotenv v1.5.1
+	github.com/lib/pq v1.10.9
+	golang.org/x/crypto v0.19.0
+	gorm.io/driver/postgres v1.5.4
+	gorm.io/gorm v1.25.5
+)
+
+require (
+	github.com/bytedance/sonic v1.10.1 // indirect
+	github.com/chenzhuoyu/base64x v0.0.0-20230717121745-296ad89f973d // indirect
+	github.com/chenzhuoyu/iasm v0.9.0 // indirect
+	github.com/gabriel-vasile/mimetype v1.4.2 // indirect
+	github.com/gin-contrib/sse v0.1.0 // indirect
+	github.com/go-playground/locales v0.14.1 // indirect
+	github.com/go-playground/universal-translator v0.18.1 // indirect
+	github.com/go-playground/validator/v10 v10.15.5 // indirect
+	github.com/goccy/go-json v0.10.2 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a // indirect
+	github.com/jackc/pgx/v5 v5.4.3 // indirect
+	github.com/jinzhu/inflection v1.0.0 // indirect
+	github.com/jinzhu/now v1.1.5 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/klauspost/cpuid/v2 v2.2.5 // indirect
+	github.com/kr/text v0.2.0 // indirect
+	github.com/leodido/go-urn v1.2.4 // indirect
+	github.com/mattn/go-isatty v0.0.19 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/pelletier/go-toml/v2 v2.1.0 // indirect
+	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
+	github.com/ugorji/go/codec v1.2.11 // indirect
+	golang.org/x/arch v0.5.0 // indirect
+	golang.org/x/net v0.16.0 // indirect
+	golang.org/x/sys v0.17.0 // indirect
+	golang.org/x/text v0.14.0 // indirect
+	google.golang.org/protobuf v1.31.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)