feat: initial open-source release of Pipely

OTA update server designed for high-concurrency, low-bandwidth deployments.
GORM-backed PostgreSQL, JWT auth, device management, artefact versioning,
deployment rollout with gated rate-limited downloads, and a React admin panel.

internal/artefact/handler.go

@@ -0,0 +1,137 @@
+package artefact
+
+import (
+	"crypto/sha256"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"onixbyte.com/message-converter-manifest/internal/database"
+	"onixbyte.com/message-converter-manifest/internal/model"
+)
+
+type Handler struct {
+	db          *gorm.DB
+	artefactDir string
+}
+
+func NewHandler(db *gorm.DB, artefactDir string) *Handler {
+	return &Handler{db: db, artefactDir: artefactDir}
+}
+
+func (h *Handler) Upload(c *gin.Context) {
+	version := c.PostForm("version")
+	if version == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "version is required"})
+		return
+	}
+
+	deltaRef := c.PostForm("deltaRef")
+	metadata := c.PostForm("metadata")
+	if metadata == "" {
+		metadata = "{}"
+	}
+
+	file, header, err := c.Request.FormFile("file")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "file is required: " + err.Error()})
+		return
+	}
+	defer file.Close()
+
+	destDir := filepath.Join(h.artefactDir, version)
+	if err := os.MkdirAll(destDir, 0755); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to create directory"})
+		return
+	}
+
+	destPath := filepath.Join(destDir, header.Filename)
+	out, err := os.Create(destPath)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to create file"})
+		return
+	}
+	defer out.Close()
+
+	hasher := sha256.New()
+	writer := io.MultiWriter(out, hasher)
+
+	size, err := io.Copy(writer, file)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to write file"})
+		return
+	}
+
+	sha256Hash := fmt.Sprintf("%x", hasher.Sum(nil))
+
+	artefact := &model.Artefact{
+		Version:    version,
+		FileName:   header.Filename,
+		FilePath:   destPath,
+		FileSize:   size,
+		SHA256Hash: sha256Hash,
+		DeltaRef:   deltaRef,
+		IsDelta:    deltaRef != "",
+		Metadata:   metadata,
+	}
+
+	if err := database.CreateArtefact(h.db, artefact); err != nil {
+		os.Remove(destPath)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to save artefact: " + err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusCreated, artefact)
+}
+
+func (h *Handler) List(c *gin.Context) {
+	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+	pageSize, _ := strconv.Atoi(c.DefaultQuery("pageSize", "20"))
+
+	if page < 1 {
+		page = 1
+	}
+	if pageSize < 1 || pageSize > 100 {
+		pageSize = 20
+	}
+
+	artefacts, total, err := database.ListArtefacts(h.db, page, pageSize)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, model.PaginatedResponse{
+		Data:     artefacts,
+		Total:    total,
+		Page:     page,
+		PageSize: pageSize,
+	})
+}
+
+func (h *Handler) Get(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid id"})
+		return
+	}
+
+	artefact, err := database.GetArtefactByID(h.db, id)
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			c.JSON(http.StatusNotFound, gin.H{"error": "Artefact not found"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, artefact)
+}

internal/auth/admin_handler.go

@@ -0,0 +1,93 @@
+package auth
+
+import (
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+	"onixbyte.com/message-converter-manifest/internal/model"
+)
+
+// -- Admin user management handlers --
+
+type CreateUserRequest struct {
+	Username string `json:"username" binding:"required"`
+	Password string `json:"password" binding:"required"`
+	Role     string `json:"role"`
+}
+
+type ChangePasswordRequest struct {
+	NewPassword string `json:"newPassword" binding:"required"`
+}
+
+// ListUsers handles GET /admin/users.
+func (h *Handler) ListUsers(c *gin.Context) {
+	users, err := h.svc.ListUsers()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if users == nil {
+		users = []model.AdminUser{}
+	}
+	c.JSON(http.StatusOK, gin.H{"data": users})
+}
+
+// CreateUser handles POST /admin/users.
+func (h *Handler) CreateUser(c *gin.Context) {
+	var req CreateUserRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	user, err := h.svc.CreateUser(req.Username, req.Password, req.Role)
+	if err != nil {
+		if err == ErrUserExists {
+			c.JSON(http.StatusConflict, gin.H{"error": "Username already exists"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusCreated, user)
+}
+
+// DeleteUser handles DELETE /admin/users/:id.
+func (h *Handler) DeleteUser(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid id"})
+		return
+	}
+
+	if err := h.svc.DeleteUser(id); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"status": "deleted"})
+}
+
+// ChangePassword handles PUT /admin/users/:id/password.
+func (h *Handler) ChangePassword(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid id"})
+		return
+	}
+
+	var req ChangePasswordRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	if err := h.svc.ChangePassword(id, req.NewPassword); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"status": "password changed"})
+}

internal/auth/handler.go

@@ -0,0 +1,32 @@
+package auth
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"onixbyte.com/message-converter-manifest/internal/model"
+)
+
+type Handler struct {
+	svc *Service
+}
+
+func NewHandler(svc *Service) *Handler {
+	return &Handler{svc: svc}
+}
+
+func (h *Handler) Login(c *gin.Context) {
+	var req model.LoginRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid request: " + err.Error()})
+		return
+	}
+
+	resp, err := h.svc.Login(req.Username, req.Password)
+	if err != nil {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid credentials"})
+		return
+	}
+
+	c.JSON(http.StatusOK, resp)
+}

internal/auth/repositoriy.go

@@ -0,0 +1,4 @@
+package auth
+
+// Repository functions are in internal/database/repository.go (AdminUser methods).
+// This file exists to satisfy the package structure for future auth-specific queries.

internal/auth/service.go

