feat: V2 microservices stack — backend services, gateway, JWT auth

Add full V2 architecture: identity, content, studio (.NET 10) and file,
render, notification, gateway (Go) services with vendored deps, plus DB
migrations, event/API contracts, and an init-db script.

Wire the Next.js frontend to the gateway: server-side JWT auth routes
(login/register/refresh/logout/me), gateway fetch helper, and session/
cookie/jwt helpers under src/lib.

Containerize the stack via docker-compose.v2.yml and per-service
Dockerfiles. Base images resolve through a Nexus mirror (Docker Hub) and
MCR directly; npm/NuGet pull from Nexus groups. Self-host fonts via
next/font/local to avoid Google Fonts (geo-blocked).

Add CI workflow and ignore .env.v2, *.stackdump, and .NET bin/obj.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

services/render/internal/handlers/exports.go

@@ -0,0 +1,151 @@
+package handlers
+
+import (
+	"context"
+	"net/http"
+	"strconv"
+	"time"
+
+	"github.com/flatrender/render-svc/internal/db"
+	"github.com/flatrender/render-svc/internal/middleware"
+	"github.com/flatrender/render-svc/internal/models"
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"github.com/minio/minio-go/v7"
+)
+
+type ExportHandler struct {
+	store  *db.Store
+	minio  *minio.Client
+	bucket string
+}
+
+func NewExportHandler(store *db.Store, mc *minio.Client, bucket string) *ExportHandler {
+	return &ExportHandler{store: store, minio: mc, bucket: bucket}
+}
+
+// GET /v1/exports
+func (h *ExportHandler) List(c *gin.Context) {
+	userID := middleware.GetUserID(c)
+	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+	if page < 1 {
+		page = 1
+	}
+	exports, total, err := h.store.ListExports(c.Request.Context(), userID, page, 20)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	if exports == nil {
+		exports = []*models.Export{}
+	}
+	c.JSON(http.StatusOK, models.PagedResponse[*models.Export]{
+		Data: exports,
+		Meta: models.PaginationMeta{
+			Page:     page,
+			PageSize: 20,
+			Total:    total,
+			HasMore:  int64(page*20) < total,
+		},
+	})
+}
+
+// GET /v1/exports/:export_id
+func (h *ExportHandler) Get(c *gin.Context) {
+	userID := middleware.GetUserID(c)
+	exportID, err := uuid.Parse(c.Param("export_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid export_id"})
+		return
+	}
+	exp, err := h.store.GetExportByID(c.Request.Context(), exportID, userID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, models.APIError{Code: "not_found", Message: err.Error()})
+		return
+	}
+	files, _ := h.store.ListExportFiles(c.Request.Context(), exportID)
+	if files == nil {
+		files = []*models.ExportFile{}
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"id":              exp.ID,
+		"saved_project_id": exp.SavedProjectID,
+		"path":            exp.Path,
+		"image":           exp.Image,
+		"size_bytes":      exp.SizeBytes,
+		"duration_sec":    exp.DurationSec,
+		"width":           exp.Width,
+		"height":          exp.Height,
+		"file_extension":  exp.FileExtension,
+		"file_type":       exp.FileType,
+		"render_quality":  exp.RenderQuality,
+		"create_type":     exp.CreateType,
+		"produce_date":    exp.ProduceDate,
+		"auto_delete_date": exp.AutoDeleteDate,
+		"files":           files,
+	})
+}
+
+// DELETE /v1/exports/:export_id
+func (h *ExportHandler) Delete(c *gin.Context) {
+	userID := middleware.GetUserID(c)
+	exportID, err := uuid.Parse(c.Param("export_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid export_id"})
+		return
+	}
+	if err := h.store.SoftDeleteExport(c.Request.Context(), exportID, userID); err != nil {
+		c.JSON(http.StatusNotFound, models.APIError{Code: "not_found", Message: err.Error()})
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+// POST /v1/exports/:export_id/extend
+func (h *ExportHandler) Extend(c *gin.Context) {
+	userID := middleware.GetUserID(c)
+	exportID, err := uuid.Parse(c.Param("export_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid export_id"})
+		return
+	}
+	var body struct {
+		Days int `json:"days" binding:"required,min=1,max=365"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: err.Error()})
+		return
+	}
+	newDate, err := h.store.ExtendExportDeleteDate(c.Request.Context(), exportID, userID, body.Days)
+	if err != nil {
+		c.JSON(http.StatusNotFound, models.APIError{Code: "not_found", Message: err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"new_auto_delete_date": newDate})
+}
+
+// GET /v1/exports/:export_id/download-url
+func (h *ExportHandler) DownloadURL(c *gin.Context) {
+	userID := middleware.GetUserID(c)
+	exportID, err := uuid.Parse(c.Param("export_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid export_id"})
+		return
+	}
+	exp, err := h.store.GetExportByID(c.Request.Context(), exportID, userID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, models.APIError{Code: "not_found", Message: err.Error()})
+		return
+	}
+	// Generate presigned URL (15 min TTL)
+	expiry := 15 * time.Minute
+	url, err := h.minio.PresignedGetObject(context.Background(), h.bucket, exp.Path, expiry, nil)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: "could not generate download URL"})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"url":        url.String(),
+		"expires_at": time.Now().Add(expiry),
+	})
+}

services/render/internal/handlers/internal.go

@@ -0,0 +1,218 @@
+package handlers
+
+import (
+	"net/http"
+
+	"github.com/flatrender/render-svc/internal/db"
+	"github.com/flatrender/render-svc/internal/models"
+	"github.com/flatrender/render-svc/internal/notifier"
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+)
+
+type InternalHandler struct {
+	store    *db.Store
+	notifier *notifier.Client // may be nil — notifications are best-effort
+}
+
+func NewInternalHandler(store *db.Store, n *notifier.Client) *InternalHandler {
+	return &InternalHandler{store: store, notifier: n}
+}
+
+// completeRequest is the body for POST .../complete
+type completeRequest struct {
+	ExportID *uuid.UUID `json:"export_id"`
+}
+
+// failRequest is the body for POST .../fail
+type failRequest struct {
+	Reason string `json:"reason" binding:"required"`
+	AtStep string `json:"at_step"` // optional: which render step failed
+}
+
+// POST /v1/internal/render/jobs/:job_id/complete
+func (h *InternalHandler) Complete(c *gin.Context) {
+	jobID, err := uuid.Parse(c.Param("job_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid job_id"})
+		return
+	}
+	var req completeRequest
+	_ = c.ShouldBindJSON(&req) // export_id is optional
+
+	job, err := h.store.CompleteJob(c.Request.Context(), jobID, req.ExportID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+
+	// Fire notification if the user requested it (tell_me_when_done)
+	if h.notifier != nil && job.TellMeWhenDone {
+		jobName := ""
+		if job.Name != nil {
+			jobName = *job.Name
+		} else if job.Title != nil {
+			jobName = *job.Title
+		}
+		h.notifier.NotifyRenderDone(c.Request.Context(),
+			job.UserID, job.TenantID, job.ID, job.ExportID, jobName)
+	}
+
+	c.JSON(http.StatusOK, gin.H{"status": "done", "job_id": job.ID})
+}
+
+// POST /v1/internal/render/jobs/:job_id/fail
+func (h *InternalHandler) Fail(c *gin.Context) {
+	jobID, err := uuid.Parse(c.Param("job_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid job_id"})
+		return
+	}
+	var req failRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: err.Error()})
+		return
+	}
+	atStep := req.AtStep
+	if atStep == "" {
+		atStep = "Rendering"
+	}
+
+	job, err := h.store.FailJob(c.Request.Context(), jobID, req.Reason, atStep)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+
+	// Notify user of failure
+	if h.notifier != nil {
+		jobName := ""
+		if job.Name != nil {
+			jobName = *job.Name
+		} else if job.Title != nil {
+			jobName = *job.Title
+		}
+		h.notifier.NotifyRenderFailed(c.Request.Context(),
+			job.UserID, job.TenantID, job.ID, jobName, req.Reason)
+	}
+
+	c.JSON(http.StatusOK, gin.H{"status": "failed", "job_id": job.ID})
+}
+
+// POST /v1/internal/nodes/:node_id/heartbeat
+func (h *InternalHandler) Heartbeat(c *gin.Context) {
+	nodeID, err := uuid.Parse(c.Param("node_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid node_id"})
+		return
+	}
+	var req models.NodeHeartbeatRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: err.Error()})
+		return
+	}
+	req.NodeID = nodeID
+	if err := h.store.UpdateNodeHeartbeat(c.Request.Context(), nodeID, &req); err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"next_heartbeat_in_sec": 5,
+		"pending_commands":      []any{},
+	})
+}
+
+// POST /v1/internal/nodes/:node_id/online
+func (h *InternalHandler) Online(c *gin.Context) {
+	nodeID, err := uuid.Parse(c.Param("node_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid node_id"})
+		return
+	}
+	var req models.NodeOnlineRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: err.Error()})
+		return
+	}
+	if err := h.store.UpdateNodeOnline(c.Request.Context(), nodeID, &req); err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	c.Status(http.StatusOK)
+}
+
+// POST /v1/internal/render/jobs/:job_id/frames
+func (h *InternalHandler) FrameProgress(c *gin.Context) {
+	jobID, err := uuid.Parse(c.Param("job_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid job_id"})
+		return
+	}
+	var req models.FrameProgressRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: err.Error()})
+		return
+	}
+	if err := h.store.UpdateFrameProgress(c.Request.Context(), jobID, &req); err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+// POST /v1/internal/render/jobs/:job_id/crash
+func (h *InternalHandler) Crash(c *gin.Context) {
+	jobID, err := uuid.Parse(c.Param("job_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid job_id"})
+		return
+	}
+	var req models.CrashReportRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: err.Error()})
+		return
+	}
+	if err := h.store.InsertCrash(c.Request.Context(), req.NodeID, jobID, &req); err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"action_recommended":     "ResetAndRestart",
+		"reassigned_to_node_id": nil,
+	})
+}
+
+// POST /v1/internal/render/jobs/:job_id/replica-ready
+func (h *InternalHandler) ReplicaReady(c *gin.Context) {
+	_, err := uuid.Parse(c.Param("job_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid job_id"})
+		return
+	}
+	var req models.ReplicaReadyRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: err.Error()})
+		return
+	}
+	// In production: update job step to TemplateCache → JsxGen, signal next pipeline phase
+	c.Status(http.StatusNoContent)
+}
+
+// POST /v1/internal/nodes/:node_id/cache-update
+func (h *InternalHandler) CacheUpdate(c *gin.Context) {
+	nodeID, err := uuid.Parse(c.Param("node_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid node_id"})
+		return
+	}
+	var req models.CacheUpdateRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: err.Error()})
+		return
+	}
+	if err := h.store.UpdateNodeCache(c.Request.Context(), nodeID, &req); err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	c.Status(http.StatusNoContent)
+}

services/render/internal/handlers/nodes.go

@@ -0,0 +1,226 @@
+package handlers
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/flatrender/render-svc/internal/db"
+	"github.com/flatrender/render-svc/internal/models"
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+)
+
+type NodeHandler struct {
+	store *db.Store
+}
+
+func NewNodeHandler(store *db.Store) *NodeHandler {
+	return &NodeHandler{store: store}
+}
+
+// GET /v1/nodes
+func (h *NodeHandler) List(c *gin.Context) {
+	region := c.Query("region")
+	status := c.Query("status")
+	nodes, err := h.store.ListNodes(c.Request.Context(), region, status)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	if nodes == nil {
+		nodes = []*models.RenderNode{}
+	}
+	c.JSON(http.StatusOK, gin.H{"data": nodes})
+}
+
+// POST /v1/nodes
+func (h *NodeHandler) Create(c *gin.Context) {
+	var req models.NodeCreateRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: err.Error()})
+		return
+	}
+	node, err := h.store.CreateNode(c.Request.Context(), &req)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	c.JSON(http.StatusCreated, node)
+}
+
+// GET /v1/nodes/:node_id
+func (h *NodeHandler) Get(c *gin.Context) {
+	nodeID, err := uuid.Parse(c.Param("node_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid node_id"})
+		return
+	}
+	node, err := h.store.GetNodeByID(c.Request.Context(), nodeID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, models.APIError{Code: "not_found", Message: err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, node)
+}
+
+// PATCH /v1/nodes/:node_id
+func (h *NodeHandler) Patch(c *gin.Context) {
+	nodeID, err := uuid.Parse(c.Param("node_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid node_id"})
+		return
+	}
+	var req models.NodePatchRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: err.Error()})
+		return
+	}
+	node, err := h.store.PatchNode(c.Request.Context(), nodeID, &req)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, node)
+}
+
+// POST /v1/nodes/:node_id/restart — Stub: in production this calls the node agent
+func (h *NodeHandler) Restart(c *gin.Context) {
+	_, err := uuid.Parse(c.Param("node_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid node_id"})
+		return
+	}
+	c.Status(http.StatusAccepted)
+}
+
+// POST /v1/nodes/:node_id/release
+func (h *NodeHandler) Release(c *gin.Context) {
+	nodeID, err := uuid.Parse(c.Param("node_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid node_id"})
+		return
+	}
+	if err := h.store.ReleaseNode(c.Request.Context(), nodeID); err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+// POST /v1/nodes/:node_id/close-ae — Stub: signals the node agent to kill AE process
+func (h *NodeHandler) CloseAE(c *gin.Context) {
+	_, err := uuid.Parse(c.Param("node_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid node_id"})
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+// GET /v1/nodes/:node_id/health
+func (h *NodeHandler) Health(c *gin.Context) {
+	nodeID, err := uuid.Parse(c.Param("node_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid node_id"})
+		return
+	}
+	node, err := h.store.GetNodeByID(c.Request.Context(), nodeID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, models.APIError{Code: "not_found", Message: err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"node_id":          node.ID,
+		"recorded_at":      node.LastHeartbeatAt,
+		"status":           node.Status,
+		"cpu_pct":          node.LastCPUPct,
+		"ram_available_mb": node.LastRAMAvailableMB,
+		"ae_running":       node.AERunning,
+		"current_job_id":   node.CurrentJobID,
+		"cache_used_gb":    node.CacheUsedGB,
+	})
+}
+
+// GET /v1/nodes/:node_id/health/history
+func (h *NodeHandler) HealthHistory(c *gin.Context) {
+	nodeID, err := uuid.Parse(c.Param("node_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid node_id"})
+		return
+	}
+	fromStr := c.Query("from")
+	toStr := c.Query("to")
+	from := time.Now().Add(-24 * time.Hour)
+	to := time.Now()
+	if fromStr != "" {
+		if t, err := time.Parse(time.RFC3339, fromStr); err == nil {
+			from = t
+		}
+	}
+	if toStr != "" {
+		if t, err := time.Parse(time.RFC3339, toStr); err == nil {
+			to = t
+		}
+	}
+	logs, err := h.store.ListNodeHealthHistory(c.Request.Context(), nodeID, from, to)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	if logs == nil {
+		logs = []*models.NodeHealthLog{}
+	}
+	c.JSON(http.StatusOK, gin.H{"data": logs})
+}
+
+// GET /v1/nodes/:node_id/crashes
+func (h *NodeHandler) Crashes(c *gin.Context) {
+	nodeID, err := uuid.Parse(c.Param("node_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid node_id"})
+		return
+	}
+	crashes, err := h.store.ListNodeCrashes(c.Request.Context(), nodeID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	if crashes == nil {
+		crashes = []*models.NodeCrash{}
+	}
+	c.JSON(http.StatusOK, gin.H{"data": crashes})
+}
+
+// GET /v1/node-updates
+func (h *NodeHandler) ListUpdates(c *gin.Context) {
+	updates, err := h.store.ListNodeUpdates(c.Request.Context())
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	if updates == nil {
+		updates = []*models.NodeUpdate{}
+	}
+	c.JSON(http.StatusOK, gin.H{"data": updates})
+}
+
+// POST /v1/node-updates/:update_id/rollout
+func (h *NodeHandler) Rollout(c *gin.Context) {
+	updateID, err := uuid.Parse(c.Param("update_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid update_id"})
+		return
+	}
+	var body struct {
+		NodeIDs []uuid.UUID `json:"node_ids"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: err.Error()})
+		return
+	}
+	if err := h.store.QueueUpdateRollout(c.Request.Context(), updateID, body.NodeIDs); err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	c.Status(http.StatusAccepted)
+}

