CUB-113: implement core CRUD API endpoints

2026-05-06 20:57:32 -04:00
parent 3ac8432360 fca2ef5b84
commit 62d74beba4
19 changed files with 1496 additions and 3 deletions
--- a/backend/go.mod
+++ b/backend/go.mod
@@ -7,3 +7,12 @@ require (
 	github.com/jackc/pgx/v5 v5.7.4
 	github.com/kelseyhightower/envconfig v1.4.0
 )
+
+require (
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
+	golang.org/x/crypto v0.31.0 // indirect
+	golang.org/x/sync v0.10.0 // indirect
+	golang.org/x/text v0.21.0 // indirect
+)
--- a/backend/go.sum
+++ b/backend/go.sum
@@ -0,0 +1,32 @@
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-chi/chi/v5 v5.2.0 h1:Aj1EtB0qR2Rdo2dG4O94RIU35w2lvQSj6BRA4+qwFL0=
+github.com/go-chi/chi/v5 v5.2.0/go.mod h1:DslCQbL2OYiznFReuXYUmQ2hGd1aDpCnlMNITLSKoi8=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.7.4 h1:9wKznZrhWa2QiHL+NjTSPP6yjl3451BX3imWDnokYlg=
+github.com/jackc/pgx/v5 v5.7.4/go.mod h1:ncY89UGWxg82EykZUwSpUKEfccBGGYq1xjrOpsbsfGQ=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/kelseyhightower/envconfig v1.4.0 h1:Im6hONhd3pLkfDFsbRgu68RDNkGF1r3dvMUtDTo2cv8=
+github.com/kelseyhightower/envconfig v1.4.0/go.mod h1:cccZRl6mQpaq41TPp5QxidR+Sa3axMbJDNb//FQX6Gg=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+golang.org/x/crypto v0.31.0 h1:ihbySMvVjLAeSH1IbfcRTkD/iNscyz8rGzjF/E5hV6U=
+golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
+golang.org/x/sync v0.10.0 h1:3NQrjDixjgGwUOCaF8w2+VYHv0Ve/vGYSbdkTa98gmQ=
+golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
+golang.org/x/text v0.21.0 h1:zyQAAkrwaneQ066sspRyJaG9VNi/YJ1NfzcGB3hZ/qo=
+golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
--- a/backend/internal/dtos/dtos.go
+++ b/backend/internal/dtos/dtos.go
@@ -0,0 +1,67 @@
+// Package dtos defines request/response data transfer objects for the Extrudex API.
+// DTOs keep HTTP serialization concerns separate from domain models.
+package dtos
+
+// ============================================================================
+// Common Response Wrappers
+// ============================================================================
+
+// ListResponse wraps a paginated collection response.
+type ListResponse struct {
+	Data   any `json:"data"`
+	Total  int `json:"total"`
+	Limit  int `json:"limit"`
+	Offset int `json:"offset"`
+}
+
+// SingleResponse wraps a single-item response.
+type SingleResponse struct {
+	Data any `json:"data"`
+}
+
+// ErrorResponse is the standard error payload for all API errors.
+type ErrorResponse struct {
+	Error string `json:"error"`
+	Code  int    `json:"code"`
+}
+
+// ============================================================================
+// Filament DTOs
+// ============================================================================
+
+// CreateFilamentRequest is the POST body for creating a new filament spool.
+type CreateFilamentRequest struct {
+	Name                  string  `json:"name"`
+	MaterialBaseID        int     `json:"material_base_id"`
+	MaterialFinishID      int     `json:"material_finish_id"`
+	MaterialModifierID    *int    `json:"material_modifier_id,omitempty"`
+	ColorHex             string  `json:"color_hex"`
+	Brand                *string `json:"brand,omitempty"`
+	DiameterMM           *float64 `json:"diameter_mm,omitempty"` // defaults to 1.75
+	InitialGrams         int     `json:"initial_grams"`
+	RemainingGrams       int     `json:"remaining_grams"`
+	SpoolWeightGrams     *int    `json:"spool_weight_grams,omitempty"`
+	CostUSD              *float64 `json:"cost_usd,omitempty"`
+	LowStockThresholdGrams *int  `json:"low_stock_threshold_grams,omitempty"` // defaults to 50
+	Notes                *string `json:"notes,omitempty"`
+	Barcode              *string `json:"barcode,omitempty"`
+}
+
+// UpdateFilamentRequest is the PUT body for partially updating a filament spool.
+// All fields are optional — only non-nil fields are applied.
+type UpdateFilamentRequest struct {
+	Name                  *string  `json:"name,omitempty"`
+	MaterialBaseID        *int     `json:"material_base_id,omitempty"`
+	MaterialFinishID      *int     `json:"material_finish_id,omitempty"`
+	MaterialModifierID    *int     `json:"material_modifier_id,omitempty"`
+	ColorHex             *string  `json:"color_hex,omitempty"`
+	Brand                *string  `json:"brand,omitempty"`
+	DiameterMM           *float64 `json:"diameter_mm,omitempty"`
+	InitialGrams         *int     `json:"initial_grams,omitempty"`
+	RemainingGrams       *int     `json:"remaining_grams,omitempty"`
+	SpoolWeightGrams     *int     `json:"spool_weight_grams,omitempty"`
+	CostUSD              *float64 `json:"cost_usd,omitempty"`
+	LowStockThresholdGrams *int   `json:"low_stock_threshold_grams,omitempty"`
+	Notes                *string  `json:"notes,omitempty"`
+	Barcode              *string  `json:"barcode,omitempty"`
+}
--- a/backend/internal/handlers/filament_handler.go
+++ b/backend/internal/handlers/filament_handler.go
@@ -0,0 +1,273 @@
+package handlers
+
+import (
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"strconv"
+
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/dtos"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/models"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/repositories"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/services"
+	"github.com/go-chi/chi/v5"
+)
+
+// FilamentHandler handles HTTP requests for filament spool CRUD operations.
+type FilamentHandler struct {
+	service *services.FilamentService
+}
+
+// NewFilamentHandler creates a FilamentHandler with the given service.
+func NewFilamentHandler(service *services.FilamentService) *FilamentHandler {
+	return &FilamentHandler{service: service}
+}
+
+// List handles GET /api/filaments — returns paginated, filtered spools.
+func (h *FilamentHandler) List(w http.ResponseWriter, r *http.Request) {
+	limit, offset := parsePagination(r)
+	filter := repositories.FilamentFilter{
+		Material: r.URL.Query().Get("material"),
+		Finish:   r.URL.Query().Get("finish"),
+		Color:    r.URL.Query().Get("color"),
+		LowStock: r.URL.Query().Get("low_stock") == "true",
+		Limit:    limit,
+		Offset:   offset,
+	}
+
+	spools, total, err := h.service.List(r.Context(), filter)
+	if err != nil {
+		slog.Error("failed to list filaments", "error", err)
+		writeJSON(w, http.StatusInternalServerError, dtos.ErrorResponse{
+			Error: "internal server error",
+			Code:  http.StatusInternalServerError,
+		})
+		return
+	}
+
+	writeJSON(w, http.StatusOK, dtos.ListResponse{
+		Data:   spools,
+		Total:  total,
+		Limit:  limit,
+		Offset: offset,
+	})
+}
+
+// Get handles GET /api/filaments/{id} — returns a single spool.
+func (h *FilamentHandler) Get(w http.ResponseWriter, r *http.Request) {
+	id, err := strconv.Atoi(chi.URLParam(r, "id"))
+	if err != nil {
+		writeJSON(w, http.StatusBadRequest, dtos.ErrorResponse{
+			Error: "invalid filament ID",
+			Code:  http.StatusBadRequest,
+		})
+		return
+	}
+
+	spool, err := h.service.GetByID(r.Context(), id)
+	if err != nil {
+		slog.Error("failed to get filament", "id", id, "error", err)
+		writeJSON(w, http.StatusInternalServerError, dtos.ErrorResponse{
+			Error: "internal server error",
+			Code:  http.StatusInternalServerError,
+		})
+		return
+	}
+	if spool == nil {
+		writeJSON(w, http.StatusNotFound, dtos.ErrorResponse{
+			Error: "filament not found",
+			Code:  http.StatusNotFound,
+		})
+		return
+	}
+
+	writeJSON(w, http.StatusOK, dtos.SingleResponse{Data: spool})
+}
+
+// Create handles POST /api/filaments — creates a new filament spool.
+func (h *FilamentHandler) Create(w http.ResponseWriter, r *http.Request) {
+	var req dtos.CreateFilamentRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeJSON(w, http.StatusBadRequest, dtos.ErrorResponse{
+			Error: "invalid request body",
+			Code:  http.StatusBadRequest,
+		})
+		return
+	}
+
+	// Validate required fields.
+	if err := services.ValidateCreateFilamentRequest(req); err != nil {
+		writeJSON(w, http.StatusBadRequest, dtos.ErrorResponse{
+			Error: "validation failed: " + err.Error(),
+			Code:  http.StatusBadRequest,
+		})
+		return
+	}
+
+	// Build domain model.
+	spool := models.FilamentSpool{
+		Name:                  req.Name,
+		MaterialBaseID:        req.MaterialBaseID,
+		MaterialFinishID:      req.MaterialFinishID,
+		MaterialModifierID:    req.MaterialModifierID,
+		ColorHex:             req.ColorHex,
+		Brand:                req.Brand,
+		DiameterMM:           1.75, // default
+		InitialGrams:         req.InitialGrams,
+		RemainingGrams:       req.RemainingGrams,
+		SpoolWeightGrams:     req.SpoolWeightGrams,
+		CostUSD:              req.CostUSD,
+		LowStockThresholdGrams: 50, // default
+		Notes:                req.Notes,
+		Barcode:              req.Barcode,
+	}
+	if req.DiameterMM != nil {
+		spool.DiameterMM = *req.DiameterMM
+	}
+	if req.LowStockThresholdGrams != nil {
+		spool.LowStockThresholdGrams = *req.LowStockThresholdGrams
+	}
+
+	created, err := h.service.Create(r.Context(), &spool)
+	if err != nil {
+		slog.Error("failed to create filament", "error", err)
+		writeJSON(w, http.StatusInternalServerError, dtos.ErrorResponse{
+			Error: "internal server error",
+			Code:  http.StatusInternalServerError,
+		})
+		return
+	}
+
+	writeJSON(w, http.StatusCreated, dtos.SingleResponse{Data: created})
+}
+
+// Update handles PUT /api/filaments/{id} — partially updates a spool.
+func (h *FilamentHandler) Update(w http.ResponseWriter, r *http.Request) {
+	id, err := strconv.Atoi(chi.URLParam(r, "id"))
+	if err != nil {
+		writeJSON(w, http.StatusBadRequest, dtos.ErrorResponse{
+			Error: "invalid filament ID",
+			Code:  http.StatusBadRequest,
+		})
+		return
+	}
+
+	var req dtos.UpdateFilamentRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeJSON(w, http.StatusBadRequest, dtos.ErrorResponse{
+			Error: "invalid request body",
+			Code:  http.StatusBadRequest,
+		})
+		return
+	}
+
+	// Validate update fields.
+	if err := services.ValidateUpdateFilamentRequest(req); err != nil {
+		writeJSON(w, http.StatusBadRequest, dtos.ErrorResponse{
+			Error: "validation failed: " + err.Error(),
+			Code:  http.StatusBadRequest,
+		})
+		return
+	}
+
+	// Build updates map (only non-nil fields).
+	updates := buildFilamentUpdates(req)
+
+	updated, err := h.service.Update(r.Context(), id, updates)
+	if err != nil {
+		slog.Error("failed to update filament", "id", id, "error", err)
+		writeJSON(w, http.StatusInternalServerError, dtos.ErrorResponse{
+			Error: "internal server error",
+			Code:  http.StatusInternalServerError,
+		})
+		return
+	}
+	if updated == nil {
+		writeJSON(w, http.StatusNotFound, dtos.ErrorResponse{
+			Error: "filament not found",
+			Code:  http.StatusNotFound,
+		})
+		return
+	}
+
+	writeJSON(w, http.StatusOK, dtos.SingleResponse{Data: updated})
+}
+
+// Delete handles DELETE /api/filaments/{id} — soft-deletes a spool.
+func (h *FilamentHandler) Delete(w http.ResponseWriter, r *http.Request) {
+	id, err := strconv.Atoi(chi.URLParam(r, "id"))
+	if err != nil {
+		writeJSON(w, http.StatusBadRequest, dtos.ErrorResponse{
+			Error: "invalid filament ID",
+			Code:  http.StatusBadRequest,
+		})
+		return
+	}
+
+	deleted, err := h.service.SoftDelete(r.Context(), id)
+	if err != nil {
+		slog.Error("failed to delete filament", "id", id, "error", err)
+		writeJSON(w, http.StatusInternalServerError, dtos.ErrorResponse{
+			Error: "internal server error",
+			Code:  http.StatusInternalServerError,
+		})
+		return
+	}
+	if !deleted {
+		writeJSON(w, http.StatusNotFound, dtos.ErrorResponse{
+			Error: "filament not found",
+			Code:  http.StatusNotFound,
+		})
+		return
+	}
+
+	w.WriteHeader(http.StatusNoContent)
+}
+
+// buildFilamentUpdates converts an UpdateFilamentRequest to a map of column→value.
+func buildFilamentUpdates(req dtos.UpdateFilamentRequest) map[string]interface{} {
+	updates := make(map[string]interface{})
+	if req.Name != nil {
+		updates["name"] = *req.Name
+	}
+	if req.MaterialBaseID != nil {
+		updates["material_base_id"] = *req.MaterialBaseID
+	}
+	if req.MaterialFinishID != nil {
+		updates["material_finish_id"] = *req.MaterialFinishID
+	}
+	if req.MaterialModifierID != nil {
+		updates["material_modifier_id"] = *req.MaterialModifierID
+	}
+	if req.ColorHex != nil {
+		updates["color_hex"] = *req.ColorHex
+	}
+	if req.Brand != nil {
+		updates["brand"] = *req.Brand
+	}
+	if req.DiameterMM != nil {
+		updates["diameter_mm"] = *req.DiameterMM
+	}
+	if req.InitialGrams != nil {
+		updates["initial_grams"] = *req.InitialGrams
+	}
+	if req.RemainingGrams != nil {
+		updates["remaining_grams"] = *req.RemainingGrams
+	}
+	if req.SpoolWeightGrams != nil {
+		updates["spool_weight_grams"] = *req.SpoolWeightGrams
+	}
+	if req.CostUSD != nil {
+		updates["cost_usd"] = *req.CostUSD
+	}
+	if req.LowStockThresholdGrams != nil {
+		updates["low_stock_threshold_grams"] = *req.LowStockThresholdGrams
+	}
+	if req.Notes != nil {
+		updates["notes"] = *req.Notes
+	}
+	if req.Barcode != nil {
+		updates["barcode"] = *req.Barcode
+	}
+	return updates
+}
--- a/backend/internal/handlers/helpers.go
+++ b/backend/internal/handlers/helpers.go
@@ -0,0 +1,51 @@
+package handlers
+
+import (
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"strconv"
+
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/dtos"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/services"
+)
+
+// writeJSON serializes v as JSON to the response writer with the given status code.
+// Logs an error if encoding fails.
+func writeJSON(w http.ResponseWriter, status int, v interface{}) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	if err := json.NewEncoder(w).Encode(v); err != nil {
+		slog.Error("failed to encode JSON response", "error", err)
+	}
+}
+
+// parsePagination reads limit and offset query parameters with defaults of 20 and 0.
+func parsePagination(r *http.Request) (limit, offset int) {
+	limit = 20
+	offset = 0
+
+	if l := r.URL.Query().Get("limit"); l != "" {
+		if parsed, err := strconv.Atoi(l); err == nil && parsed > 0 {
+			limit = parsed
+		}
+	}
+	if o := r.URL.Query().Get("offset"); o != "" {
+		if parsed, err := strconv.Atoi(o); err == nil && parsed >= 0 {
+			offset = parsed
+		}
+	}
+	return
+}
+
+// ValidateCreateFilamentRequest validates a CreateFilamentRequest DTO.
+// Re-exports the service-layer validator for handler use.
+func ValidateCreateFilamentRequest(req dtos.CreateFilamentRequest) error {
+	return services.ValidateCreateFilamentRequest(req)
+}
+
+// ValidateUpdateFilamentRequest validates an UpdateFilamentRequest DTO.
+// Re-exports the service-layer validator for handler use.
+func ValidateUpdateFilamentRequest(req dtos.UpdateFilamentRequest) error {
+	return services.ValidateUpdateFilamentRequest(req)
+}
--- a/backend/internal/handlers/material_handler.go
+++ b/backend/internal/handlers/material_handler.go
@@ -0,0 +1,34 @@
+package handlers
+
+import (
+	"log/slog"
+	"net/http"
+
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/dtos"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/repositories"
+)
+
+// MaterialHandler handles requests for material lookup data.
+type MaterialHandler struct {
+	repo *repositories.MaterialRepository
+}
+
+// NewMaterialHandler creates a MaterialHandler with the given repository.
+func NewMaterialHandler(repo *repositories.MaterialRepository) *MaterialHandler {
+	return &MaterialHandler{repo: repo}
+}
+
+// List handles GET /api/materials — returns all material bases.
+func (h *MaterialHandler) List(w http.ResponseWriter, r *http.Request) {
+	materials, err := h.repo.GetAll(r.Context())
+	if err != nil {
+		slog.Error("failed to list materials", "error", err)
+		writeJSON(w, http.StatusInternalServerError, dtos.ErrorResponse{
+			Error: "internal server error",
+			Code:  http.StatusInternalServerError,
+		})
+		return
+	}
+
+	writeJSON(w, http.StatusOK, dtos.SingleResponse{Data: materials})
+}
--- a/backend/internal/handlers/print_job_handler.go
+++ b/backend/internal/handlers/print_job_handler.go
@@ -0,0 +1,60 @@
+package handlers
+
+import (
+	"log/slog"
+	"net/http"
+	"strconv"
+
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/dtos"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/repositories"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/services"
+)
+
+// PrintJobHandler handles HTTP requests for print job operations.
+type PrintJobHandler struct {
+	service *services.PrintJobService
+}
+
+// NewPrintJobHandler creates a PrintJobHandler with the given service.
+func NewPrintJobHandler(service *services.PrintJobService) *PrintJobHandler {
+	return &PrintJobHandler{service: service}
+}
+
+// List handles GET /api/print-jobs — returns paginated, filtered print jobs.
+func (h *PrintJobHandler) List(w http.ResponseWriter, r *http.Request) {
+	limit, offset := parsePagination(r)
+	filter := repositories.PrintJobFilter{
+		Status: r.URL.Query().Get("status"),
+		Limit:  limit,
+		Offset: offset,
+	}
+
+	if pidStr := r.URL.Query().Get("printer_id"); pidStr != "" {
+		pid, err := strconv.Atoi(pidStr)
+		if err != nil {
+			writeJSON(w, http.StatusBadRequest, dtos.ErrorResponse{
+				Error: "invalid printer_id",
+				Code:  http.StatusBadRequest,
+			})
+			return
+		}
+		filter.PrinterID = &pid
+	}
+
+	jobs, total, err := h.service.List(r.Context(), filter)
+	if err != nil {
+		slog.Error("failed to list print jobs", "error", err)
+		writeJSON(w, http.StatusInternalServerError, dtos.ErrorResponse{
+			Error: "internal server error",
+			Code:  http.StatusInternalServerError,
+		})
+		return
+	}
+
+	writeJSON(w, http.StatusOK, dtos.ListResponse{
+		Data:   jobs,
+		Total:  total,
+		Limit:  limit,
+		Offset: offset,
+	})
+}
--- a/backend/internal/handlers/printer_handler.go
+++ b/backend/internal/handlers/printer_handler.go
@@ -0,0 +1,34 @@
+package handlers
+
+import (
+	"log/slog"
+	"net/http"
+
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/dtos"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/services"
+)
+
+// PrinterHandler handles HTTP requests for printer listings.
+type PrinterHandler struct {
+	service *services.PrinterService
+}
+
+// NewPrinterHandler creates a PrinterHandler with the given service.
+func NewPrinterHandler(service *services.PrinterService) *PrinterHandler {
+	return &PrinterHandler{service: service}
+}
+
+// List handles GET /api/printers — returns all printers with printer_type info.
+func (h *PrinterHandler) List(w http.ResponseWriter, r *http.Request) {
+	printers, err := h.service.List(r.Context())
+	if err != nil {
+		slog.Error("failed to list printers", "error", err)
+		writeJSON(w, http.StatusInternalServerError, dtos.ErrorResponse{
+			Error: "internal server error",
+			Code:  http.StatusInternalServerError,
+		})
+		return
+	}
+
+	writeJSON(w, http.StatusOK, dtos.SingleResponse{Data: printers})
+}
--- a/backend/internal/handlers/usage_log_handler.go
+++ b/backend/internal/handlers/usage_log_handler.go
@@ -0,0 +1,70 @@
+package handlers
+
+import (
+	"log/slog"
+	"net/http"
+	"strconv"
+
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/dtos"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/repositories"
+)
+
+// UsageLogHandler handles HTTP requests for usage log operations.
+type UsageLogHandler struct {
+	repo *repositories.UsageLogRepository
+}
+
+// NewUsageLogHandler creates a UsageLogHandler with the given repository.
+func NewUsageLogHandler(repo *repositories.UsageLogRepository) *UsageLogHandler {
+	return &UsageLogHandler{repo: repo}
+}
+
+// List handles GET /api/usage-logs — returns paginated, filtered usage logs.
+func (h *UsageLogHandler) List(w http.ResponseWriter, r *http.Request) {
+	limit, offset := parsePagination(r)
+	filter := repositories.UsageLogFilter{
+		Limit:  limit,
+		Offset: offset,
+	}
+
+	if sidStr := r.URL.Query().Get("spool_id"); sidStr != "" {
+		sid, err := strconv.Atoi(sidStr)
+		if err != nil {
+			writeJSON(w, http.StatusBadRequest, dtos.ErrorResponse{
+				Error: "invalid spool_id",
+				Code:  http.StatusBadRequest,
+			})
+			return
+		}
+		filter.SpoolID = &sid
+	}
+
+	if jidStr := r.URL.Query().Get("job_id"); jidStr != "" {
+		jid, err := strconv.Atoi(jidStr)
+		if err != nil {
+			writeJSON(w, http.StatusBadRequest, dtos.ErrorResponse{
+				Error: "invalid job_id",
+				Code:  http.StatusBadRequest,
+			})
+			return
+		}
+		filter.JobID = &jid
+	}
+
+	logs, total, err := h.repo.GetAll(r.Context(), filter)
+	if err != nil {
+		slog.Error("failed to list usage logs", "error", err)
+		writeJSON(w, http.StatusInternalServerError, dtos.ErrorResponse{
+			Error: "internal server error",
+			Code:  http.StatusInternalServerError,
+		})
+		return
+	}
+
+	writeJSON(w, http.StatusOK, dtos.ListResponse{
+		Data:   logs,
+		Total:  total,
+		Limit:  limit,
+		Offset: offset,
+	})
+}
--- a/backend/internal/repositories/.gitkeep
+++ b/backend/internal/repositories/.gitkeep
@@ -1 +0,0 @@
-# Repositories
--- a/backend/internal/repositories/filament_repository.go
+++ b/backend/internal/repositories/filament_repository.go
@@ -0,0 +1,285 @@
+package repositories
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/models"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// FilamentRepository handles database queries for filament_spools.
+type FilamentRepository struct {
+	pool *pgxpool.Pool
+}
+
+// NewFilamentRepository creates a FilamentRepository backed by the given pool.
+func NewFilamentRepository(pool *pgxpool.Pool) *FilamentRepository {
+	return &FilamentRepository{pool: pool}
+}
+
+// FilamentFilter holds query parameters for listing filament spools.
+type FilamentFilter struct {
+	Material string // filter by material_base name (case-insensitive)
+	Finish   string // filter by material_finish name (case-insensitive)
+	Color    string // filter by exact color_hex match
+	LowStock bool   // if true, filter for remaining_grams <= low_stock_threshold_grams
+	Limit    int
+	Offset   int
+}
+
+// spoolScanFields is the common SELECT column list for filament spools with JOINs.
+const spoolScanFields = `
+	s.id, s.name,
+	s.material_base_id,
+	COALESCE(mb.name, '') as material_base_name,
+	COALESCE(mb.density_g_cm3, 0) as material_base_density_g_cm3,
+	COALESCE(mb.extrusion_temp_min, NULL::int) as material_base_extrusion_temp_min,
+	COALESCE(mb.extrusion_temp_max, NULL::int) as material_base_extrusion_temp_max,
+	COALESCE(mb.bed_temp_min, NULL::int) as material_base_bed_temp_min,
+	COALESCE(mb.bed_temp_max, NULL::int) as material_base_bed_temp_max,
+	COALESCE(mb.created_at, s.created_at) as material_base_created_at,
+	COALESCE(mb.updated_at, s.created_at) as material_base_updated_at,
+	s.material_finish_id,
+	COALESCE(mf.name, '') as material_finish_name,
+	mf.description as material_finish_description,
+	COALESCE(mf.created_at, s.created_at) as material_finish_created_at,
+	COALESCE(mf.updated_at, s.created_at) as material_finish_updated_at,
+	s.material_modifier_id,
+	mm.name as material_modifier_name,
+	mm.description as material_modifier_description,
+	mm.created_at as material_modifier_created_at,
+	mm.updated_at as material_modifier_updated_at,
+	s.color_hex, s.brand, s.diameter_mm,
+	s.initial_grams, s.remaining_grams, s.spool_weight_grams,
+	s.cost_usd, s.low_stock_threshold_grams,
+	s.notes, s.barcode,
+	s.deleted_at, s.created_at, s.updated_at`
+
+const spoolFromJoins = `
+	FROM filament_spools s
+	LEFT JOIN material_bases mb ON s.material_base_id = mb.id
+	LEFT JOIN material_finishes mf ON s.material_finish_id = mf.id
+	LEFT JOIN material_modifiers mm ON s.material_modifier_id = mm.id`
+
+// scanSpoolWithJoins scans a full spool row including all JOINed tables.
+func scanSpoolWithJoins(row interface{ Scan(...interface{}) error }) (models.FilamentSpool, error) {
+	var s models.FilamentSpool
+	var mb models.MaterialBase
+	var mf models.MaterialFinish
+	var mfDesc *string
+	var modifierID *int
+	var modName, modDesc *string
+	var modCreatedAt, modUpdatedAt *time.Time
+
+	err := row.Scan(
+		&s.ID, &s.Name,
+		&s.MaterialBaseID,
+		&mb.Name, &mb.DensityGCm3,
+		&mb.ExtrusionTempMin, &mb.ExtrusionTempMax,
+		&mb.BedTempMin, &mb.BedTempMax,
+		&mb.CreatedAt, &mb.UpdatedAt,
+		&s.MaterialFinishID,
+		&mf.Name, &mfDesc,
+		&mf.CreatedAt, &mf.UpdatedAt,
+		&modifierID,
+		&modName, &modDesc,
+		&modCreatedAt, &modUpdatedAt,
+		&s.ColorHex, &s.Brand, &s.DiameterMM,
+		&s.InitialGrams, &s.RemainingGrams, &s.SpoolWeightGrams,
+		&s.CostUSD, &s.LowStockThresholdGrams,
+		&s.Notes, &s.Barcode,
+		&s.DeletedAt, &s.CreatedAt, &s.UpdatedAt,
+	)
+	if err != nil {
+		return s, err
+	}
+
+	mb.ID = s.MaterialBaseID
+	s.MaterialBase = &mb
+
+	mf.ID = s.MaterialFinishID
+	if mfDesc != nil {
+		mf.Description = mfDesc
+	}
+	s.MaterialFinish = &mf
+
+	s.MaterialModifierID = modifierID
+	if modifierID != nil && modName != nil {
+		mm := models.MaterialModifier{
+			ID:   *modifierID,
+			Name: *modName,
+		}
+		if modDesc != nil {
+			mm.Description = modDesc
+		}
+		if modCreatedAt != nil {
+			mm.CreatedAt = *modCreatedAt
+		}
+		if modUpdatedAt != nil {
+			mm.UpdatedAt = *modUpdatedAt
+		}
+		s.MaterialModifier = &mm
+	}
+
+	return s, nil
+}
+
+// GetAll returns filament spools matching the given filters, with pagination.
+// Returns results, total matching count, and any error.
+func (r *FilamentRepository) GetAll(ctx context.Context, filter FilamentFilter) ([]models.FilamentSpool, int, error) {
+	conditions := []string{"s.deleted_at IS NULL"}
+	args := []interface{}{}
+	argIdx := 1
+
+	if filter.Material != "" {
+		conditions = append(conditions, fmt.Sprintf("LOWER(mb.name) = LOWER($%d)", argIdx))
+		args = append(args, filter.Material)
+		argIdx++
+	}
+	if filter.Finish != "" {
+		conditions = append(conditions, fmt.Sprintf("LOWER(mf.name) = LOWER($%d)", argIdx))
+		args = append(args, filter.Finish)
+		argIdx++
+	}
+	if filter.Color != "" {
+		conditions = append(conditions, fmt.Sprintf("s.color_hex = $%d", argIdx))
+		args = append(args, filter.Color)
+		argIdx++
+	}
+	if filter.LowStock {
+		conditions = append(conditions, "s.remaining_grams <= s.low_stock_threshold_grams")
+	}
+
+	whereClause := ""
+	if len(conditions) > 0 {
+		whereClause = "WHERE " + strings.Join(conditions, " AND ")
+	}
+
+	// Count total.
+	var total int
+	countQuery := "SELECT COUNT(*) " + spoolFromJoins + " " + whereClause
+	if err := r.pool.QueryRow(ctx, countQuery, args...).Scan(&total); err != nil {
+		return nil, 0, err
+	}
+
+	// Query with pagination.
+	dataQuery := "SELECT " + spoolScanFields + " " + spoolFromJoins + " " +
+		whereClause +
+		" ORDER BY s.name ASC" +
+		fmt.Sprintf(" LIMIT $%d OFFSET $%d", argIdx, argIdx+1)
+
+	dataArgs := make([]interface{}, len(args))
+	copy(dataArgs, args)
+	dataArgs = append(dataArgs, filter.Limit, filter.Offset)
+
+	rows, err := r.pool.Query(ctx, dataQuery, dataArgs...)
+	if err != nil {
+		return nil, 0, err
+	}
+	defer rows.Close()
+
+	var spools []models.FilamentSpool
+	for rows.Next() {
+		s, err := scanSpoolWithJoins(rows)
+		if err != nil {
+			return nil, 0, err
+		}
+		spools = append(spools, s)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, 0, err
+	}
+	if spools == nil {
+		spools = []models.FilamentSpool{}
+	}
+
+	return spools, total, nil
+}
+
+// GetByID returns a single filament spool by ID with JOINed data.
+// Returns nil if not found or soft-deleted.
+func (r *FilamentRepository) GetByID(ctx context.Context, id int) (*models.FilamentSpool, error) {
+	query := "SELECT " + spoolScanFields + " " + spoolFromJoins +
+		" WHERE s.id = $1 AND s.deleted_at IS NULL"
+
+	row := r.pool.QueryRow(ctx, query, id)
+	s, err := scanSpoolWithJoins(row)
+	if err != nil {
+		return nil, err
+	}
+	return &s, nil
+}
+
+// Create inserts a new filament spool and returns the created spool with JOINed data.
+func (r *FilamentRepository) Create(ctx context.Context, spool *models.FilamentSpool) (*models.FilamentSpool, error) {
+	var id int
+	err := r.pool.QueryRow(ctx, `
+		INSERT INTO filament_spools (
+			name, material_base_id, material_finish_id, material_modifier_id,
+			color_hex, brand, diameter_mm, initial_grams, remaining_grams,
+			spool_weight_grams, cost_usd, low_stock_threshold_grams,
+			notes, barcode
+		) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14)
+		RETURNING id
+	`,
+		spool.Name, spool.MaterialBaseID, spool.MaterialFinishID, spool.MaterialModifierID,
+		spool.ColorHex, spool.Brand, spool.DiameterMM, spool.InitialGrams, spool.RemainingGrams,
+		spool.SpoolWeightGrams, spool.CostUSD, spool.LowStockThresholdGrams,
+		spool.Notes, spool.Barcode,
+	).Scan(&id)
+	if err != nil {
+		return nil, err
+	}
+
+	return r.GetByID(ctx, id)
+}
+
+// Update applies partial updates to an existing filament spool.
+// Only non-nil fields in the update map are applied.
+// Returns the updated spool.
+func (r *FilamentRepository) Update(ctx context.Context, id int, updates map[string]interface{}) (*models.FilamentSpool, error) {
+	if len(updates) == 0 {
+		return r.GetByID(ctx, id)
+	}
+
+	setClauses := []string{"updated_at = NOW()"}
+	args := []interface{}{}
+	argIdx := 1
+
+	for col, val := range updates {
+		setClauses = append(setClauses, fmt.Sprintf("%s = $%d", col, argIdx))
+		args = append(args, val)
+		argIdx++
+	}
+
+	args = append(args, id)
+	query := fmt.Sprintf("UPDATE filament_spools SET %s WHERE id = $%d AND deleted_at IS NULL",
+		strings.Join(setClauses, ", "), argIdx)
+
+	result, err := r.pool.Exec(ctx, query, args...)
+	if err != nil {
+		return nil, err
+	}
+	if result.RowsAffected() == 0 {
+		return nil, nil // not found or deleted
+	}
+
+	return r.GetByID(ctx, id)
+}
+
+// SoftDelete marks a filament spool as deleted by setting deleted_at = NOW().
+// Returns true if a row was affected.
+func (r *FilamentRepository) SoftDelete(ctx context.Context, id int) (bool, error) {
+	result, err := r.pool.Exec(ctx, `
+		UPDATE filament_spools
+		SET deleted_at = NOW(), updated_at = NOW()
+		WHERE id = $1 AND deleted_at IS NULL
+	`, id)
+	if err != nil {
+		return false, err
+	}
+	return result.RowsAffected() > 0, nil
+}
--- a/backend/internal/repositories/material_repository.go
+++ b/backend/internal/repositories/material_repository.go
@@ -0,0 +1,54 @@
+// Package repositories provides data access logic backed by PostgreSQL via pgxpool.
+package repositories
+
+import (
+	"context"
+
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/models"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// MaterialRepository handles database queries for material lookup tables.
+type MaterialRepository struct {
+	pool *pgxpool.Pool
+}
+
+// NewMaterialRepository creates a MaterialRepository backed by the given pool.
+func NewMaterialRepository(pool *pgxpool.Pool) *MaterialRepository {
+	return &MaterialRepository{pool: pool}
+}
+
+// GetAll returns all material bases ordered by name.
+func (r *MaterialRepository) GetAll(ctx context.Context) ([]models.MaterialBase, error) {
+	rows, err := r.pool.Query(ctx, `
+		SELECT id, name, density_g_cm3, extrusion_temp_min, extrusion_temp_max,
+		       bed_temp_min, bed_temp_max, created_at, updated_at
+		FROM material_bases
+		ORDER BY name
+	`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var materials []models.MaterialBase
+	for rows.Next() {
+		var m models.MaterialBase
+		if err := rows.Scan(
+			&m.ID, &m.Name, &m.DensityGCm3,
+			&m.ExtrusionTempMin, &m.ExtrusionTempMax,
+			&m.BedTempMin, &m.BedTempMax,
+			&m.CreatedAt, &m.UpdatedAt,
+		); err != nil {
+			return nil, err
+		}
+		materials = append(materials, m)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	if materials == nil {
+		materials = []models.MaterialBase{}
+	}
+	return materials, nil
+}
--- a/backend/internal/repositories/print_job_repository.go
+++ b/backend/internal/repositories/print_job_repository.go
@@ -0,0 +1,157 @@
+package repositories
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/models"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// PrintJobRepository handles database queries for print_jobs.
+type PrintJobRepository struct {
+	pool *pgxpool.Pool
+}
+
+// NewPrintJobRepository creates a PrintJobRepository backed by the given pool.
+func NewPrintJobRepository(pool *pgxpool.Pool) *PrintJobRepository {
+	return &PrintJobRepository{pool: pool}
+}
+
+// PrintJobFilter holds query parameters for listing print jobs.
+type PrintJobFilter struct {
+	Status    string // filter by job_status name (case-insensitive)
+	PrinterID *int   // filter by printer_id
+	Limit     int
+	Offset    int
+}
+
+// scanPrintJobWithJoins scans a print_job row with JOINed tables.
+func (r *PrintJobRepository) scanPrintJobWithJoins(row interface{ Scan(...interface{}) error }) (models.PrintJob, error) {
+	var pj models.PrintJob
+	var js models.JobStatus
+
+	err := row.Scan(
+		&pj.ID, &pj.PrinterID, &pj.FilamentSpoolID,
+		&pj.JobName, &pj.FileName,
+		&pj.JobStatusID,
+		&pj.StartedAt, &pj.CompletedAt,
+		&pj.DurationSeconds, &pj.EstimatedDurationSeconds,
+		&pj.TotalMMExtruded, &pj.TotalGramsUsed, &pj.TotalCostUSD,
+		&pj.Notes,
+		&pj.DeletedAt, &pj.CreatedAt, &pj.UpdatedAt,
+		&js.ID, &js.Name,
+		&js.CreatedAt, &js.UpdatedAt,
+	)
+	if err != nil {
+		return pj, err
+	}
+
+	pj.JobStatus = &js
+	return pj, nil
+}
+
+// GetAll returns print jobs matching the given filters, with pagination.
+func (r *PrintJobRepository) GetAll(ctx context.Context, filter PrintJobFilter) ([]models.PrintJob, int, error) {
+	conditions := []string{"pj.deleted_at IS NULL"}
+	args := []interface{}{}
+	argIdx := 1
+
+	if filter.Status != "" {
+		conditions = append(conditions, fmt.Sprintf("LOWER(js.name) = LOWER($%d)", argIdx))
+		args = append(args, filter.Status)
+		argIdx++
+	}
+	if filter.PrinterID != nil {
+		conditions = append(conditions, fmt.Sprintf("pj.printer_id = $%d", argIdx))
+		args = append(args, *filter.PrinterID)
+		argIdx++
+	}
+
+	whereClause := ""
+	if len(conditions) > 0 {
+		whereClause = "WHERE " + strings.Join(conditions, " AND ")
+	}
+
+	// Count.
+	var total int
+	countQuery := `SELECT COUNT(*)
+		FROM print_jobs pj
+		LEFT JOIN job_statuses js ON pj.job_status_id = js.id
+	` + " " + whereClause
+	if err := r.pool.QueryRow(ctx, countQuery, args...).Scan(&total); err != nil {
+		return nil, 0, err
+	}
+
+	// Query with pagination.
+	dataQuery := `SELECT
+		pj.id, pj.printer_id, pj.filament_spool_id,
+		pj.job_name, pj.file_name,
+		pj.job_status_id,
+		pj.started_at, pj.completed_at,
+		pj.duration_seconds, pj.estimated_duration_seconds,
+		pj.total_mm_extruded, pj.total_grams_used, pj.total_cost_usd,
+		pj.notes,
+		pj.deleted_at, pj.created_at, pj.updated_at,
+		js.id, js.name,
+		js.created_at, js.updated_at
+	FROM print_jobs pj
+	LEFT JOIN job_statuses js ON pj.job_status_id = js.id
+	` + whereClause +
+		" ORDER BY pj.created_at DESC" +
+		fmt.Sprintf(" LIMIT $%d OFFSET $%d", argIdx, argIdx+1)
+
+	dataArgs := make([]interface{}, len(args))
+	copy(dataArgs, args)
+	dataArgs = append(dataArgs, filter.Limit, filter.Offset)
+
+	rows, err := r.pool.Query(ctx, dataQuery, dataArgs...)
+	if err != nil {
+		return nil, 0, err
+	}
+	defer rows.Close()
+
+	var jobs []models.PrintJob
+	for rows.Next() {
+		pj, err := r.scanPrintJobWithJoins(rows)
+		if err != nil {
+			return nil, 0, err
+		}
+		jobs = append(jobs, pj)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, 0, err
+	}
+	if jobs == nil {
+		jobs = []models.PrintJob{}
+	}
+
+	return jobs, total, nil
+}
+
+// GetByID returns a single print job by ID with JOINed job_status.
+func (r *PrintJobRepository) GetByID(ctx context.Context, id int) (*models.PrintJob, error) {
+	row := r.pool.QueryRow(ctx, `
+		SELECT
+			pj.id, pj.printer_id, pj.filament_spool_id,
+			pj.job_name, pj.file_name,
+			pj.job_status_id,
+			pj.started_at, pj.completed_at,
+			pj.duration_seconds, pj.estimated_duration_seconds,
+			pj.total_mm_extruded, pj.total_grams_used, pj.total_cost_usd,
+			pj.notes,
+			pj.deleted_at, pj.created_at, pj.updated_at,
+			js.id, js.name,
+			js.created_at, js.updated_at
+		FROM print_jobs pj
+		LEFT JOIN job_statuses js ON pj.job_status_id = js.id
+		WHERE pj.id = $1 AND pj.deleted_at IS NULL
+	`, id)
+
+	pj, err := r.scanPrintJobWithJoins(row)
+	if err != nil {
+		return nil, err
+	}
+	return &pj, nil
+}
--- a/backend/internal/repositories/printer_repository.go
+++ b/backend/internal/repositories/printer_repository.go
@@ -0,0 +1,78 @@
+package repositories
+
+import (
+	"context"
+
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/models"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// PrinterRepository handles database queries for printers.
+type PrinterRepository struct {
+	pool *pgxpool.Pool
+}
+
+// NewPrinterRepository creates a PrinterRepository backed by the given pool.
+func NewPrinterRepository(pool *pgxpool.Pool) *PrinterRepository {
+	return &PrinterRepository{pool: pool}
+}
+
+// scanPrinterWithType scans a printer row with JOINed printer_type.
+func (r *PrinterRepository) scanPrinterWithType(row interface{ Scan(...interface{}) error }) (models.Printer, error) {
+	var p models.Printer
+	var pt models.PrinterType
+
+	err := row.Scan(
+		&p.ID, &p.Name, &p.PrinterTypeID,
+		&p.Manufacturer, &p.Model,
+		&p.MoonrakerURL, &p.MoonrakerAPIKey,
+		&p.MQTTBrokerHost, &p.MQTTTopicPrefix,
+		&p.MQTTTLSEnabled, &p.IsActive,
+		&p.CreatedAt, &p.UpdatedAt,
+		&pt.ID, &pt.Name,
+		&pt.CreatedAt, &pt.UpdatedAt,
+	)
+	if err != nil {
+		return p, err
+	}
+
+	p.PrinterType = &pt
+	return p, nil
+}
+
+// GetAll returns all printers joined with their printer_type, ordered by name.
+func (r *PrinterRepository) GetAll(ctx context.Context) ([]models.Printer, error) {
+	rows, err := r.pool.Query(ctx, `
+		SELECT p.id, p.name, p.printer_type_id,
+		       p.manufacturer, p.model,
+		       p.moonraker_url, p.moonraker_api_key,
+		       p.mqtt_broker_host, p.mqtt_topic_prefix,
+		       p.mqtt_tls_enabled, p.is_active,
+		       p.created_at, p.updated_at,
+		       pt.id, pt.name,
+		       pt.created_at, pt.updated_at
+		FROM printers p
+		JOIN printer_types pt ON p.printer_type_id = pt.id
+		ORDER BY p.name
+	`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var printers []models.Printer
+	for rows.Next() {
+		p, err := r.scanPrinterWithType(rows)
+		if err != nil {
+			return nil, err
+		}
+		printers = append(printers, p)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	if printers == nil {
+		printers = []models.Printer{}
+	}
+	return printers, nil
+}
--- a/backend/internal/repositories/usage_log_repository.go
+++ b/backend/internal/repositories/usage_log_repository.go
@@ -0,0 +1,96 @@
+package repositories
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/models"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// UsageLogRepository handles database queries for usage_logs.
+type UsageLogRepository struct {
+	pool *pgxpool.Pool
+}
+
+// NewUsageLogRepository creates a UsageLogRepository backed by the given pool.
+func NewUsageLogRepository(pool *pgxpool.Pool) *UsageLogRepository {
+	return &UsageLogRepository{pool: pool}
+}
+
+// UsageLogFilter holds query parameters for listing usage logs.
+type UsageLogFilter struct {
+	SpoolID *int // filter by filament_spool_id
+	JobID   *int // filter by print_job_id
+	Limit   int
+	Offset  int
+}
+
+// GetAll returns usage logs matching the given filters, with pagination.
+func (r *UsageLogRepository) GetAll(ctx context.Context, filter UsageLogFilter) ([]models.UsageLog, int, error) {
+	conditions := []string{"1=1"}
+	args := []interface{}{}
+	argIdx := 1
+
+	if filter.SpoolID != nil {
+		conditions = append(conditions, fmt.Sprintf("ul.filament_spool_id = $%d", argIdx))
+		args = append(args, *filter.SpoolID)
+		argIdx++
+	}
+	if filter.JobID != nil {
+		conditions = append(conditions, fmt.Sprintf("ul.print_job_id = $%d", argIdx))
+		args = append(args, *filter.JobID)
+		argIdx++
+	}
+
+	whereClause := "WHERE " + fmt.Sprintf("%s", conditions[0])
+	for _, c := range conditions[1:] {
+		whereClause += " AND " + c
+	}
+
+	// Count.
+	var total int
+	countQuery := "SELECT COUNT(*) FROM usage_logs ul " + whereClause
+	if err := r.pool.QueryRow(ctx, countQuery, args...).Scan(&total); err != nil {
+		return nil, 0, err
+	}
+
+	// Query with pagination.
+	dataQuery := `SELECT id, print_job_id, filament_spool_id, mm_extruded,
+	       grams_used, cost_usd, logged_at, created_at
+	FROM usage_logs ul
+	` + whereClause +
+		" ORDER BY ul.logged_at DESC" +
+		fmt.Sprintf(" LIMIT $%d OFFSET $%d", argIdx, argIdx+1)
+
+	dataArgs := make([]interface{}, len(args))
+	copy(dataArgs, args)
+	dataArgs = append(dataArgs, filter.Limit, filter.Offset)
+
+	rows, err := r.pool.Query(ctx, dataQuery, dataArgs...)
+	if err != nil {
+		return nil, 0, err
+	}
+	defer rows.Close()
+
+	var logs []models.UsageLog
+	for rows.Next() {
+		var l models.UsageLog
+		if err := rows.Scan(
+			&l.ID, &l.PrintJobID, &l.FilamentSpoolID,
+			&l.MMExtruded, &l.GramsUsed, &l.CostUSD,
+			&l.LoggedAt, &l.CreatedAt,
+		); err != nil {
+			return nil, 0, err
+		}
+		logs = append(logs, l)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, 0, err
+	}
+	if logs == nil {
+		logs = []models.UsageLog{}
+	}
+
+	return logs, total, nil
+}
--- a/backend/internal/router/router.go
+++ b/backend/internal/router/router.go
@@ -1,12 +1,13 @@
 package router

 import (
-	"log/slog"
 	"net/http"
 	"time"

 	"github.com/CubeCraft-Creations/Extrudex/backend/internal/config"
 	"github.com/CubeCraft-Creations/Extrudex/backend/internal/handlers"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/repositories"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/services"
 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/chi/v5/middleware"
 	"github.com/jackc/pgx/v5/pgxpool"
@@ -41,5 +42,43 @@ func New(cfg *config.Config, dbPool *pgxpool.Pool) chi.Router {
 	healthHandler := handlers.NewHealthHandler(dbPool)
 	r.Get("/health", healthHandler.ServeHTTP)

+	// ── Repositories ──────────────────────────────────────────────────────
+	materialRepo := repositories.NewMaterialRepository(dbPool)
+	filamentRepo := repositories.NewFilamentRepository(dbPool)
+	printerRepo := repositories.NewPrinterRepository(dbPool)
+	printJobRepo := repositories.NewPrintJobRepository(dbPool)
+	usageLogRepo := repositories.NewUsageLogRepository(dbPool)
+
+	// ── Services ──────────────────────────────────────────────────────────
+	filamentService := services.NewFilamentService(filamentRepo)
+	printerService := services.NewPrinterService(printerRepo)
+	printJobService := services.NewPrintJobService(printJobRepo)
+
+	// ── Handlers ──────────────────────────────────────────────────────────
+	materialHandler := handlers.NewMaterialHandler(materialRepo)
+	filamentHandler := handlers.NewFilamentHandler(filamentService)
+	printerHandler := handlers.NewPrinterHandler(printerService)
+	printJobHandler := handlers.NewPrintJobHandler(printJobService)
+	usageLogHandler := handlers.NewUsageLogHandler(usageLogRepo)
+
+	// ── API Routes ────────────────────────────────────────────────────────
+	r.Route("/api", func(r chi.Router) {
+		r.Get("/materials", materialHandler.List)
+
+		r.Route("/filaments", func(r chi.Router) {
+			r.Get("/", filamentHandler.List)
+			r.Post("/", filamentHandler.Create)
+			r.Route("/{id}", func(r chi.Router) {
+				r.Get("/", filamentHandler.Get)
+				r.Put("/", filamentHandler.Update)
+				r.Delete("/", filamentHandler.Delete)
+			})
+		})
+
+		r.Get("/printers", printerHandler.List)
+		r.Get("/print-jobs", printJobHandler.List)
+		r.Get("/usage-logs", usageLogHandler.List)
+	})
+
 	return r
 }
--- a/backend/internal/services/.gitkeep
+++ b/backend/internal/services/.gitkeep
@@ -1 +0,0 @@
-# Services
--- a/backend/internal/services/services.go
+++ b/backend/internal/services/services.go
@@ -0,0 +1,82 @@
+// Package services contains business logic and application services.
+package services
+
+import (
+	"context"
+
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/models"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/repositories"
+)
+
+// FilamentService wraps FilamentRepository with business logic and validation.
+type FilamentService struct {
+	repo *repositories.FilamentRepository
+}
+
+// NewFilamentService creates a FilamentService backed by the given repository.
+func NewFilamentService(repo *repositories.FilamentRepository) *FilamentService {
+	return &FilamentService{repo: repo}
+}
+
+// List returns paginated filament spools filtered by the given criteria.
+func (s *FilamentService) List(ctx context.Context, filter repositories.FilamentFilter) ([]models.FilamentSpool, int, error) {
+	return s.repo.GetAll(ctx, filter)
+}
+
+// GetByID returns a single filament spool by ID.
+func (s *FilamentService) GetByID(ctx context.Context, id int) (*models.FilamentSpool, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+// Create validates and creates a new filament spool.
+func (s *FilamentService) Create(ctx context.Context, spool *models.FilamentSpool) (*models.FilamentSpool, error) {
+	if err := validateFilamentSpool(spool); err != nil {
+		return nil, err
+	}
+	return s.repo.Create(ctx, spool)
+}
+
+// Update applies partial updates to a filament spool after validation.
+func (s *FilamentService) Update(ctx context.Context, id int, updates map[string]interface{}) (*models.FilamentSpool, error) {
+	return s.repo.Update(ctx, id, updates)
+}
+
+// SoftDelete marks a filament spool as deleted.
+func (s *FilamentService) SoftDelete(ctx context.Context, id int) (bool, error) {
+	return s.repo.SoftDelete(ctx, id)
+}
+
+// PrinterService wraps PrinterRepository.
+type PrinterService struct {
+	repo *repositories.PrinterRepository
+}
+
+// NewPrinterService creates a PrinterService backed by the given repository.
+func NewPrinterService(repo *repositories.PrinterRepository) *PrinterService {
+	return &PrinterService{repo: repo}
+}
+
+// List returns all printers.
+func (s *PrinterService) List(ctx context.Context) ([]models.Printer, error) {
+	return s.repo.GetAll(ctx)
+}
+
+// PrintJobService wraps PrintJobRepository.
+type PrintJobService struct {
+	repo *repositories.PrintJobRepository
+}
+
+// NewPrintJobService creates a PrintJobService backed by the given repository.
+func NewPrintJobService(repo *repositories.PrintJobRepository) *PrintJobService {
+	return &PrintJobService{repo: repo}
+}
+
+// List returns paginated print jobs filtered by the given criteria.
+func (s *PrintJobService) List(ctx context.Context, filter repositories.PrintJobFilter) ([]models.PrintJob, int, error) {
+	return s.repo.GetAll(ctx, filter)
+}
+
+// GetByID returns a single print job by ID.
+func (s *PrintJobService) GetByID(ctx context.Context, id int) (*models.PrintJob, error) {
+	return s.repo.GetByID(ctx, id)
+}
--- a/backend/internal/services/validation.go
+++ b/backend/internal/services/validation.go
@@ -0,0 +1,74 @@
+package services
+
+import (
+	"errors"
+	"fmt"
+	"regexp"
+
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/dtos"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/models"
+)
+
+// colorHexPattern validates hex color strings like #FF0000 or #ff0000.
+var colorHexPattern = regexp.MustCompile(`^#[0-9A-Fa-f]{6}$`)
+
+// validateFilamentSpool performs validation on a FilamentSpool entity.
+// Returns a descriptive error on failure.
+func validateFilamentSpool(s *models.FilamentSpool) error {
+	if s.Name == "" {
+		return errors.New("name is required")
+	}
+	if s.MaterialBaseID <= 0 {
+		return errors.New("material_base_id is required")
+	}
+	if s.MaterialFinishID <= 0 {
+		return errors.New("material_finish_id is required")
+	}
+	if !colorHexPattern.MatchString(s.ColorHex) {
+		return fmt.Errorf("color_hex must be a valid hex color (e.g., #FF0000)")
+	}
+	if s.InitialGrams <= 0 {
+		return errors.New("initial_grams must be greater than 0")
+	}
+	if s.RemainingGrams < 0 {
+		return errors.New("remaining_grams must be >= 0")
+	}
+	return nil
+}
+
+// ValidateCreateFilamentRequest validates a creation DTO.
+func ValidateCreateFilamentRequest(req dtos.CreateFilamentRequest) error {
+	if req.Name == "" {
+		return errors.New("name is required")
+	}
+	if req.MaterialBaseID <= 0 {
+		return errors.New("material_base_id is required")
+	}
+	if req.MaterialFinishID <= 0 {
+		return errors.New("material_finish_id is required")
+	}
+	if !colorHexPattern.MatchString(req.ColorHex) {
+		return fmt.Errorf("color_hex must be a valid hex color (e.g., #FF0000)")
+	}
+	if req.InitialGrams <= 0 {
+		return errors.New("initial_grams must be greater than 0")
+	}
+	if req.RemainingGrams < 0 {
+		return errors.New("remaining_grams must be >= 0")
+	}
+	return nil
+}
+
+// ValidateUpdateFilamentRequest validates partial update fields.
+func ValidateUpdateFilamentRequest(req dtos.UpdateFilamentRequest) error {
+	if req.ColorHex != nil && !colorHexPattern.MatchString(*req.ColorHex) {
+		return fmt.Errorf("color_hex must be a valid hex color (e.g., #FF0000)")
+	}
+	if req.InitialGrams != nil && *req.InitialGrams <= 0 {
+		return errors.New("initial_grams must be greater than 0")
+	}
+	if req.RemainingGrams != nil && *req.RemainingGrams < 0 {
+		return errors.New("remaining_grams must be >= 0")
+	}
+	return nil
+}