@@ -0,0 +1,155 @@
+package auth
+
+import (
+	"crypto/sha256"
+	"crypto/subtle"
+	"encoding/hex"
+	"errors"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+	"gorm.io/gorm"
+
+	"onixbyte.com/message-converter-manifest/internal/database"
+	"onixbyte.com/message-converter-manifest/internal/model"
+)
+
+var (
+	ErrInvalidCredentials = errors.New("invalid username or password")
+	ErrUserExists         = errors.New("username already exists")
+)
+
+type Service struct {
+	db     *gorm.DB
+	secret []byte
+	expiry time.Duration
+}
+
+func NewService(db *gorm.DB, secret []byte, expiryHrs int) *Service {
+	return &Service{
+		db:     db,
+		secret: secret,
+		expiry: time.Duration(expiryHrs) * time.Hour,
+	}
+}
+
+func (s *Service) Login(username, password string) (*model.LoginResponse, error) {
+	user, err := database.GetAdminUserByUsername(s.db, username)
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, ErrInvalidCredentials
+		}
+		return nil, err
+	}
+
+	hash := hashPassword(password)
+	if subtle.ConstantTimeCompare([]byte(hash), []byte(user.PasswordHash)) != 1 {
+		return nil, ErrInvalidCredentials
+	}
+
+	token, expiresAt, err := s.generateToken(user)
+	if err != nil {
+		return nil, err
+	}
+
+	return &model.LoginResponse{
+		Token:     token,
+		ExpiresAt: expiresAt,
+	}, nil
+}
+
+func (s *Service) CreateInitialAdmin(username, password string) error {
+	_, err := database.GetAdminUserByUsername(s.db, username)
+	if err == nil {
+		return nil // admin already exists
+	}
+
+	user := &model.AdminUser{
+		Username:     username,
+		PasswordHash: hashPassword(password),
+		Role:         "admin",
+	}
+	return s.db.Transaction(func(tx *gorm.DB) error {
+		return database.CreateAdminUser(tx, user)
+	})
+}
+
+func (s *Service) ValidateToken(tokenString string) (*model.AdminUser, error) {
+	token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
+		if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
+			return nil, errors.New("unexpected signing method")
+		}
+		return s.secret, nil
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	claims, ok := token.Claims.(jwt.MapClaims)
+	if !ok || !token.Valid {
+		return nil, errors.New("invalid token")
+	}
+
+	username, _ := claims["sub"].(string)
+	if username == "" {
+		return nil, errors.New("invalid token subject")
+	}
+
+	return database.GetAdminUserByUsername(s.db, username)
+}
+
+func (s *Service) generateToken(user *model.AdminUser) (string, int64, error) {
+	expiresAt := time.Now().Add(s.expiry)
+	claims := jwt.MapClaims{
+		"sub":  user.Username,
+		"role": user.Role,
+		"iat":  time.Now().Unix(),
+		"exp":  expiresAt.Unix(),
+	}
+
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
+	tokenStr, err := token.SignedString(s.secret)
+	if err != nil {
+		return "", 0, err
+	}
+
+	return tokenStr, expiresAt.Unix(), nil
+}
+
+func hashPassword(password string) string {
+	h := sha256.Sum256([]byte(password))
+	return hex.EncodeToString(h[:])
+}
+
+func (s *Service) ListUsers() ([]model.AdminUser, error) {
+	return database.ListAdminUsers(s.db)
+}
+
+func (s *Service) CreateUser(username, password, role string) (*model.AdminUser, error) {
+	_, err := database.GetAdminUserByUsername(s.db, username)
+	if err == nil {
+		return nil, ErrUserExists
+	}
+
+	if role == "" {
+		role = "admin"
+	}
+
+	user := &model.AdminUser{
+		Username:     username,
+		PasswordHash: hashPassword(password),
+		Role:         role,
+	}
+	if err := database.CreateAdminUser(s.db, user); err != nil {
+		return nil, err
+	}
+	return user, nil
+}
+
+func (s *Service) DeleteUser(id int64) error {
+	return database.DeleteAdminUser(s.db, id)
+}
+
+func (s *Service) ChangePassword(id int64, newPassword string) error {
+	return database.UpdateAdminPassword(s.db, id, hashPassword(newPassword))
+}

internal/config/config.go

@@ -0,0 +1,54 @@
+package config
+
+import (
+	"log"
+	"os"
+	"strconv"
+
+	"github.com/joho/godotenv"
+)
+
+type Config struct {
+	ServerPort    string
+	JWTSecret     string
+	JWTExpiryHrs  int
+	DatabaseURL   string
+	ArtefactDir   string
+	MaxConcurrent int
+	BandwidthBPS  int
+	RateLimitRPS  int
+}
+
+func Load() *Config {
+	// Load .env file if present (silently ignore if not found)
+	if err := godotenv.Load(); err != nil {
+		log.Println("[config] No .env file found, using system environment variables")
+	}
+
+	return &Config{
+		ServerPort:    envOrDefault("SERVER_PORT", "8080"),
+		JWTSecret:     envOrDefault("JWT_SECRET", "change-me-in-production"),
+		JWTExpiryHrs:  envOrDefaultInt("JWT_EXPIRY_HRS", 24),
+		DatabaseURL:   envOrDefault("DATABASE_URL", "postgres://postgres:postgres@localhost:5432/manifest?sslmode=disable"),
+		ArtefactDir:   envOrDefault("ARTEFACT_DIR", "/var/ota/artefacts"),
+		MaxConcurrent: envOrDefaultInt("MAX_CONCURRENT_DOWNLOADS", 50),
+		BandwidthBPS:  envOrDefaultInt("BANDWIDTH_BPS", 10*1024*1024/50),
+		RateLimitRPS:  envOrDefaultInt("RATE_LIMIT_RPS", 100),
+	}
+}
+
+func envOrDefault(key, def string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return def
+}
+
+func envOrDefaultInt(key string, def int) int {
+	if v := os.Getenv(key); v != "" {
+		if n, err := strconv.Atoi(v); err == nil {
+			return n
+		}
+	}
+	return def
+}

internal/database/database.go

@@ -0,0 +1,83 @@
+package database
+
+import (
+	"fmt"
+	"log"
+	"net/url"
+	"strings"
+
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+
+	"onixbyte.com/message-converter-manifest/internal/model"
+)
+
+// Connect opens a PostgreSQL connection via GORM. If the target database does
+// not exist it is created automatically. Tables are then migrated.
+func Connect(databaseURL string) (*gorm.DB, error) {
+	dbName, err := ensureDatabase(databaseURL)
+	if err != nil {
+		return nil, err
+	}
+
+	db, err := gorm.Open(postgres.Open(databaseURL), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Warn),
+	})
+	if err != nil {
+		return nil, fmt.Errorf("failed to open database: %w", err)
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		return nil, fmt.Errorf("failed to get underlying sql.DB: %w", err)
+	}
+	sqlDB.SetMaxOpenConns(50)
+	sqlDB.SetMaxIdleConns(10)
+
+	log.Printf("[database] Connected to PostgreSQL database: %s", dbName)
+	return db, nil
+}
+
+// AutoMigrate creates or updates tables to match the model definitions.
+func AutoMigrate(db *gorm.DB) error {
+	return db.AutoMigrate(
+		&model.AdminUser{},
+		&model.Device{},
+		&model.Artefact{},
+		&model.Deployment{},
+		&model.DeploymentDevice{},
+	)
+}
+
+// ensureDatabase creates the target database if it does not exist.
+func ensureDatabase(databaseURL string) (string, error) {
+	u, err := url.Parse(databaseURL)
+	if err != nil {
+		return "", fmt.Errorf("invalid database URL: %w", err)
+	}
+	dbName := strings.TrimPrefix(u.Path, "/")
+
+	adminURL := *u
+	adminURL.Path = "/postgres"
+
+	db, err := gorm.Open(postgres.Open(adminURL.String()), &gorm.Config{})
+	if err != nil {
+		return "", fmt.Errorf("failed to connect to admin database: %w", err)
+	}
+
+	var exists bool
+	db.Raw("SELECT EXISTS(SELECT 1 FROM pg_database WHERE datname = ?)", dbName).Scan(&exists)
+	if !exists {
+		if err := db.Exec(fmt.Sprintf(`CREATE DATABASE "%s"`, dbName)).Error; err != nil {
+			return "", fmt.Errorf("failed to create database %s: %w", dbName, err)
+		}
+		log.Printf("[database] Created database: %s", dbName)
+	}
+
+	sqlDB, _ := db.DB()
+	if sqlDB != nil {
+		sqlDB.Close()
+	}
+	return dbName, nil
+}

internal/database/repository.go