services/render/internal/handlers/renders.go

@@ -0,0 +1,193 @@
+package handlers
+
+import (
+	"net/http"
+	"strconv"
+
+	"github.com/flatrender/render-svc/internal/db"
+	"github.com/flatrender/render-svc/internal/middleware"
+	"github.com/flatrender/render-svc/internal/models"
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+)
+
+type RenderHandler struct {
+	store *db.Store
+}
+
+func NewRenderHandler(store *db.Store) *RenderHandler {
+	return &RenderHandler{store: store}
+}
+
+// GET /v1/renders
+func (h *RenderHandler) List(c *gin.Context) {
+	userID := middleware.GetUserID(c)
+	status := c.Query("status")
+	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+	pageSize, _ := strconv.Atoi(c.DefaultQuery("page_size", "20"))
+	if page < 1 {
+		page = 1
+	}
+	if pageSize < 1 || pageSize > 100 {
+		pageSize = 20
+	}
+
+	jobs, total, err := h.store.ListJobs(c.Request.Context(), userID, status, page, pageSize)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	if jobs == nil {
+		jobs = []*models.RenderJob{}
+	}
+	c.JSON(http.StatusOK, models.PagedResponse[*models.RenderJob]{
+		Data: jobs,
+		Meta: models.PaginationMeta{
+			Page:     page,
+			PageSize: pageSize,
+			Total:    total,
+			HasMore:  int64(page*pageSize) < total,
+		},
+	})
+}
+
+// POST /v1/renders
+func (h *RenderHandler) Create(c *gin.Context) {
+	userID := middleware.GetUserID(c)
+	tenantID := middleware.GetTenantID(c)
+
+	var req models.RenderJobCreateRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: err.Error()})
+		return
+	}
+	job, err := h.store.CreateJob(c.Request.Context(), userID, tenantID, &req)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	c.JSON(http.StatusCreated, job)
+}
+
+// GET /v1/renders/:job_id
+func (h *RenderHandler) Get(c *gin.Context) {
+	userID := middleware.GetUserID(c)
+	jobID, err := uuid.Parse(c.Param("job_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid job_id"})
+		return
+	}
+	job, err := h.store.GetJobByID(c.Request.Context(), jobID, userID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, models.APIError{Code: "not_found", Message: err.Error()})
+		return
+	}
+	frames, _ := h.store.ListFrameJobs(c.Request.Context(), jobID)
+	if frames == nil {
+		frames = []*models.FrameJob{}
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"id":               job.ID,
+		"saved_project_id": job.SavedProjectID,
+		"name":             job.Name,
+		"step":             job.Step,
+		"render_progress":  job.RenderProgress,
+		"priority_queue":   job.PriorityQueue,
+		"price_type":       job.PriceType,
+		"paid_price_minor": job.PaidPriceMinor,
+		"quality":          job.Quality,
+		"resolution":       job.Resolution,
+		"frame_rate":       job.FrameRate,
+		"duration_sec":     job.DurationSec,
+		"has_voiceover":    job.HasVoiceover,
+		"image_preview_b64": job.ImagePreviewB64,
+		"failed_message":   job.FailedMessage,
+		"export_id":        job.ExportID,
+		"queued_at":        job.QueuedAt,
+		"started_at":       job.StartedAt,
+		"completed_at":     job.CompletedAt,
+		"retry_count":      job.RetryCount,
+		"repair_attempts":  job.RepairAttempts,
+		"frame_jobs":       frames,
+	})
+}
+
+// POST /v1/renders/:job_id/cancel
+func (h *RenderHandler) Cancel(c *gin.Context) {
+	userID := middleware.GetUserID(c)
+	jobID, err := uuid.Parse(c.Param("job_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid job_id"})
+		return
+	}
+	cancelled, err := h.store.CancelJob(c.Request.Context(), jobID, userID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"cancelled":           cancelled,
+		"refund_amount_minor": 0,
+	})
+}
+
+// POST /v1/renders/:job_id/retry
+func (h *RenderHandler) Retry(c *gin.Context) {
+	userID := middleware.GetUserID(c)
+	tenantID := middleware.GetTenantID(c)
+	jobID, err := uuid.Parse(c.Param("job_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid job_id"})
+		return
+	}
+	original, err := h.store.GetJobByID(c.Request.Context(), jobID, userID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, models.APIError{Code: "not_found", Message: err.Error()})
+		return
+	}
+	// Create a new job cloning the original config
+	req := &models.RenderJobCreateRequest{
+		SavedProjectID: original.SavedProjectID,
+		Quality:        original.Quality,
+		Resolution:     original.Resolution,
+		FrameRate:      &original.FrameRate,
+	}
+	newJob, err := h.store.CreateJob(c.Request.Context(), userID, tenantID, req)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	c.JSON(http.StatusCreated, newJob)
+}
+
+// GET /v1/renders/:job_id/progress
+func (h *RenderHandler) Progress(c *gin.Context) {
+	userID := middleware.GetUserID(c)
+	jobID, err := uuid.Parse(c.Param("job_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid job_id"})
+		return
+	}
+	job, err := h.store.GetJobByID(c.Request.Context(), jobID, userID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, models.APIError{Code: "not_found", Message: err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"job_id":         job.ID,
+		"step":           job.Step,
+		"progress":       job.RenderProgress,
+		"current_frame":  nil,
+		"total_frames":   nil,
+		"eta_seconds":    nil,
+		"preview_b64":    job.ImagePreviewB64,
+		"active_nodes":   job.CurrentActiveNodes,
+		"message":        job.FailedMessage,
+	})
+}
+
+// GET /v1/renders/:job_id/logs
+func (h *RenderHandler) Logs(c *gin.Context) {
+	// Logs are stored externally (MinIO/ELK). Return empty for now — node agents push logs elsewhere.
+	c.JSON(http.StatusOK, gin.H{"logs": []any{}})
+}