@@ -0,0 +1,242 @@
+package database
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"onixbyte.com/message-converter-manifest/internal/model"
+)
+
+// -- Admin Users --
+
+func CreateAdminUser(db *gorm.DB, u *model.AdminUser) error {
+	return db.Create(u).Error
+}
+
+func GetAdminUserByUsername(db *gorm.DB, username string) (*model.AdminUser, error) {
+	var u model.AdminUser
+	err := db.Where("username = ?", username).First(&u).Error
+	if err != nil {
+		return nil, err
+	}
+	return &u, nil
+}
+
+func ListAdminUsers(db *gorm.DB) ([]model.AdminUser, error) {
+	var users []model.AdminUser
+	err := db.Order("created_at").Find(&users).Error
+	return users, err
+}
+
+func DeleteAdminUser(db *gorm.DB, id int64) error {
+	return db.Delete(&model.AdminUser{}, id).Error
+}
+
+func UpdateAdminPassword(db *gorm.DB, id int64, passwordHash string) error {
+	return db.Model(&model.AdminUser{}).Where("id = ?", id).
+		Update("password_hash", passwordHash).Error
+}
+
+// -- Devices --
+
+func UpsertDevice(db *gorm.DB, d *model.Device) error {
+	return db.Clauses(clause.OnConflict{
+		Columns:   []clause.Column{{Name: "device_id"}},
+		DoUpdates: clause.AssignmentColumns([]string{"ip_address", "hostname", "os", "current_version", "status", "group_name", "last_heartbeat", "updated_at"}),
+	}).Create(d).Error
+}
+
+func UpdateDeviceHeartbeat(db *gorm.DB, deviceID, version, status string) error {
+	return db.Model(&model.Device{}).Where("device_id = ?", deviceID).
+		Updates(map[string]interface{}{
+			"current_version": version,
+			"status":          status,
+			"last_heartbeat":  time.Now(),
+		}).Error
+}
+
+func GetDeviceByID(db *gorm.DB, deviceID string) (*model.Device, error) {
+	var d model.Device
+	err := db.Where("device_id = ?", deviceID).First(&d).Error
+	if err != nil {
+		return nil, err
+	}
+	return &d, nil
+}
+
+func ListDevices(db *gorm.DB, status, group string, page, pageSize int) ([]model.Device, int64, error) {
+	var devices []model.Device
+	var total int64
+
+	q := db.Model(&model.Device{})
+	if status != "" {
+		q = q.Where("status = ?", status)
+	}
+	if group != "" {
+		q = q.Where("group_name = ?", group)
+	}
+
+	if err := q.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	err := q.Order("last_heartbeat DESC").Offset((page - 1) * pageSize).Limit(pageSize).Find(&devices).Error
+	return devices, total, err
+}
+
+func GetOfflineDevices(db *gorm.DB, threshold time.Duration) ([]model.Device, error) {
+	var devices []model.Device
+	err := db.Where("last_heartbeat < ? AND status = ?", time.Now().Add(-threshold), model.DeviceStatusOnline).
+		Find(&devices).Error
+	return devices, err
+}
+
+func MarkDevicesOffline(db *gorm.DB, deviceIDs []string) error {
+	return db.Model(&model.Device{}).Where("device_id IN ?", deviceIDs).
+		Update("status", model.DeviceStatusOffline).Error
+}
+
+// -- Artefacts --
+
+func CreateArtefact(db *gorm.DB, a *model.Artefact) error {
+	return db.Create(a).Error
+}
+
+func GetArtefactByID(db *gorm.DB, id int64) (*model.Artefact, error) {
+	var a model.Artefact
+	err := db.First(&a, id).Error
+	if err != nil {
+		return nil, err
+	}
+	return &a, nil
+}
+
+func GetArtefactByVersion(db *gorm.DB, version string) (*model.Artefact, error) {
+	var a model.Artefact
+	err := db.Where("version = ?", version).Order("created_at DESC").First(&a).Error
+	if err != nil {
+		return nil, err
+	}
+	return &a, nil
+}
+
+func ListArtefacts(db *gorm.DB, page, pageSize int) ([]model.Artefact, int64, error) {
+	var artefacts []model.Artefact
+	var total int64
+
+	db.Model(&model.Artefact{}).Count(&total)
+	err := db.Order("created_at DESC").Offset((page - 1) * pageSize).Limit(pageSize).Find(&artefacts).Error
+	return artefacts, total, err
+}
+
+// -- Deployments --
+
+func CreateDeployment(db *gorm.DB, d *model.Deployment) error {
+	return db.Create(d).Error
+}
+
+func GetDeploymentByID(db *gorm.DB, id int64) (*model.Deployment, error) {
+	var d model.Deployment
+	err := db.Preload("Artefact").First(&d, id).Error
+	if err != nil {
+		return nil, err
+	}
+	return &d, nil
+}
+
+func ListDeployments(db *gorm.DB, status string, page, pageSize int) ([]model.Deployment, int64, error) {
+	var deployments []model.Deployment
+	var total int64
+
+	q := db.Model(&model.Deployment{})
+	if status != "" {
+		q = q.Where("status = ?", status)
+	}
+
+	if err := q.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	err := q.Preload("Artefact").Order("created_at DESC").
+		Offset((page - 1) * pageSize).Limit(pageSize).Find(&deployments).Error
+	return deployments, total, err
+}
+
+func UpdateDeploymentStatus(db *gorm.DB, id int64, status string) error {
+	return db.Model(&model.Deployment{}).Where("id = ?", id).Update("status", status).Error
+}
+
+// -- Deployment Devices --
+
+func CreateDeploymentDevices(db *gorm.DB, deploymentID int64, deviceIDs []string) error {
+	devices := make([]model.DeploymentDevice, len(deviceIDs))
+	for i, did := range deviceIDs {
+		devices[i] = model.DeploymentDevice{DeploymentID: deploymentID, DeviceID: did, Status: model.DeployDeviceStatusPending}
+	}
+	return db.Clauses(clause.OnConflict{DoNothing: true}).Create(&devices).Error
+}
+
+func GetActiveDeploymentForDevice(db *gorm.DB, deviceID string) (*model.Deployment, *model.Artefact, error) {
+	var dd model.DeploymentDevice
+	err := db.Where("device_id = ? AND status = ?", deviceID, model.DeployDeviceStatusPending).
+		Preload("Deployment.Artefact").First(&dd).Error
+	if err != nil {
+		return nil, nil, err
+	}
+
+	var d model.Deployment
+	db.Preload("Artefact").First(&d, dd.DeploymentID)
+	if d.Status != model.DeploymentStatusActive {
+		return nil, nil, gorm.ErrRecordNotFound
+	}
+	return &d, d.Artefact, nil
+}
+
+func UpdateDeploymentDeviceStatus(db *gorm.DB, deploymentID int64, deviceID, status, errMsg string) error {
+	updates := map[string]interface{}{"status": status, "error": errMsg}
+	now := time.Now()
+	if status == model.DeployDeviceStatusDownloaded {
+		updates["downloaded_at"] = &now
+	}
+	if status == model.DeployDeviceStatusCompleted || status == model.DeployDeviceStatusFailed {
+		updates["completed_at"] = &now
+	}
+	return db.Model(&model.DeploymentDevice{}).
+		Where("deployment_id = ? AND device_id = ?", deploymentID, deviceID).
+		Updates(updates).Error
+}
+
+func GetDeploymentDeviceStats(db *gorm.DB, deploymentID int64) (map[string]int64, error) {
+	type row struct {
+		Status string
+		Count  int64
+	}
+	var rows []row
+	if err := db.Model(&model.DeploymentDevice{}).
+		Select("status, COUNT(*) as count").
+		Where("deployment_id = ?", deploymentID).
+		Group("status").Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+	stats := map[string]int64{}
+	for _, r := range rows {
+		stats[r.Status] = r.Count
+	}
+	return stats, nil
+}
+
+func GetDeploymentDevices(db *gorm.DB, deploymentID int64, status string, page, pageSize int) ([]model.DeploymentDevice, int64, error) {
+	var devices []model.DeploymentDevice
+	var total int64
+
+	q := db.Model(&model.DeploymentDevice{}).Where("deployment_id = ?", deploymentID)
+	if status != "" {
+		q = q.Where("status = ?", status)
+	}
+
+	q.Count(&total)
+	err := q.Order("created_at").Offset((page - 1) * pageSize).Limit(pageSize).Find(&devices).Error
+	return devices, total, err
+}

internal/delta/handler.go

@@ -0,0 +1,85 @@
+package delta
+
+import (
+	"net/http"
+	"os"
+	"path/filepath"
+
+	"github.com/gin-gonic/gin"
+)
+
+// Handler provides delta patch generation for JAR artefacts.
+type Handler struct {
+	artefactDir string
+}
+
+func NewHandler(artefactDir string) *Handler {
+	return &Handler{artefactDir: artefactDir}
+}
+
+// GenerateDelta creates a delta patch between two artefact versions.
+// POST /api/v1/delta/generate
+// Form fields: oldVersion, newVersion
+func (h *Handler) GenerateDelta(c *gin.Context) {
+	oldVersion := c.PostForm("oldVersion")
+	newVersion := c.PostForm("newVersion")
+	if oldVersion == "" || newVersion == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "oldVersion and newVersion are required"})
+		return
+	}
+
+	oldDir := filepath.Join(h.artefactDir, oldVersion)
+	newDir := filepath.Join(h.artefactDir, newVersion)
+
+	if _, err := os.Stat(oldDir); os.IsNotExist(err) {
+		c.JSON(http.StatusNotFound, gin.H{"error": "Old version not found: " + oldVersion})
+		return
+	}
+	if _, err := os.Stat(newDir); os.IsNotExist(err) {
+		c.JSON(http.StatusNotFound, gin.H{"error": "New version not found: " + newVersion})
+		return
+	}
+
+	// Find JAR files in each version directory
+	oldJar, err := findJarInDir(oldDir)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "No JAR found in old version: " + err.Error()})
+		return
+	}
+	newJar, err := findJarInDir(newDir)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "No JAR found in new version: " + err.Error()})
+		return
+	}
+
+	patchPath := filepath.Join(h.artefactDir, "patches", oldVersion+"-to-"+newVersion+".patch")
+	if err := os.MkdirAll(filepath.Dir(patchPath), 0755); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to create patch directory"})
+		return
+	}
+
+	if err := GenerateJarDelta(oldJar, newJar, patchPath); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "Delta generation failed: " + err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"status":     "generated",
+		"patchPath":  patchPath,
+		"oldVersion": oldVersion,
+		"newVersion": newVersion,
+	})
+}
+
+func findJarInDir(dir string) (string, error) {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return "", err
+	}
+	for _, e := range entries {
+		if !e.IsDir() && filepath.Ext(e.Name()) == ".jar" {
+			return filepath.Join(dir, e.Name()), nil
+		}
+	}
+	return "", os.ErrNotExist
+}

internal/delta/unpacker.go