services/render/internal/handlers/snapshots.go

@@ -0,0 +1,80 @@
+package handlers
+
+import (
+	"crypto/sha256"
+	"fmt"
+	"net/http"
+
+	"github.com/flatrender/render-svc/internal/db"
+	"github.com/flatrender/render-svc/internal/middleware"
+	"github.com/flatrender/render-svc/internal/models"
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+)
+
+type SnapshotHandler struct {
+	store *db.Store
+}
+
+func NewSnapshotHandler(store *db.Store) *SnapshotHandler {
+	return &SnapshotHandler{store: store}
+}
+
+// POST /v1/snapshots
+func (h *SnapshotHandler) Create(c *gin.Context) {
+	userID := middleware.GetUserID(c)
+	tenantID := middleware.GetTenantID(c)
+
+	var req models.SnapshotCreateRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: err.Error()})
+		return
+	}
+
+	// Deterministic cache key from inputs
+	hash := fmt.Sprintf("%x", sha256.Sum256([]byte(
+		fmt.Sprintf("%s:%s:%d", req.SavedProjectID, req.SceneKey, req.FrameNumber),
+	)))
+
+	// Check cache first
+	cached, err := h.store.GetCachedSnapshot(c.Request.Context(),
+		req.SavedProjectID, req.SceneKey, req.FrameNumber, hash)
+	if err == nil && cached != nil {
+		c.JSON(http.StatusAccepted, gin.H{
+			"snapshot_id":   cached.ID,
+			"status":        "Cached",
+			"image_url":     cached.ImageURL,
+			"thumbnail_url": cached.ThumbnailURL,
+			"expires_at":    cached.ExpiresAt,
+		})
+		return
+	}
+
+	snap, err := h.store.CreateSnapshot(c.Request.Context(), userID, tenantID, &req, hash)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	c.JSON(http.StatusAccepted, gin.H{
+		"snapshot_id":   snap.ID,
+		"status":        "Pending",
+		"image_url":     nil,
+		"thumbnail_url": nil,
+		"expires_at":    snap.ExpiresAt,
+	})
+}
+
+// GET /v1/snapshots/:snapshot_id
+func (h *SnapshotHandler) Get(c *gin.Context) {
+	snapID, err := uuid.Parse(c.Param("snapshot_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid snapshot_id"})
+		return
+	}
+	snap, err := h.store.GetSnapshotByID(c.Request.Context(), snapID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, models.APIError{Code: "not_found", Message: err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, snap)
+}