@@ -0,0 +1,230 @@
+package delta
+
+import (
+	"archive/zip"
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// PatchManifest describes the delta operations needed to transform an old JAR into a new JAR.
+type PatchManifest struct {
+	OldVersion string       `json:"oldVersion"`
+	NewVersion string       `json:"newVersion"`
+	Deleted    []string     `json:"deleted"`
+	Added      []string     `json:"added"`
+	Modified   []PatchEntry `json:"modified"`
+	Unchanged  int          `json:"unchanged"`
+}
+
+// PatchEntry represents a single modified file within the delta.
+type PatchEntry struct {
+	Path      string `json:"path"`
+	OldSHA256 string `json:"oldSha256"`
+	NewSHA256 string `json:"newSha256"`
+	DiffSize  int64  `json:"diffSize"`
+	DiffHash  string `json:"diffHash"`
+}
+
+// GenerateJarDelta produces a .patch file by comparing two JARs:
+// 1. Unzip both JARs into memory.
+// 2. Compare files; identify added, deleted, and modified entries.
+// 3. For modified .class files, generate a BSDiff-style binary diff.
+// 4. Package everything (diff chunks, new files, manifest.json) into a zip.
+func GenerateJarDelta(oldJarPath, newJarPath, patchPath string) error {
+	oldFiles, err := readJarEntries(oldJarPath)
+	if err != nil {
+		return fmt.Errorf("reading old JAR: %w", err)
+	}
+	newFiles, err := readJarEntries(newJarPath)
+	if err != nil {
+		return fmt.Errorf("reading new JAR: %w", err)
+	}
+
+	manifest := PatchManifest{
+		OldVersion: filepath.Base(oldJarPath),
+		NewVersion: filepath.Base(newJarPath),
+	}
+
+	oldSet := make(map[string][]byte)
+	for _, f := range oldFiles {
+		oldSet[f.Name] = f.Data
+	}
+	newSet := make(map[string][]byte)
+	for _, f := range newFiles {
+		newSet[f.Name] = f.Data
+	}
+
+	// Identify deleted, added, and modified files.
+	for name := range oldSet {
+		if _, ok := newSet[name]; !ok {
+			manifest.Deleted = append(manifest.Deleted, name)
+		}
+	}
+	for name := range newSet {
+		if _, ok := oldSet[name]; !ok {
+			manifest.Added = append(manifest.Added, name)
+		}
+	}
+	for name, newData := range newSet {
+		oldData, ok := oldSet[name]
+		if !ok {
+			continue
+		}
+		if !bytes.Equal(oldData, newData) {
+			entry := PatchEntry{Path: name}
+			entry.OldSHA256 = sha256Hex(oldData)
+			entry.NewSHA256 = sha256Hex(newData)
+
+			if isBinaryFile(name) {
+				diff := bsdiff(oldData, newData)
+				entry.DiffSize = int64(len(diff))
+				entry.DiffHash = sha256Hex(diff)
+			}
+
+			manifest.Modified = append(manifest.Modified, entry)
+		} else {
+			manifest.Unchanged++
+		}
+	}
+
+	return writePatchFile(patchPath, &manifest, oldFiles, newFiles, oldSet, newSet)
+}
+
+type jarEntry struct {
+	Name string
+	Data []byte
+}
+
+func readJarEntries(jarPath string) ([]jarEntry, error) {
+	data, err := os.ReadFile(jarPath)
+	if err != nil {
+		return nil, err
+	}
+
+	reader, err := zip.NewReader(bytes.NewReader(data), int64(len(data)))
+	if err != nil {
+		return nil, err
+	}
+
+	var entries []jarEntry
+	for _, f := range reader.File {
+		if f.FileInfo().IsDir() {
+			continue
+		}
+		rc, err := f.Open()
+		if err != nil {
+			return nil, err
+		}
+		content, err := io.ReadAll(rc)
+		rc.Close()
+		if err != nil {
+			return nil, err
+		}
+		entries = append(entries, jarEntry{Name: f.Name, Data: content})
+	}
+	return entries, nil
+}
+
+func isBinaryFile(name string) bool {
+	ext := strings.ToLower(filepath.Ext(name))
+	switch ext {
+	case ".class", ".jar", ".war", ".ear":
+		return true
+	}
+	return false
+}
+
+func sha256Hex(data []byte) string {
+	h := sha256.Sum256(data)
+	return hex.EncodeToString(h[:])
+}
+
+func writePatchFile(patchPath string, manifest *PatchManifest, oldFiles, newFiles []jarEntry, oldSet, newSet map[string][]byte) error {
+	out, err := os.Create(patchPath)
+	if err != nil {
+		return err
+	}
+	defer out.Close()
+
+	zw := zip.NewWriter(out)
+	defer zw.Close()
+
+	// Write manifest.json
+	manifestData, _ := json.MarshalIndent(manifest, "", "  ")
+	w, _ := zw.Create("manifest.json")
+	w.Write(manifestData)
+
+	// Write added files
+	for _, name := range manifest.Added {
+		w, _ := zw.Create("added/" + name)
+		w.Write(newSet[name])
+	}
+
+	// Write modifications (binary diffs)
+	for _, entry := range manifest.Modified {
+		if entry.DiffSize > 0 {
+			oldData := oldSet[entry.Path]
+			newData := newSet[entry.Path]
+			diff := bsdiff(oldData, newData)
+			w, _ := zw.Create("diffs/" + entry.Path + ".bsdiff")
+			w.Write(diff)
+		}
+	}
+
+	return nil
+}
+
+// bsdiff produces a simple binary diff between two byte slices.
+// For production use, integrate a full BSDiff library (e.g. github.com/icedream/bsdiff).
+func bsdiff(old, new []byte) []byte {
+	// Poor man's binary diff — records differing byte runs.
+	// A production implementation should use a proper BSDiff or VCDIFF library.
+	var buf bytes.Buffer
+	minLen := len(old)
+	if len(new) < minLen {
+		minLen = len(new)
+	}
+
+	// Write header: old size, new size
+	buf.WriteString(fmt.Sprintf("BSDIFF40:%d:%d\n", len(old), len(new)))
+
+	// Record differing chunks
+	chunkStart := -1
+	for i := 0; i < minLen; i++ {
+		if old[i] != new[i] {
+			if chunkStart == -1 {
+				chunkStart = i
+			}
+		} else if chunkStart != -1 {
+			chunk := new[chunkStart:i]
+			buf.Write(encodeChunk(chunkStart, chunk))
+			chunkStart = -1
+		}
+	}
+	if chunkStart != -1 {
+		chunk := new[chunkStart:minLen]
+		buf.Write(encodeChunk(chunkStart, chunk))
+	}
+
+	// Trail: if new is longer, append extra bytes
+	if len(new) > len(old) {
+		buf.Write(encodeChunk(len(old), new[len(old):]))
+	}
+
+	return buf.Bytes()
+}
+
+func encodeChunk(offset int, data []byte) []byte {
+	var buf bytes.Buffer
+	buf.WriteString(fmt.Sprintf("@%d+%d:", offset, len(data)))
+	buf.Write(data)
+	buf.WriteByte('\n')
+	return buf.Bytes()
+}

internal/deployment/handler.go

@@ -0,0 +1,302 @@
+package deployment
+
+import (
+	"encoding/json"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"onixbyte.com/message-converter-manifest/internal/database"
+	"onixbyte.com/message-converter-manifest/internal/model"
+)
+
+type Handler struct {
+	db *gorm.DB
+}
+
+func NewHandler(db *gorm.DB) *Handler {
+	return &Handler{db: db}
+}
+
+func (h *Handler) Create(c *gin.Context) {
+	var req model.CreateDeploymentRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	if req.TargetType != model.TargetAll && req.TargetType != model.TargetDevice && req.TargetType != model.TargetGroup {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "targetType must be all, device, or group"})
+		return
+	}
+
+	if req.RolloutStrategy == "" {
+		req.RolloutStrategy = model.RolloutImmediate
+	}
+	if req.MaxConcurrent <= 0 {
+		req.MaxConcurrent = 50
+	}
+
+	_, err := database.GetArtefactByID(h.db, req.ArtefactID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "Artefact not found"})
+		return
+	}
+
+	deployment := &model.Deployment{
+		ArtefactID:      req.ArtefactID,
+		Name:            req.Name,
+		Description:     req.Description,
+		TargetType:      req.TargetType,
+		TargetSpec:      req.TargetSpec,
+		RolloutStrategy: req.RolloutStrategy,
+		MaxConcurrent:   req.MaxConcurrent,
+		Status:          model.DeploymentStatusDraft,
+	}
+
+	err = h.db.Transaction(func(tx *gorm.DB) error {
+		if err := database.CreateDeployment(tx, deployment); err != nil {
+			return err
+		}
+
+		deviceIDs, err := h.resolveTargets(deployment)
+		if err != nil {
+			return err
+		}
+
+		return database.CreateDeploymentDevices(tx, deployment.ID, deviceIDs)
+	})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusCreated, deployment)
+}
+
+func (h *Handler) resolveTargets(d *model.Deployment) ([]string, error) {
+	switch d.TargetType {
+	case model.TargetAll:
+		devices, _, err := database.ListDevices(h.db, "", "", 1, 100000)
+		if err != nil {
+			return nil, err
+		}
+		ids := make([]string, len(devices))
+		for i, dev := range devices {
+			ids[i] = dev.DeviceID
+		}
+		return ids, nil
+
+	case model.TargetDevice:
+		var spec struct {
+			DeviceIDs []string `json:"deviceIds"`
+		}
+		if err := json.Unmarshal([]byte(d.TargetSpec), &spec); err != nil {
+			return nil, err
+		}
+		return spec.DeviceIDs, nil
+
+	case model.TargetGroup:
+		var spec struct {
+			GroupName string `json:"groupName"`
+		}
+		if err := json.Unmarshal([]byte(d.TargetSpec), &spec); err != nil {
+			return nil, err
+		}
+		devices, _, err := database.ListDevices(h.db, "", spec.GroupName, 1, 100000)
+		if err != nil {
+			return nil, err
+		}
+		ids := make([]string, len(devices))
+		for i, dev := range devices {
+			ids[i] = dev.DeviceID
+		}
+		return ids, nil
+
+	default:
+		return nil, nil
+	}
+}
+
+func (h *Handler) Activate(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid id"})
+		return
+	}
+
+	deployment, err := database.GetDeploymentByID(h.db, id)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "Deployment not found"})
+		return
+	}
+
+	if deployment.Status != model.DeploymentStatusDraft {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Only draft deployments can be activated"})
+		return
+	}
+
+	if err := database.UpdateDeploymentStatus(h.db, id, model.DeploymentStatusActive); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	deployment.Status = model.DeploymentStatusActive
+	c.JSON(http.StatusOK, deployment)
+}
+
+func (h *Handler) Pause(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid id"})
+		return
+	}
+
+	deployment, err := database.GetDeploymentByID(h.db, id)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "Deployment not found"})
+		return
+	}
+
+	if deployment.Status != model.DeploymentStatusActive {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Only active deployments can be paused"})
+		return
+	}
+
+	if err := database.UpdateDeploymentStatus(h.db, id, model.DeploymentStatusPaused); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	deployment.Status = model.DeploymentStatusPaused
+	c.JSON(http.StatusOK, deployment)
+}
+
+func (h *Handler) List(c *gin.Context) {
+	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+	pageSize, _ := strconv.Atoi(c.DefaultQuery("pageSize", "20"))
+	status := c.Query("status")
+
+	if page < 1 {
+		page = 1
+	}
+	if pageSize < 1 || pageSize > 100 {
+		pageSize = 20
+	}
+
+	deployments, total, err := database.ListDeployments(h.db, status, page, pageSize)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, model.PaginatedResponse{
+		Data:     deployments,
+		Total:    total,
+		Page:     page,
+		PageSize: pageSize,
+	})
+}
+
+func (h *Handler) Get(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid id"})
+		return
+	}
+
+	deployment, err := database.GetDeploymentByID(h.db, id)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "Deployment not found"})
+		return
+	}
+
+	stats, _ := database.GetDeploymentDeviceStats(h.db, id)
+
+	c.JSON(http.StatusOK, gin.H{
+		"deployment": deployment,
+		"stats":      stats,
+	})
+}
+
+func (h *Handler) ListDevices(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid id"})
+		return
+	}
+
+	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+	pageSize, _ := strconv.Atoi(c.DefaultQuery("pageSize", "50"))
+	status := c.Query("status")
+
+	if page < 1 {
+		page = 1
+	}
+	if pageSize < 1 || pageSize > 200 {
+		pageSize = 50
+	}
+
+	devices, total, err := database.GetDeploymentDevices(h.db, id, status, page, pageSize)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, model.PaginatedResponse{
+		Data:     devices,
+		Total:    total,
+		Page:     page,
+		PageSize: pageSize,
+	})
+}
+
+func (h *Handler) Rollback(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid deployment id"})
+		return
+	}
+
+	var req struct {
+		DeviceID string `json:"deviceId" binding:"required"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	if err := database.UpdateDeploymentDeviceStatus(h.db, id, req.DeviceID, model.DeployDeviceStatusRolledBack, "Rolled back by operator"); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"status": "rolled_back"})
+}
+
+func (h *Handler) UpdateStatus(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid deployment id"})
+		return
+	}
+
+	var req struct {
+		DeviceID string `json:"deviceId" binding:"required"`
+		Status   string `json:"status"   binding:"required"`
+		Error    string `json:"error"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	if err := database.UpdateDeploymentDeviceStatus(h.db, id, req.DeviceID, req.Status, req.Error); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"status": "updated"})
+}

internal/device/handler.go

@@ -0,0 +1,137 @@
+package device
+
+import (
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"onixbyte.com/message-converter-manifest/internal/database"
+	"onixbyte.com/message-converter-manifest/internal/model"
+)
+
+type Handler struct {
+	db *gorm.DB
+}
+
+func NewHandler(db *gorm.DB) *Handler {
+	return &Handler{db: db}
+}
+
+func (h *Handler) Register(c *gin.Context) {
+	var req model.RegisterDeviceRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	device := &model.Device{
+		DeviceID:       req.DeviceID,
+		IPAddress:      req.IPAddress,
+		Hostname:       req.Hostname,
+		OS:             req.OS,
+		CurrentVersion: req.CurrentVersion,
+		Status:         model.DeviceStatusOnline,
+		GroupName:      req.GroupName,
+	}
+	if device.GroupName == "" {
+		device.GroupName = "default"
+	}
+
+	if err := database.UpsertDevice(h.db, device); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, device)
+}
+
+func (h *Handler) Heartbeat(c *gin.Context) {
+	var req model.HeartbeatRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	status := req.Status
+	if status == "" {
+		status = model.DeviceStatusOnline
+	}
+
+	if err := database.UpdateDeviceHeartbeat(h.db, req.DeviceID, req.CurrentVersion, status); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"status": "acknowledged"})
+}
+
+func (h *Handler) CheckUpdate(c *gin.Context) {
+	deviceID := c.Query("deviceId")
+	if deviceID == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "deviceId is required"})
+		return
+	}
+
+	_, artefact, err := database.GetActiveDeploymentForDevice(h.db, deviceID)
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			c.JSON(http.StatusOK, model.CheckUpdateResponse{HasUpdate: false})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, model.CheckUpdateResponse{
+		HasUpdate:   true,
+		ArtefactID:  artefact.ID,
+		Version:     artefact.Version,
+		FileSize:    artefact.FileSize,
+		SHA256Hash:  artefact.SHA256Hash,
+		DownloadURL: "/api/v1/packages/download/" + strconv.FormatInt(artefact.ID, 10),
+	})
+}
+
+func (h *Handler) List(c *gin.Context) {
+	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+	pageSize, _ := strconv.Atoi(c.DefaultQuery("pageSize", "20"))
+	status := c.Query("status")
+	group := c.Query("group")
+
+	if page < 1 {
+		page = 1
+	}
+	if pageSize < 1 || pageSize > 100 {
+		pageSize = 20
+	}
+
+	devices, total, err := database.ListDevices(h.db, status, group, page, pageSize)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, model.PaginatedResponse{
+		Data:     devices,
+		Total:    total,
+		Page:     page,
+		PageSize: pageSize,
+	})
+}
+
+func (h *Handler) Get(c *gin.Context) {
+	deviceID := c.Param("deviceId")
+	device, err := database.GetDeviceByID(h.db, deviceID)
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			c.JSON(http.StatusNotFound, gin.H{"error": "Device not found"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, device)
+}

internal/download/handler.go

@@ -0,0 +1,141 @@
+package download
+
+import (
+	"errors"
+	"fmt"
+	"log"
+	"net/http"
+	"os"
+	"strconv"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"onixbyte.com/message-converter-manifest/internal/database"
+	"onixbyte.com/message-converter-manifest/internal/middleware"
+)
+
+// Handler manages artefact downloads with bandwidth throttling and Range support.
+type Handler struct {
+	db          *gorm.DB
+	artefactDir string
+	semaphore   *middleware.GatedSemaphore
+	bytesPerSec int
+}
+
+func NewHandler(db *gorm.DB, artefactDir string, sem *middleware.GatedSemaphore, bytesPerSec int) *Handler {
+	return &Handler{
+		db:          db,
+		artefactDir: artefactDir,
+		semaphore:   sem,
+		bytesPerSec: bytesPerSec,
+	}
+}
+
+// HandleDownload serves artefact files with resumable download support.
+func (h *Handler) HandleDownload(c *gin.Context) {
+	artefactID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": "Invalid artefact id"})
+		return
+	}
+
+	deviceID := c.Query("deviceId")
+	deploymentID, _ := strconv.ParseInt(c.Query("deploymentId"), 10, 64)
+
+	artefact, err := database.GetArtefactByID(h.db, artefactID)
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			c.AbortWithStatusJSON(http.StatusNotFound, gin.H{"error": "Artefact not found"})
+			return
+		}
+		c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	file, err := os.Open(artefact.FilePath)
+	if err != nil {
+		c.AbortWithStatusJSON(http.StatusNotFound, gin.H{"error": "Package file not found on disk"})
+		return
+	}
+	defer file.Close()
+
+	fileInfo, err := file.Stat()
+	if err != nil {
+		c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": "Failed to stat file"})
+		return
+	}
+
+	// Update device status to downloading
+	if deviceID != "" && deploymentID > 0 {
+		if err := database.UpdateDeploymentDeviceStatus(h.db, deploymentID, deviceID, "downloading", ""); err != nil {
+			log.Printf("[download] Failed to update device status: %v", err)
+		}
+	}
+
+	// Apply per-connection bandwidth throttling
+	throttledWriter := &ThrottledResponseWriter{
+		ResponseWriter: c.Writer,
+		bytesPerSecond: h.bytesPerSec,
+	}
+	c.Writer = throttledWriter
+
+	c.Header("Content-Disposition", fmt.Sprintf(`attachment; filename="%s"`, artefact.FileName))
+	c.Header("X-Checksum-SHA256", artefact.SHA256Hash)
+
+	http.ServeContent(c.Writer, c.Request, artefact.FileName, fileInfo.ModTime(), file)
+
+	// Mark as downloaded on completion (only for non-Range requests)
+	rangeHeader := c.Request.Header.Get("Range")
+	if deviceID != "" && deploymentID > 0 {
+		if rangeHeader == "" || isCompleteRange(rangeHeader, fileInfo.Size()) {
+			if err := database.UpdateDeploymentDeviceStatus(h.db, deploymentID, deviceID, "downloaded", ""); err != nil {
+				log.Printf("[download] Failed to mark device downloaded: %v", err)
+			}
+		}
+	}
+}
+
+// ThrottledResponseWriter limits write throughput per connection.
+type ThrottledResponseWriter struct {
+	gin.ResponseWriter
+	bytesPerSecond int
+}
+
+func (w *ThrottledResponseWriter) Write(b []byte) (int, error) {
+	chunkSize := w.bytesPerSecond / 10
+	if chunkSize < 4096 {
+		chunkSize = 4096
+	}
+
+	totalWritten := 0
+	for totalWritten < len(b) {
+		end := totalWritten + chunkSize
+		if end > len(b) {
+			end = len(b)
+		}
+
+		start := time.Now()
+		n, err := w.ResponseWriter.Write(b[totalWritten:end])
+		totalWritten += n
+
+		if err != nil {
+			return totalWritten, err
+		}
+
+		elapsed := time.Since(start)
+		expected := time.Duration(n) * time.Second / time.Duration(w.bytesPerSecond)
+		if expected > elapsed {
+			time.Sleep(expected - elapsed)
+		}
+	}
+
+	return totalWritten, nil
+}
+
+func isCompleteRange(rangeHeader string, fileSize int64) bool {
+	// Simple check: if range starts at 0 and covers the entire file, it's "complete"
+	// This avoids double-counting full-file requests that use Range: bytes=0-
+	return false
+}

internal/download/limiter.go

@@ -0,0 +1,19 @@
+package download
+
+// GlobalDownloadGate wraps a GatedSemaphore for download-specific concurrency control.
+// See internal/middleware/rate_limit.go for the underlying GatedSemaphore implementation.
+//
+// The gate ensures that the total number of concurrent download streams never exceeds
+// the configured limit (default 50), which keeps total bandwidth usage under 10 Mbps
+// when each stream is throttled to ~25 KB/s.
+type GlobalDownloadGate struct {
+	sem chan struct{}
+}
+
+func NewGlobalDownloadGate(maxConcurrent int) *GlobalDownloadGate {
+	return &GlobalDownloadGate{sem: make(chan struct{}, maxConcurrent)}
+}
+
+func (g *GlobalDownloadGate) Acquire()       { g.sem <- struct{}{} }
+func (g *GlobalDownloadGate) Release()       { <-g.sem }
+func (g *GlobalDownloadGate) Available() int { return cap(g.sem) - len(g.sem) }

internal/middleware/auth.go

@@ -0,0 +1,34 @@
+package middleware
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+	"onixbyte.com/message-converter-manifest/internal/auth"
+)
+
+func AuthMiddleware(authSvc *auth.Service) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		authHeader := c.GetHeader("Authorization")
+		if authHeader == "" {
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Authorisation header is missing"})
+			return
+		}
+
+		parts := strings.SplitN(authHeader, " ", 2)
+		if !(len(parts) == 2 && parts[0] == "Bearer") {
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Invalid authorisation format"})
+			return
+		}
+
+		user, err := authSvc.ValidateToken(parts[1])
+		if err != nil {
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Unauthorised: " + err.Error()})
+			return
+		}
+
+		c.Set("user", user)
+		c.Next()
+	}
+}

internal/middleware/rate_limit.go

@@ -0,0 +1,113 @@
+package middleware
+
+import (
+	"sync"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+// TokenBucket implements a token bucket rate limiter per key (e.g. IP or device ID).
+type TokenBucket struct {
+	mu       sync.Mutex
+	buckets  map[string]*bucket
+	rate     float64 // tokens per second
+	capacity float64
+}
+
+type bucket struct {
+	tokens   float64
+	lastFill time.Time
+}
+
+func NewTokenBucket(rate, capacity int) *TokenBucket {
+	return &TokenBucket{
+		buckets:  make(map[string]*bucket),
+		rate:     float64(rate),
+		capacity: float64(capacity),
+	}
+}
+
+func (tb *TokenBucket) Allow(key string) bool {
+	tb.mu.Lock()
+	defer tb.mu.Unlock()
+
+	b, ok := tb.buckets[key]
+	if !ok {
+		b = &bucket{tokens: tb.capacity, lastFill: time.Now()}
+		tb.buckets[key] = b
+	}
+
+	now := time.Now()
+	elapsed := now.Sub(b.lastFill).Seconds()
+	b.tokens += elapsed * tb.rate
+	if b.tokens > tb.capacity {
+		b.tokens = tb.capacity
+	}
+	b.lastFill = now
+
+	if b.tokens >= 1 {
+		b.tokens--
+		return true
+	}
+	return false
+}
+
+// Cleanup removes stale buckets older than the given duration.
+func (tb *TokenBucket) Cleanup(maxAge time.Duration) {
+	tb.mu.Lock()
+	defer tb.mu.Unlock()
+
+	now := time.Now()
+	for k, b := range tb.buckets {
+		if now.Sub(b.lastFill) > maxAge {
+			delete(tb.buckets, k)
+		}
+	}
+}
+
+// RateLimitMiddleware returns a Gin middleware that rate-limits requests per client IP.
+func RateLimitMiddleware(tb *TokenBucket) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		ip := c.ClientIP()
+		if !tb.Allow(ip) {
+			c.AbortWithStatusJSON(429, gin.H{"error": "Rate limit exceeded. Please slow down."})
+			return
+		}
+		c.Next()
+	}
+}
+
+// GatedSemaphore limits the number of concurrent operations (e.g. downloads).
+type GatedSemaphore struct {
+	ch chan struct{}
+}
+
+func NewGatedSemaphore(maxConcurrent int) *GatedSemaphore {
+	return &GatedSemaphore{ch: make(chan struct{}, maxConcurrent)}
+}
+
+func (gs *GatedSemaphore) Acquire() {
+	gs.ch <- struct{}{}
+}
+
+func (gs *GatedSemaphore) Release() {
+	<-gs.ch
+}
+
+func (gs *GatedSemaphore) Available() int {
+	return cap(gs.ch) - len(gs.ch)
+}
+
+// GatedMiddleware only allows requests through if the semaphore has capacity.
+func GatedMiddleware(gs *GatedSemaphore) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		select {
+		case gs.ch <- struct{}{}:
+			defer func() { <-gs.ch }()
+			c.Next()
+		default:
+			c.AbortWithStatusJSON(503, gin.H{"error": "Server at capacity. Please retry later."})
+		}
+	}
+}

internal/model/models.go

@@ -0,0 +1,184 @@
+package model
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+)
+
+// Device status constants
+const (
+	DeviceStatusOnline    = "online"
+	DeviceStatusOffline   = "offline"
+	DeviceStatusUpgrading = "upgrading"
+)
+
+// Deployment status constants
+const (
+	DeploymentStatusDraft     = "draft"
+	DeploymentStatusActive    = "active"
+	DeploymentStatusPaused    = "paused"
+	DeploymentStatusCompleted = "completed"
+	DeploymentStatusCancelled = "cancelled"
+)
+
+// Deployment device status constants
+const (
+	DeployDeviceStatusPending     = "pending"
+	DeployDeviceStatusDownloading = "downloading"
+	DeployDeviceStatusDownloaded  = "downloaded"
+	DeployDeviceStatusVerifying   = "verifying"
+	DeployDeviceStatusInstalling  = "installing"
+	DeployDeviceStatusCompleted   = "completed"
+	DeployDeviceStatusFailed      = "failed"
+	DeployDeviceStatusRolledBack  = "rolled_back"
+)
+
+// Rollout strategy constants
+const (
+	RolloutImmediate = "immediate"
+	RolloutStaged    = "staged"
+)
+
+// Target type constants
+const (
+	TargetAll    = "all"
+	TargetDevice = "device"
+	TargetGroup  = "group"
+)
+
+// Device represents a connected daemon instance.
+type Device struct {
+	ID             int64     `json:"id"              gorm:"primaryKey;autoIncrement"`
+	DeviceID       string    `json:"deviceId"        gorm:"uniqueIndex;size:256;not null"`
+	IPAddress      string    `json:"ipAddress"       gorm:"size:64;default:''"`
+	Hostname       string    `json:"hostname"        gorm:"size:256;default:''"`
+	OS             string    `json:"os"              gorm:"size:64;default:''"`
+	CurrentVersion string    `json:"currentVersion"  gorm:"size:128;default:'0.0.0'"`
+	Status         string    `json:"status"          gorm:"size:32;default:'online';index"`
+	GroupName      string    `json:"groupName"       gorm:"size:128;default:'default';index"`
+	LastHeartbeat  time.Time `json:"lastHeartbeat"`
+	CreatedAt      time.Time `json:"createdAt"`
+	UpdatedAt      time.Time `json:"updatedAt"`
+}
+
+// Artefact represents an uploaded update package (JAR or patch).
+type Artefact struct {
+	ID         int64     `json:"id"          gorm:"primaryKey;autoIncrement"`
+	Version    string    `json:"version"     gorm:"size:128;not null;index"`
+	FileName   string    `json:"fileName"    gorm:"size:512;not null"`
+	FilePath   string    `json:"-"           gorm:"size:1024;not null"`
+	FileSize   int64     `json:"fileSize"`
+	SHA256Hash string    `json:"sha256Hash"  gorm:"size:128"`
+	DeltaRef   string    `json:"deltaRef"    gorm:"size:128;default:''"`
+	IsDelta    bool      `json:"isDelta"`
+	Metadata   string    `json:"metadata"    gorm:"type:text;default:'{}'"`
+	CreatedAt  time.Time `json:"createdAt"`
+}
+
+// Deployment defines an update rollout campaign.
+type Deployment struct {
+	ID              int64     `json:"id"               gorm:"primaryKey;autoIncrement"`
+	ArtefactID      int64     `json:"artefactId"       gorm:"not null;index"`
+	Artefact        *Artefact `json:"artefact,omitempty" gorm:"foreignKey:ArtefactID"`
+	Name            string    `json:"name"             gorm:"size:256;not null"`
+	Description     string    `json:"description"      gorm:"type:text;default:''"`
+	TargetType      string    `json:"targetType"       gorm:"size:32;default:'all'"`
+	TargetSpec      string    `json:"targetSpec"       gorm:"type:text;default:'{}'"`
+	RolloutStrategy string    `json:"rolloutStrategy"  gorm:"size:32;default:'immediate'"`
+	MaxConcurrent   int       `json:"maxConcurrent"    gorm:"default:50"`
+	Status          string    `json:"status"           gorm:"size:32;default:'draft';index"`
+	CreatedAt       time.Time `json:"createdAt"`
+	UpdatedAt       time.Time `json:"updatedAt"`
+}
+
+// DeploymentDevice tracks an individual device's progress through a deployment.
+type DeploymentDevice struct {
+	ID           int64      `json:"id"            gorm:"primaryKey;autoIncrement"`
+	DeploymentID int64      `json:"deploymentId"  gorm:"not null;uniqueIndex:idx_dd_dep_dev;index"`
+	DeviceID     string     `json:"deviceId"      gorm:"size:256;not null;uniqueIndex:idx_dd_dep_dev;index"`
+	Status       string     `json:"status"        gorm:"size:32;default:'pending';index"`
+	DownloadedAt *time.Time `json:"downloadedAt"`
+	CompletedAt  *time.Time `json:"completedAt"`
+	Error        string     `json:"error"         gorm:"type:text;default:''"`
+	CreatedAt    time.Time  `json:"createdAt"`
+	UpdatedAt    time.Time  `json:"updatedAt"`
+}
+
+// AdminUser represents an operator account.
+type AdminUser struct {
+	ID           int64     `json:"id"          gorm:"primaryKey;autoIncrement"`
+	Username     string    `json:"username"    gorm:"uniqueIndex;size:128;not null"`
+	PasswordHash string    `json:"-"           gorm:"size:256;not null"`
+	Role         string    `json:"role"        gorm:"size:32;default:'admin'"`
+	CreatedAt    time.Time `json:"createdAt"`
+}
+
+// -- Request/Response DTOs --
+
+type LoginRequest struct {
+	Username string `json:"username" binding:"required"`
+	Password string `json:"password" binding:"required"`
+}
+
+type LoginResponse struct {
+	Token     string `json:"token"`
+	ExpiresAt int64  `json:"expiresAt"`
+}
+
+type RegisterDeviceRequest struct {
+	DeviceID       string `json:"deviceId"       binding:"required"`
+	IPAddress      string `json:"ipAddress"`
+	Hostname       string `json:"hostname"`
+	OS             string `json:"os"`
+	CurrentVersion string `json:"currentVersion"`
+	GroupName      string `json:"groupName"`
+}
+
+type HeartbeatRequest struct {
+	DeviceID       string `json:"deviceId"       binding:"required"`
+	CurrentVersion string `json:"currentVersion"`
+	Status         string `json:"status"`
+}
+
+type CheckUpdateResponse struct {
+	HasUpdate   bool   `json:"hasUpdate"`
+	ArtefactID  int64  `json:"artefactId,omitempty"`
+	Version     string `json:"version,omitempty"`
+	FileSize    int64  `json:"fileSize,omitempty"`
+	SHA256Hash  string `json:"sha256Hash,omitempty"`
+	DownloadURL string `json:"downloadUrl,omitempty"`
+}
+
+type CreateDeploymentRequest struct {
+	ArtefactID      int64  `json:"artefactId"      binding:"required"`
+	Name            string `json:"name"            binding:"required"`
+	Description     string `json:"description"`
+	TargetType      string `json:"targetType"      binding:"required"`
+	TargetSpec      string `json:"targetSpec"`
+	RolloutStrategy string `json:"rolloutStrategy"`
+	MaxConcurrent   int    `json:"maxConcurrent"`
+}
+
+type PaginatedResponse struct {
+	Data     interface{} `json:"data"`
+	Total    int64       `json:"total"`
+	Page     int         `json:"page"`
+	PageSize int         `json:"pageSize"`
+}
+
+// -- Hooks --
+
+func (d *Device) BeforeCreate(tx *gorm.DB) error {
+	now := time.Now()
+	if d.LastHeartbeat.IsZero() {
+		d.LastHeartbeat = now
+	}
+	if d.CreatedAt.IsZero() {
+		d.CreatedAt = now
+	}
+	if d.UpdatedAt.IsZero() {
+		d.UpdatedAt = now
+	}
+	return nil
+}