Merge branch 'dev' into agent/dex/CUB-117-moonraker-mqtt-go

Reviewed-on: #42

backend/cmd/server/main.go

@@ -6,30 +6,32 @@ import (
 	"net/http"
 	"os"
 	"os/signal"
+	"strconv"
+	"sync"
 	"syscall"
 	"time"
 
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/clients"
 	"github.com/CubeCraft-Creations/Extrudex/backend/internal/config"
 	"github.com/CubeCraft-Creations/Extrudex/backend/internal/db"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/models"
 	"github.com/CubeCraft-Creations/Extrudex/backend/internal/router"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/sse"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/workers"
+	"github.com/jackc/pgx/v5/pgxpool"
 )
 
 func main() {
-	// Setup structured logging
 	slog.SetDefault(slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
 		Level: slog.LevelInfo,
 	})))
 
-	// Load configuration
 	cfg, err := config.Load()
 	if err != nil {
 		slog.Error("failed to load config", "error", err)
 		os.Exit(1)
 	}
 
-	slog.Info("config loaded", "port", cfg.Port, "cors_origin", cfg.CorsOrigin)
-
-	// Connect to database
 	dbPool, err := db.NewPool(cfg.DatabaseURL)
 	if err != nil {
 		slog.Error("failed to connect to database", "error", err)
@@ -37,21 +39,38 @@ func main() {
 	}
 	defer db.ClosePool(dbPool)
 
-	slog.Info("database connected")
+	sseBC := sse.NewBroadcaster(128)
+	sseBC.Start()
+	defer sseBC.Stop()
 
-	// Create router
-	r := router.New(cfg, dbPool)
+	r := router.New(cfg, dbPool, sseBC)
+
+	// ── Workers ─────────────────────────────────────────────────────────
+
+	var wg sync.WaitGroup
+	workersCtx, cancelWorkers := context.WithCancel(context.Background())
+	defer cancelWorkers()
+
+	pollInterval, _ := time.ParseDuration(cfg.MoonrakerPollInterval)
+	if pollInterval <= 0 {
+		pollInterval = 10 * time.Second
+	}
+
+	activePrinters := listActivePrinters(workersCtx, dbPool)
+	for _, p := range activePrinters {
+		startWorkerForPrinter(workersCtx, &wg, cfg, dbPool, p, pollInterval)
+	}
+
+	// ── HTTP server ─────────────────────────────────────────────────────
 
-	// Create HTTP server
 	server := &http.Server{
 		Addr:         ":" + cfg.Port,
 		Handler:      r,
 		ReadTimeout:  15 * time.Second,
-		WriteTimeout: 15 * time.Second,
+		WriteTimeout: 0,
 		IdleTimeout:  60 * time.Second,
 	}
 
-	// Start server in goroutine
 	go func() {
 		slog.Info("server starting", "addr", server.Addr)
 		if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
@@ -60,21 +79,119 @@ func main() {
 		}
 	}()
 
-	// Wait for shutdown signal
 	quit := make(chan os.Signal, 1)
 	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
 	<-quit
 
 	slog.Info("server shutting down")
+	cancelWorkers()
 
-	// Graceful shutdown
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	defer cancel()
+	shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer shutdownCancel()
 
-	if err := server.Shutdown(ctx); err != nil {
+	if err := server.Shutdown(shutdownCtx); err != nil {
 		slog.Error("server shutdown error", "error", err)
 	}
 
-	db.ClosePool(dbPool)
+	done := make(chan struct{})
+	go func() {
+		wg.Wait()
+		close(done)
+	}()
+	select {
+	case <-done:
+		slog.Info("all workers stopped")
+	case <-time.After(15 * time.Second):
+		slog.Warn("timed out waiting for workers to stop")
+	}
+
 	slog.Info("server stopped")
 }
+
+func listActivePrinters(ctx context.Context, pool *pgxpool.Pool) []models.Printer {
+	rows, err := pool.Query(ctx, `
+		SELECT id, name, printer_type_id,
+		       manufacturer, model,
+		       moonraker_url, moonraker_api_key,
+		       mqtt_broker_host, mqtt_topic_prefix,
+		       mqtt_tls_enabled, is_active,
+		       created_at, updated_at
+		FROM printers WHERE is_active = TRUE ORDER BY name
+	`)
+	if err != nil {
+		slog.Warn("failed to query active printers", "error", err)
+		return nil
+	}
+	defer rows.Close()
+
+	var printers []models.Printer
+	for rows.Next() {
+		var p models.Printer
+		if err := rows.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,
+		); err != nil {
+			slog.Warn("failed to scan printer row", "error", err)
+			continue
+		}
+		printers = append(printers, p)
+	}
+	return printers
+}
+
+func startWorkerForPrinter(
+	ctx context.Context,
+	wg *sync.WaitGroup,
+	cfg *config.Config,
+	pool *pgxpool.Pool,
+	printer models.Printer,
+	pollInterval time.Duration,
+) {
+	if printer.MoonrakerURL != nil && *printer.MoonrakerURL != "" {
+		mc := clients.NewMoonrakerClient(*printer.MoonrakerURL)
+		poller := workers.NewMoonrakerPoller(workers.MoonrakerPollerConfig{
+			Client:       mc,
+			Pool:         pool,
+			PollInterval: pollInterval,
+			PrinterID:    printer.ID,
+			PrinterName:  printer.Name,
+		})
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			poller.Run(ctx)
+		}()
+	}
+
+	if printer.MQTTBrokerHost != nil && *printer.MQTTBrokerHost != "" {
+		topicPrefix := cfg.MQTTTopicPrefix
+		if printer.MQTTTopicPrefix != nil && *printer.MQTTTopicPrefix != "" {
+			topicPrefix = *printer.MQTTTopicPrefix
+		}
+		sub := workers.NewMQTTSubscriber(workers.MQTTSubscriberConfig{
+			Pool:        pool,
+			PrinterID:   printer.ID,
+			PrinterName: printer.Name,
+		})
+		mqttClient := clients.NewMQTTClient(clients.MQTTConfig{
+			Broker:      *printer.MQTTBrokerHost,
+			ClientID:    cfg.MQTTClientID + "-p" + strconv.Itoa(printer.ID),
+			TopicPrefix: topicPrefix,
+			TLSCert:     cfg.MQTTTLSCert,
+			TLSKey:      cfg.MQTTTLSKey,
+			Handler:     sub.HandleBambuReport,
+		})
+		sub.Client = mqttClient
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			if err := sub.Run(ctx); err != nil {
+				slog.Error("mqtt subscriber error", "printer_id", printer.ID, "error", err)
+			}
+		}()
+	}
+}

backend/go.mod

@@ -1,9 +1,13 @@
 module github.com/CubeCraft-Creations/Extrudex/backend
 
-go 1.24
+go 1.24.0
+
+toolchain go1.24.2
 
 require (
+	github.com/eclipse/paho.mqtt.golang v1.5.1
 	github.com/go-chi/chi/v5 v5.2.0
+	github.com/gorilla/websocket v1.5.3
 	github.com/jackc/pgx/v5 v5.7.4
 	github.com/kelseyhightower/envconfig v1.4.0
 )
@@ -12,7 +16,8 @@ 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
+	golang.org/x/crypto v0.42.0 // indirect
+	golang.org/x/net v0.44.0 // indirect
+	golang.org/x/sync v0.17.0 // indirect
+	golang.org/x/text v0.29.0 // indirect
 )

backend/go.sum

@@ -1,8 +1,12 @@
 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/eclipse/paho.mqtt.golang v1.5.1 h1:/VSOv3oDLlpqR2Epjn1Q7b2bSTplJIeV2ISgCl2W7nE=
+github.com/eclipse/paho.mqtt.golang v1.5.1/go.mod h1:1/yJCneuyOoCOzKSsOTUc0AJfpsItBGWvYpBLimhArU=
 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/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
+github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 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=
@@ -20,12 +24,14 @@ github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UV
 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=
+golang.org/x/crypto v0.42.0 h1:chiH31gIWm57EkTXpwnqf8qeuMUi0yekh6mT2AvFlqI=
+golang.org/x/crypto v0.42.0/go.mod h1:4+rDnOTJhQCx2q7/j6rAN5XDw8kPjeaXEUR2eL94ix8=
+golang.org/x/net v0.44.0 h1:evd8IRDyfNBMBTTY5XRF1vaZlD+EmWx6x8PkhR04H/I=
+golang.org/x/net v0.44.0/go.mod h1:ECOoLqd5U3Lhyeyo/QDCEVQ4sNgYsqvCZ722XogGieY=
+golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug=
+golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk=
+golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
 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=

backend/internal/clients/moonraker.go

@@ -0,0 +1,171 @@
+// Package clients provides client implementations for printer integrations:
+// Moonraker REST + WebSocket (Klipper-based printers) and MQTT (Bambu Lab).
+package clients
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+)
+
+// ── Moonraker response types ────────────────────────────────────────────────
+
+// moonrakerRPC is the generic JSON-RPC wrapper Moonraker uses for responses.
+type moonrakerRPC struct {
+	Result json.RawMessage `json:"result"`
+	Error  *moonrakerError `json:"error"`
+}
+
+type moonrakerError struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+}
+
+// ── Public DTOs ─────────────────────────────────────────────────────────────
+
+// MoonrakerPrinterInfo represents the /printer/info response.
+type MoonrakerPrinterInfo struct {
+	State        string `json:"state"`
+	StateMessage string `json:"state_message"`
+	KlippyReady  bool   `json:"klippy_ready"`
+}
+
+// MoonrakerPrintStats represents the print_stats object from
+// /printer/objects/query?print_stats.
+type MoonrakerPrintStats struct {
+	State          string  `json:"state"`
+	Filename       *string `json:"filename"`
+	FilamentUsedMm float64 `json:"filament_used"`
+	PrintDuration  float64 `json:"print_duration"`
+	Message        *string `json:"message"`
+}
+
+// MoonrakerPrintJob represents a single entry in /server/history/items.
+type MoonrakerPrintJob struct {
+	JobID              string                 `json:"job_id"`
+	Filename           string                 `json:"filename"`
+	Status             string                 `json:"status"`
+	FilamentUsedMm     float64                `json:"filament_used"`
+	PrintDuration      float64                `json:"print_duration"`
+	TotalDuration      float64                `json:"total_duration"`
+	StartTime          *float64               `json:"start_time"`
+	EndTime            *float64               `json:"end_time"`
+	Metadata           map[string]interface{} `json:"metadata"`
+}
+
+// MoonrakerHistoryResponse wraps the /server/history/items response.
+type MoonrakerHistoryResponse struct {
+	Items      []MoonrakerPrintJob `json:"items"`
+	TotalCount int                 `json:"count"`
+}
+
+// ── Client ──────────────────────────────────────────────────────────────────
+
+// MoonrakerClient is an HTTP client for the Moonraker REST API on
+// Klipper-based printers (e.g., Elegoo Centauri Carbon).
+type MoonrakerClient struct {
+	baseURL    string
+	httpClient *http.Client
+}
+
+// NewMoonrakerClient creates a MoonrakerClient that targets the given
+// base URL (e.g., "http://192.168.1.50:7125"). The internal HTTP client
+// uses a 15-second timeout.
+func NewMoonrakerClient(baseURL string) *MoonrakerClient {
+	baseURL = strings.TrimRight(baseURL, "/")
+	return &MoonrakerClient{
+		baseURL: baseURL,
+		httpClient: &http.Client{
+			Timeout: 15 * time.Second,
+		},
+	}
+}
+
+// GetPrinterInfo calls GET /printer/info and returns the Klipper state.
+// Returns nil when the printer is unreachable or the response cannot be parsed.
+func (c *MoonrakerClient) GetPrinterInfo(ctx context.Context) (*MoonrakerPrinterInfo, error) {
+	var info MoonrakerPrinterInfo
+	if err := c.getJSON(ctx, "/printer/info", &info); err != nil {
+		return nil, err
+	}
+	return &info, nil
+}
+
+// GetPrintStats calls GET /printer/objects/query?print_stats and returns
+// real-time print statistics including filament consumption.
+// Returns nil when no print is active or the printer is unreachable.
+func (c *MoonrakerClient) GetPrintStats(ctx context.Context) (*MoonrakerPrintStats, error) {
+	var stats MoonrakerPrintStats
+	// Moonraker wraps the object in status.print_stats
+	var wrapper struct {
+		Status struct {
+			PrintStats MoonrakerPrintStats `json:"print_stats"`
+		} `json:"status"`
+	}
+	if err := c.getJSON(ctx, "/printer/objects/query?print_stats", &wrapper); err != nil {
+		return nil, err
+	}
+	stats = wrapper.Status.PrintStats
+	return &stats, nil
+}
+
+// GetPrintHistory calls GET /server/history/items and returns recent print
+// jobs. limit controls the maximum number of items (clamped 1-100).
+func (c *MoonrakerClient) GetPrintHistory(ctx context.Context, limit int) (*MoonrakerHistoryResponse, error) {
+	if limit < 1 {
+		limit = 1
+	}
+	if limit > 100 {
+		limit = 100
+	}
+	var history MoonrakerHistoryResponse
+	if err := c.getJSON(ctx, fmt.Sprintf("/server/history/items?limit=%d", limit), &history); err != nil {
+		return nil, err
+	}
+	return &history, nil
+}
+
+// ── Internal helpers ────────────────────────────────────────────────────────
+
+func (c *MoonrakerClient) getJSON(ctx context.Context, path string, target interface{}) error {
+	url := c.baseURL + path
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return fmt.Errorf("moonraker: failed to build request: %w", err)
+	}
+	req.Header.Set("Accept", "application/json")
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("moonraker: request failed (%s): %w", url, err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return fmt.Errorf("moonraker: failed to read body: %w", err)
+	}
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("moonraker: %s returned HTTP %d: %s", url, resp.StatusCode, string(body))
+	}
+
+	// Moonraker wraps responses in {"result": ...}
+	var rpc moonrakerRPC
+	if err := json.Unmarshal(body, &rpc); err != nil {
+		return fmt.Errorf("moonraker: failed to parse response: %w", err)
+	}
+	if rpc.Error != nil && rpc.Error.Message != "" {
+		return fmt.Errorf("moonraker: api error: %s", rpc.Error.Message)
+	}
+
+	if err := json.Unmarshal(rpc.Result, target); err != nil {
+		return fmt.Errorf("moonraker: failed to unmarshal result: %w (raw: %s)", err, string(rpc.Result))
+	}
+	return nil
+}

backend/internal/clients/moonraker_ws.go

@@ -0,0 +1,229 @@
+package clients
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+// ── WebSocket message types ─────────────────────────────────────────────────
+
+// moonrakerWSMessage is a single JSON-RPC frame from the Moonraker WebSocket.
+type moonrakerWSMessage struct {
+	JSONRPC string          `json:"jsonrpc"`
+	Method  string          `json:"method"`
+	Params  json.RawMessage `json:"params"`
+	ID      *int            `json:"id"`
+}
+
+// MoonrakerPrintEvent is the payload delivered by the "notify_status_update"
+// subscription when print_stats or display_status change.
+type MoonrakerPrintEvent struct {
+	PrintStats    *MoonrakerPrintStats    `json:"print_stats"`
+	DisplayStatus *MoonrakerDisplayStatus `json:"display_status"`
+}
+
+// MoonrakerDisplayStatus carries progress and the LCD message.
+type MoonrakerDisplayStatus struct {
+	Progress float64 `json:"progress"`
+	Message  string  `json:"message"`
+}
+
+// MoonrakerStatusHandler is called for every status update received from the
+// Moonraker WebSocket. It receives the parsed event and the raw JSON.
+type MoonrakerStatusHandler func(event MoonrakerPrintEvent) error
+
+// ── WebSocket client ────────────────────────────────────────────────────────
+
+// MoonrakerWSClient maintains a persistent WebSocket connection to the
+// Moonraker server and delivers parsed status updates to a handler.
+type MoonrakerWSClient struct {
+	wsURL   string
+	handler MoonrakerStatusHandler
+	dialer  *websocket.Dialer
+
+	mu     sync.Mutex
+	conn   *websocket.Conn
+	done   chan struct{}
+	once   sync.Once
+}
+
+// NewMoonrakerWSClient creates a WebSocket client for the given Moonraker base
+// URL. The handler is invoked on every status update.
+func NewMoonrakerWSClient(baseURL string, handler MoonrakerStatusHandler) *MoonrakerWSClient {
+	baseURL = strings.TrimRight(baseURL, "/")
+	wsURL := strings.Replace(baseURL, "http://", "ws://", 1)
+	wsURL = strings.Replace(wsURL, "https://", "wss://", 1)
+	wsURL += "/websocket"
+
+	return &MoonrakerWSClient{
+		wsURL:   wsURL,
+		handler: handler,
+		dialer: &websocket.Dialer{
+			Proxy:            http.ProxyFromEnvironment,
+			HandshakeTimeout: 10 * time.Second,
+		},
+		done: make(chan struct{}),
+	}
+}
+
+// Connect establishes the WebSocket, subscribes to status updates, and
+// starts the read loop in a background goroutine. It retries on failure
+// with exponential backoff up to a 60-second cap.
+func (c *MoonrakerWSClient) Connect(ctx context.Context) {
+	go c.run(ctx)
+}
+
+// Shutdown gracefully closes the WebSocket and stops the read loop.
+func (c *MoonrakerWSClient) Shutdown() {
+	c.once.Do(func() {
+		close(c.done)
+	})
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.conn != nil {
+		c.conn.Close()
+		c.conn = nil
+	}
+}
+
+// run is the main connection loop with reconnect backoff.
+func (c *MoonrakerWSClient) run(ctx context.Context) {
+	backoff := 1 * time.Second
+	const maxBackoff = 60 * time.Second
+
+	for {
+		select {
+		case <-ctx.Done():
+			slog.Info("moonraker ws: context cancelled, stopping")
+			return
+		case <-c.done:
+			slog.Info("moonraker ws: shutdown requested")
+			return
+		default:
+		}
+
+		if err := c.connectAndRead(ctx); err != nil {
+			slog.Error("moonraker ws: connection error, retrying", "error", err, "backoff", backoff)
+		}
+
+		// Exponential backoff.
+		select {
+		case <-ctx.Done():
+			return
+		case <-c.done:
+			return
+		case <-time.After(backoff):
+		}
+		backoff *= 2
+		if backoff > maxBackoff {
+			backoff = maxBackoff
+		}
+	}
+}
+
+func (c *MoonrakerWSClient) connectAndRead(ctx context.Context) error {
+	slog.Info("moonraker ws: connecting", "url", c.wsURL)
+
+	conn, _, err := c.dialer.DialContext(ctx, c.wsURL, nil)
+	if err != nil {
+		return fmt.Errorf("dial failed: %w", err)
+	}
+
+	c.mu.Lock()
+	if c.conn != nil {
+		c.conn.Close()
+	}
+	c.conn = conn
+	c.mu.Unlock()
+
+	defer func() {
+		c.mu.Lock()
+		if c.conn == conn {
+			c.conn = nil
+		}
+		c.mu.Unlock()
+		conn.Close()
+	}()
+
+	// Subscribe to status updates.
+	subReq := map[string]interface{}{
+		"jsonrpc": "2.0",
+		"method":  "printer.objects.subscribe",
+		"params": map[string]interface{}{
+			"objects": map[string]interface{}{
+				"print_stats":    nil,
+				"display_status": nil,
+			},
+		},
+		"id": 1,
+	}
+	if err := conn.WriteJSON(subReq); err != nil {
+		return fmt.Errorf("subscribe failed: %w", err)
+	}
+
+	slog.Info("moonraker ws: subscribed to status updates")
+
+	// Set read deadline to detect stale connections.
+	// 120s is long enough to avoid false positives.
+	pingPeriod := 60 * time.Second
+
+	for {
+		// Set read deadline.
+		if err := conn.SetReadDeadline(time.Now().Add(150 * time.Second)); err != nil {
+			return fmt.Errorf("set read deadline: %w", err)
+		}
+
+		_, raw, err := conn.ReadMessage()
+		if err != nil {
+			return fmt.Errorf("read message: %w", err)
+		}
+
+		// Send periodic pings to keep the connection alive.
+		go func() {
+			time.Sleep(pingPeriod)
+			c.mu.Lock()
+			if c.conn == conn {
+				c.conn.WriteControl(websocket.PingMessage, []byte{}, time.Now().Add(10*time.Second))
+			}
+			c.mu.Unlock()
+		}()
+
+		var msg moonrakerWSMessage
+		if err := json.Unmarshal(raw, &msg); err != nil {
+			slog.Warn("moonraker ws: failed to parse message", "error", err)
+			continue
+		}
+
+		// Only process notify_status_update messages.
+		if msg.Method != "notify_status_update" {
+			continue
+		}
+
+		var statusWrapper []MoonrakerPrintEvent
+		if err := json.Unmarshal(msg.Params, &statusWrapper); err != nil {
+			// Params might be an object, not an array.
+			var singleEvent MoonrakerPrintEvent
+			if err2 := json.Unmarshal(msg.Params, &singleEvent); err2 != nil {
+				slog.Warn("moonraker ws: failed to unmarshal status params", "error", err2)
+				continue
+			}
+			statusWrapper = []MoonrakerPrintEvent{singleEvent}
+		}
+
+		for _, ev := range statusWrapper {
+			if c.handler != nil {
+				if err := c.handler(ev); err != nil {
+					slog.Error("moonraker ws: handler error", "error", err)
+				}
+			}
+		}
+	}
+}

backend/internal/clients/mqtt.go

@@ -0,0 +1,183 @@
+package clients
+
+import (
+	"crypto/tls"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"sync"
+	"time"
+
+	mqtt "github.com/eclipse/paho.mqtt.golang"
+)
+
+// ── Bambu Lab telemetry types ───────────────────────────────────────────────
+
+// BambuPrintReport is the JSON payload published by Bambu Lab printers
+// on the MQTT report topic. The structure varies by printer model;
+// we extract the common fields needed for filament tracking.
+type BambuPrintReport struct {
+	// Print holds the active print job data.
+	Print BambuPrintData `json:"print"`
+
+	// VtTray contains AMS tray info; the extruded length is per-tray.
+	VtTray *BambuVtTray `json:"vt_tray,omitempty"`
+}
+
+// BambuPrintData carries the active print state from a Bambu report.
+type BambuPrintData struct {
+	// GcodeFile is the filename being printed.
+	GcodeFile string `json:"gcode_file"`
+	// GcodeState describes the current print state:
+	// "IDLE", "RUNNING", "PAUSE", "FINISH", "FAILED".
+	GcodeState string `json:"gcode_state"`
+	// McPercent is the progress as a percentage (0-100).
+	McPercent int `json:"mc_percent"`
+	// McRemainingTime is the estimated remaining time in minutes.
+	McRemainingTime int `json:"mc_remaining_time"`
+}
+
+// BambuVtTray holds AMS tray telemetry from Bambu printers.
+type BambuVtTray struct {
+	ID         string `json:"id"`
+	TagUID     string `json:"tag_uid"`
+	TrayIDName string `json:"tray_id_name"`
+	// TrayInfoIdx is the hex color code for the tray's filament.
+	TrayInfoIdx string `json:"tray_info_idx"`
+	// TrayColor is a hex color string like "FF0000FF".
+	TrayColor string `json:"tray_color"`
+	// Remain is the percentage of filament remaining on this tray (0-100).
+	Remain int `json:"remain"`
+	// K is a temperature coefficient.
+	K float64 `json:"k"`
+	// N is a second temperature coefficient.
+	N float64 `json:"n"`
+}
+
+// BambuReportHandler is called for each parsed Bambu telemetry message.
+type BambuReportHandler func(report BambuPrintReport) error
+
+// ── MQTT client ─────────────────────────────────────────────────────────────
+
+// MQTTClient wraps the Eclipse Paho MQTT client for Bambu Lab printer
+// telemetry with optional TLS support.
+type MQTTClient struct {
+	broker      string
+	clientID    string
+	topicPrefix string
+	tlsCert     string
+	tlsKey      string
+	handler     BambuReportHandler
+
+	mu     sync.Mutex
+	client mqtt.Client
+}
+
+// MQTTConfig holds the configuration for creating an MQTTClient.
+type MQTTConfig struct {
+	Broker      string // e.g., "ssl://192.168.1.50:8883"
+	ClientID    string // unique MQTT client id, defaults to "extrudex"
+	TopicPrefix string // topic prefix, defaults to "device/+/report"
+	TLSCert     string // path to TLS client certificate (optional)
+	TLSKey      string // path to TLS client key (optional)
+	Handler     BambuReportHandler
+}
+
+// NewMQTTClient creates a new MQTTClient. The connection is not established
+// until Connect is called.
+func NewMQTTClient(cfg MQTTConfig) *MQTTClient {
+	if cfg.ClientID == "" {
+		cfg.ClientID = "extrudex"
+	}
+	if cfg.TopicPrefix == "" {
+		cfg.TopicPrefix = "device/+/report"
+	}
+	return &MQTTClient{
+		broker:      cfg.Broker,
+		clientID:    cfg.ClientID,
+		topicPrefix: cfg.TopicPrefix,
+		tlsCert:     cfg.TLSCert,
+		tlsKey:      cfg.TLSKey,
+		handler:     cfg.Handler,
+	}
+}
+
+// Connect establishes the MQTT connection and subscribes to the configured
+// topic prefix. Returns an error if the initial connection fails.
+func (c *MQTTClient) Connect() error {
+	opts := mqtt.NewClientOptions().
+		AddBroker(c.broker).
+		SetClientID(c.clientID).
+		SetAutoReconnect(true).
+		SetMaxReconnectInterval(30 * time.Second).
+		SetKeepAlive(30 * time.Second).
+		SetPingTimeout(10 * time.Second).
+		SetConnectTimeout(15 * time.Second).
+		SetOnConnectHandler(func(client mqtt.Client) {
+			slog.Info("mqtt: connected", "broker", c.broker)
+			// Subscribe on every reconnect.
+			token := client.Subscribe(c.topicPrefix, 0, c.messageHandler)
+			token.Wait()
+			if err := token.Error(); err != nil {
+				slog.Error("mqtt: subscribe failed on reconnect", "topic", c.topicPrefix, "error", err)
+			} else {
+				slog.Info("mqtt: subscribed", "topic", c.topicPrefix)
+			}
+		}).
+		SetConnectionLostHandler(func(client mqtt.Client, err error) {
+			slog.Warn("mqtt: connection lost", "error", err)
+		})
+
+	// Configure TLS if cert and key are provided.
+	if c.tlsCert != "" && c.tlsKey != "" {
+		cert, err := tls.LoadX509KeyPair(c.tlsCert, c.tlsKey)
+		if err != nil {
+			return fmt.Errorf("mqtt: failed to load TLS cert/key: %w", err)
+		}
+		opts.SetTLSConfig(&tls.Config{
+			Certificates: []tls.Certificate{cert},
+			MinVersion:   tls.VersionTLS12,
+		})
+		slog.Info("mqtt: TLS configured", "cert", c.tlsCert)
+	}
+
+	c.client = mqtt.NewClient(opts)
+	token := c.client.Connect()
+	if !token.WaitTimeout(15 * time.Second) {
+		return fmt.Errorf("mqtt: connect timed out to %s", c.broker)
+	}
+	if err := token.Error(); err != nil {
+		return fmt.Errorf("mqtt: connect failed: %w", err)
+	}
+
+	slog.Info("mqtt: initial connection established", "broker", c.broker)
+	return nil
+}
+
+// Disconnect gracefully closes the MQTT connection.
+func (c *MQTTClient) Disconnect() {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.client != nil && c.client.IsConnected() {
+		c.client.Disconnect(2500) // wait up to 2.5s
+		slog.Info("mqtt: disconnected")
+	}
+}
+
+// messageHandler is the MQTT callback invoked for every message received on
+// the subscribed topic.
+func (c *MQTTClient) messageHandler(_ mqtt.Client, msg mqtt.Message) {
+	if c.handler == nil {
+		return
+	}
+
+	var report BambuPrintReport
+	if err := json.Unmarshal(msg.Payload(), &report); err != nil {
+		slog.Warn("mqtt: failed to parse bambu report", "topic", msg.Topic(), "error", err)
+		return
+	}
+
+	if err := c.handler(report); err != nil {
+		slog.Error("mqtt: handler error", "topic", msg.Topic(), "error", err)
+	}
+}

backend/internal/config/config.go

@@ -12,6 +12,17 @@ type Config struct {
 	Port        string `envconfig:"port" default:"8080"`
 	CorsOrigin  string `envconfig:"cors_origin" default:"*"`
 	LogLevel    string `envconfig:"log_level" default:"info"`
+
+	// Moonraker integration.
+	MoonrakerURL          string `envconfig:"moonraker_url" default:"http://localhost:7125"`
+	MoonrakerPollInterval string `envconfig:"moonraker_poll_interval" default:"10s"`
+
+	// MQTT (Bambu Lab) integration.
+	MQTTBroker      string `envconfig:"mqtt_broker" default:"localhost:1883"`
+	MQTTTopicPrefix string `envconfig:"mqtt_topic_prefix" default:"device/+/report"`
+	MQTTClientID    string `envconfig:"mqtt_client_id" default:"extrudex"`
+	MQTTTLSCert     string `envconfig:"mqtt_tls_cert" default:""`
+	MQTTTLSKey      string `envconfig:"mqtt_tls_key" default:""`
 }
 
 // Load reads configuration from environment variables and returns a populated Config.

backend/internal/router/router.go

@@ -8,13 +8,14 @@ import (
 	"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/CubeCraft-Creations/Extrudex/backend/internal/sse"
 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/chi/v5/middleware"
 	"github.com/jackc/pgx/v5/pgxpool"
 )
 
 // New creates and configures a Chi router with all middleware and handlers mounted.
-func New(cfg *config.Config, dbPool *pgxpool.Pool) chi.Router {
+func New(cfg *config.Config, dbPool *pgxpool.Pool, sseBC *sse.Broadcaster) chi.Router {
 	r := chi.NewRouter()
 
 	// Middleware
@@ -22,7 +23,7 @@ func New(cfg *config.Config, dbPool *pgxpool.Pool) chi.Router {
 	r.Use(middleware.RealIP)
 	r.Use(middleware.Logger)
 	r.Use(middleware.Recoverer)
-	r.Use(middleware.Timeout(60 * time.Second))
+	// Timeout middleware is applied per-route below to exclude SSE
 
 	// CORS
 	r.Use(func(next http.Handler) http.Handler {
@@ -38,9 +39,9 @@ func New(cfg *config.Config, dbPool *pgxpool.Pool) chi.Router {
 		})
 	})
 
-	// Health check
+	// Health check (with timeout)
 	healthHandler := handlers.NewHealthHandler(dbPool)
-	r.Get("/health", healthHandler.ServeHTTP)
+	r.With(middleware.Timeout(30 * time.Second)).Get("/health", healthHandler.ServeHTTP)
 
 	// ── Repositories ──────────────────────────────────────────────────────
 	materialRepo := repositories.NewMaterialRepository(dbPool)
@@ -61,8 +62,9 @@ func New(cfg *config.Config, dbPool *pgxpool.Pool) chi.Router {
 	printJobHandler := handlers.NewPrintJobHandler(printJobService)
 	usageLogHandler := handlers.NewUsageLogHandler(usageLogRepo)
 
-	// ── API Routes ────────────────────────────────────────────────────────
+	// ── API Routes (with timeout) ─────────────────────────────────────────
 	r.Route("/api", func(r chi.Router) {
+		r.Use(middleware.Timeout(60 * time.Second))
 		r.Get("/materials", materialHandler.List)
 
 		r.Route("/filaments", func(r chi.Router) {
@@ -78,6 +80,10 @@ func New(cfg *config.Config, dbPool *pgxpool.Pool) chi.Router {
 		r.Get("/printers", printerHandler.List)
 		r.Get("/print-jobs", printJobHandler.List)
 		r.Get("/usage-logs", usageLogHandler.List)
+
+		// SSE Events stream
+		sseHandler := sse.NewHandler(sseBC)
+		r.Get("/events", sseHandler.ServeHTTP)
 	})
 
 	return r

backend/internal/sse/broadcaster.go

@@ -0,0 +1,133 @@
+package sse
+
+import (
+	"log/slog"
+	"sync"
+)
+
+// client represents a single SSE subscriber — identified by its send channel.
+type client struct {
+	ch chan string
+}
+
+// Broadcaster receives Events on its input channel and fans them out to every
+// connected client. Subscribe adds a new client; Unsubscribe removes one.
+// Start must be called before the broadcaster accepts events.
+type Broadcaster struct {
+	input       chan Event
+	subscribe   chan client
+	unsubscribe chan client
+	clients     map[chan string]struct{}
+	done        chan struct{}
+	once        sync.Once
+}
+
+// NewBroadcaster creates a Broadcaster. bufSize controls the buffer depth for
+// the input channel as well as for each per-client outbound channel.
+func NewBroadcaster(bufSize int) *Broadcaster {
+	if bufSize <= 0 {
+		bufSize = 64
+	}
+	return &Broadcaster{
+		input:       make(chan Event, bufSize),
+		subscribe:   make(chan client),
+		unsubscribe: make(chan client),
+		clients:     make(map[chan string]struct{}),
+		done:        make(chan struct{}),
+	}
+}
+
+// Publish pushes an event into the broadcaster. Safe for concurrent use.
+func (b *Broadcaster) Publish(ev Event) {
+	select {
+	case b.input <- ev:
+	case <-b.done:
+		// Silently drop during shutdown.
+	}
+}
+
+// Start launches the broadcaster's fan-out loop in a goroutine.
+// It must be called before Publish is used.
+func (b *Broadcaster) Start() {
+	go b.loop()
+}
+
+// Stop terminates the fan-out loop and closes all client channels.
+// It is safe to call multiple times.
+func (b *Broadcaster) Stop() {
+	b.once.Do(func() {
+		close(b.done)
+	})
+}
+
+// Subscribe returns a new client channel that receives SSE-formatted strings.
+func (b *Broadcaster) Subscribe() chan string {
+	c := client{ch: make(chan string, 64)}
+	select {
+	case b.subscribe <- c:
+	case <-b.done:
+		// Broadcaster already stopped — return a closed chan so the handler
+		// can bail out quickly.
+		ch := make(chan string)
+		close(ch)
+		return ch
+	}
+	return c.ch
+}
+
+// Unsubscribe removes a client channel and closes it.
+func (b *Broadcaster) Unsubscribe(ch chan string) {
+	c := client{ch: ch}
+	select {
+	case b.unsubscribe <- c:
+	case <-b.done:
+		// Already shutting down — channels will be cleaned up by Stop.
+	}
+}
+
+// loop is the core fan-out goroutine.
+func (b *Broadcaster) loop() {
+	for {
+		select {
+		case ev := <-b.input:
+			sse := ev.toSSE()
+			for ch := range b.clients {
+				// Non-blocking send — slow clients are dropped.
+				select {
+				case ch <- sse:
+				default:
+					slog.Warn("sse broadcaster: dropping event for slow client", "type", ev.Type)
+				}
+			}
+
+		case c := <-b.subscribe:
+			b.clients[c.ch] = struct{}{}
+			slog.Debug("sse broadcaster: client connected", "total_clients", len(b.clients))
+
+		case c := <-b.unsubscribe:
+			if _, ok := b.clients[c.ch]; ok {
+				delete(b.clients, c.ch)
+				close(c.ch)
+				slog.Debug("sse broadcaster: client disconnected", "total_clients", len(b.clients))
+			}
+
+		case <-b.done:
+			// Drain remaining events in input before shutting down.
+			for ev := range b.input {
+				sse := ev.toSSE()
+				for ch := range b.clients {
+					select {
+					case ch <- sse:
+					default:
+					}
+				}
+			}
+			// Close all remaining client channels.
+			for ch := range b.clients {
+				close(ch)
+			}
+			b.clients = nil
+			return
+		}
+	}
+}

backend/internal/sse/events.go

@@ -0,0 +1,92 @@
+// Package sse provides Server-Sent Events infrastructure for real-time updates.
+// Includes event types, a central broadcaster, and an HTTP handler.
+package sse
+
+import (
+	"encoding/json"
+	"time"
+)
+
+// EventType identifies the category of an SSE event.
+type EventType string
+
+const (
+	EventPrinterStatus  EventType = "printer.status"
+	EventJobStarted     EventType = "job.started"
+	EventJobCompleted   EventType = "job.completed"
+	EventFilamentLow    EventType = "filament.low"
+)
+
+// Event is a JSON-serializable SSE event pushed through the broadcaster.
+type Event struct {
+	Type      EventType       `json:"type"`
+	Payload   json.RawMessage `json:"payload"`
+	Timestamp time.Time       `json:"timestamp"`
+}
+
+// PrinterStatusPayload carries printer online/offline/printing state.
+type PrinterStatusPayload struct {
+	PrinterID   int    `json:"printer_id"`
+	PrinterName string `json:"printer_name"`
+	Status      string `json:"status"` // "online", "offline", "printing"
+}
+
+// JobStartedPayload carries initial print job info.
+type JobStartedPayload struct {
+	JobID      int    `json:"job_id"`
+	JobName    string `json:"job_name"`
+	PrinterID  int    `json:"printer_id"`
+	SpoolID    *int   `json:"spool_id,omitempty"`
+}
+
+// JobCompletedPayload carries final print job data including usage.
+type JobCompletedPayload struct {
+	JobID           int     `json:"job_id"`
+	JobName         string  `json:"job_name"`
+	PrinterID       int     `json:"printer_id"`
+	DurationSeconds *int    `json:"duration_seconds,omitempty"`
+	TotalGramsUsed  *float64 `json:"total_grams_used,omitempty"`
+	TotalCostUSD    *float64 `json:"total_cost_usd,omitempty"`
+}
+
+// FilamentLowPayload alerts that a spool is below its threshold.
+type FilamentLowPayload struct {
+	SpoolID       int    `json:"spool_id"`
+	SpoolName     string `json:"spool_name"`
+	RemainingGrams int   `json:"remaining_grams"`
+	ThresholdGrams int   `json:"threshold_grams"`
+}
+
+// NewEvent creates an Event with the current timestamp from a typed payload.
+func NewEvent(eventType EventType, payload any) (Event, error) {
+	raw, err := json.Marshal(payload)
+	if err != nil {
+		return Event{}, err
+	}
+	return Event{
+		Type:      eventType,
+		Payload:   raw,
+		Timestamp: time.Now().UTC(),
+	}, nil
+}
+
+// MustEvent creates an Event and panics on marshal failure (for use with
+// known-good payloads in tests and internal wiring).
+func MustEvent(eventType EventType, payload any) Event {
+	ev, err := NewEvent(eventType, payload)
+	if err != nil {
+		panic("sse.MustEvent: failed to marshal payload: " + err.Error())
+	}
+	return ev
+}
+
+// toSSE formats this Event as a standard SSE message string ready to be
+// written to a response writer. The format is:
+//
+//	event: <type>
+//	data: <json>
+//
+func (e Event) toSSE() string {
+	data, _ := json.Marshal(e)
+	return "event: " + string(e.Type) + "\n" + "data: " + string(data) + "\n\n"
+}

backend/internal/sse/handler.go

@@ -0,0 +1,59 @@
+package sse
+
+import (
+	"net/http"
+)
+
+// Handler is the HTTP handler for the GET /api/events SSE stream.
+// It registers a client with the broadcaster, streams events as they arrive,
+// and unregisters on disconnect.
+type Handler struct {
+	bc *Broadcaster
+}
+
+// NewHandler creates a Handler backed by the given Broadcaster.
+func NewHandler(bc *Broadcaster) *Handler {
+	return &Handler{bc: bc}
+}
+
+// ServeHTTP implements the SSE streaming endpoint.
+// Flusher is required; clients that do not support flushing receive a 501.
+func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	flusher, ok := w.(http.Flusher)
+	if !ok {
+		http.Error(w, "streaming not supported", http.StatusNotImplemented)
+		return
+	}
+
+	// SSE-specific headers
+	w.Header().Set("Content-Type", "text/event-stream")
+	w.Header().Set("Cache-Control", "no-cache")
+	w.Header().Set("Connection", "keep-alive")
+	w.Header().Set("X-Accel-Buffering", "no") // Disable nginx buffering
+
+	// Write headers immediately
+	flusher.Flush()
+
+	// Subscribe to the broadcaster
+	ch := h.bc.Subscribe()
+	defer h.bc.Unsubscribe(ch)
+
+	// Use request context for cancellation when the client disconnects.
+	ctx := r.Context()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case msg, ok := <-ch:
+			if !ok {
+				return
+			}
+			_, err := w.Write([]byte(msg))
+			if err != nil {
+				return
+			}
+			flusher.Flush()
+		}
+	}
+}

backend/internal/workers/moonraker_poller.go

@@ -0,0 +1,255 @@
+package workers
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"sync"
+	"time"
+
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/clients"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// ── deduplication ───────────────────────────────────────────────────────────
+
+// jobTrack holds the last-seen filename and filament_used for dedup.
+type jobTrack struct {
+	filename     string
+	filamentUsed float64
+}
+
+// MoonrakerPoller periodically queries the Moonraker REST API for print stats
+// and logs filament usage to PostgreSQL. It deduplicates by tracking the
+// last-known filament_used value for the active job on this printer.
+type MoonrakerPoller struct {
+	client       *clients.MoonrakerClient
+	pool         *pgxpool.Pool
+	pollInterval time.Duration
+	printerID    int
+	printerName  string
+
+	mu    sync.Mutex
+	track jobTrack
+}
+
+// MoonrakerPollerConfig holds configuration for the Moonraker polling worker.
+type MoonrakerPollerConfig struct {
+	Client       *clients.MoonrakerClient
+	Pool         *pgxpool.Pool
+	PollInterval time.Duration
+	PrinterID    int
+	PrinterName  string
+}
+
+// NewMoonrakerPoller creates a new MoonrakerPoller worker.
+func NewMoonrakerPoller(cfg MoonrakerPollerConfig) *MoonrakerPoller {
+	if cfg.PollInterval <= 0 {
+		cfg.PollInterval = 10 * time.Second
+	}
+	return &MoonrakerPoller{
+		client:       cfg.Client,
+		pool:         cfg.Pool,
+		pollInterval: cfg.PollInterval,
+		printerID:    cfg.PrinterID,
+		printerName:  cfg.PrinterName,
+	}
+}
+
+// Run starts the polling loop. It blocks until ctx is cancelled.
+func (w *MoonrakerPoller) Run(ctx context.Context) {
+	slog.Info("moonraker poller: starting",
+		"printer_id", w.printerID,
+		"printer_name", w.printerName,
+		"interval", w.pollInterval,
+	)
+
+	ticker := time.NewTicker(w.pollInterval)
+	defer ticker.Stop()
+
+	w.poll(ctx)
+
+	for {
+		select {
+		case <-ctx.Done():
+			slog.Info("moonraker poller: stopping", "printer_id", w.printerID)
+			return
+		case <-ticker.C:
+			w.poll(ctx)
+		}
+	}
+}
+
+func (w *MoonrakerPoller) poll(ctx context.Context) {
+	stats, err := w.client.GetPrintStats(ctx)
+	if err != nil {
+		slog.Warn("moonraker poller: failed to get print stats",
+			"printer_id", w.printerID, "error", err)
+		return
+	}
+
+	if stats.State == "" {
+		return
+	}
+
+	jobName := "unknown"
+	if stats.Filename != nil {
+		jobName = *stats.Filename
+	}
+
+	// Compute delta under lock; release before I/O.
+	w.mu.Lock()
+	prevName := w.track.filename
+	prevUsed := w.track.filamentUsed
+
+	if jobName != prevName {
+		w.track.filename = jobName
+		w.track.filamentUsed = 0
+		prevUsed = 0
+	}
+
+	deltaMM := stats.FilamentUsedMm - prevUsed
+	totalMM := stats.FilamentUsedMm
+	if deltaMM <= 0 && jobName == prevName {
+		w.mu.Unlock()
+		return
+	}
+	w.mu.Unlock()
+
+	slog.Info("moonraker poller: filament usage",
+		"printer_id", w.printerID,
+		"job", jobName,
+		"delta_mm", deltaMM,
+		"total_mm", totalMM,
+		"state", stats.State,
+	)
+
+	jobID, err := w.ensurePrintJob(ctx, jobName, stats.State)
+	if err != nil {
+		slog.Error("moonraker poller: failed to ensure print job",
+			"printer_id", w.printerID, "error", err)
+		return
+	}
+
+	spoolID, density := lookupActiveSpool(ctx, w.pool, w.printerID)
+
+	if err := insertUsageLog(ctx, w.pool, jobID, spoolID, deltaMM, density); err != nil {
+		slog.Error("moonraker poller: failed to log usage",
+			"printer_id", w.printerID, "error", err)
+		return
+	}
+
+	w.mu.Lock()
+	w.track.filamentUsed = totalMM
+	w.mu.Unlock()
+}
+
+func (w *MoonrakerPoller) ensurePrintJob(ctx context.Context, jobName, state string) (int, error) {
+	var jobID int
+	err := w.pool.QueryRow(ctx, `
+		SELECT pj.id FROM print_jobs pj
+		JOIN job_statuses js ON pj.job_status_id = js.id
+		WHERE pj.printer_id = $1
+		  AND pj.job_name = $2
+		  AND pj.deleted_at IS NULL
+		  AND js.name IN ('printing', 'pending')
+		ORDER BY pj.created_at DESC
+		LIMIT 1
+	`, w.printerID, jobName).Scan(&jobID)
+
+	if err == nil {
+		_, _ = w.pool.Exec(ctx, `
+			UPDATE print_jobs SET
+				job_status_id = (SELECT id FROM job_statuses WHERE name = 'printing'),
+				started_at = COALESCE(started_at, NOW()),
+				updated_at = NOW()
+			WHERE id = $1
+			  AND job_status_id = (SELECT id FROM job_statuses WHERE name = 'pending')
+		`, jobID)
+		return jobID, nil
+	}
+
+	var statusID int
+	err = w.pool.QueryRow(ctx, `SELECT id FROM job_statuses WHERE name = 'printing'`).Scan(&statusID)
+	if err != nil {
+		return 0, fmt.Errorf("moonraker poller: missing 'printing' job status: %w", err)
+	}
+
+	err = w.pool.QueryRow(ctx, `
+		INSERT INTO print_jobs (printer_id, job_name, file_name, job_status_id, started_at)
+		VALUES ($1, $2, $3, $4, NOW())
+		RETURNING id
+	`, w.printerID, jobName, jobName, statusID).Scan(&jobID)
+	if err != nil {
+		return 0, fmt.Errorf("moonraker poller: failed to create print job: %w", err)
+	}
+
+	slog.Info("moonraker poller: created print job", "job_id", jobID, "job_name", jobName)
+	return jobID, nil
+}
+
+// ── Package-level helpers (shared by both workers) ──────────────────────────
+
+// lookupActiveSpool finds the most recently used spool for a given printer.
+func lookupActiveSpool(ctx context.Context, pool *pgxpool.Pool, printerID int) (int, float64) {
+	type result struct {
+		id      int
+		density float64
+	}
+	var res result
+
+	err := pool.QueryRow(ctx, `
+		SELECT fs.id, COALESCE(mb.density_g_cm3, 1.24)
+		FROM filament_spools fs
+		JOIN material_bases mb ON fs.material_base_id = mb.id
+		JOIN print_jobs pj ON pj.filament_spool_id = fs.id
+		WHERE pj.printer_id = $1 AND fs.deleted_at IS NULL
+		ORDER BY pj.created_at DESC LIMIT 1
+	`, printerID).Scan(&res.id, &res.density)
+	if err == nil {
+		return res.id, res.density
+	}
+
+	err = pool.QueryRow(ctx, `
+		SELECT fs.id, COALESCE(mb.density_g_cm3, 1.24)
+		FROM filament_spools fs
+		JOIN material_bases mb ON fs.material_base_id = mb.id
+		WHERE fs.deleted_at IS NULL
+		ORDER BY fs.created_at DESC LIMIT 1
+	`).Scan(&res.id, &res.density)
+	if err == nil {
+		return res.id, res.density
+	}
+
+	return 1, 1.24
+}
+
+// insertUsageLog inserts a usage_log entry and decrements the spool's remaining grams.
+func insertUsageLog(ctx context.Context, pool *pgxpool.Pool, jobID, spoolID int, deltaMM, densityGCm3 float64) error {
+	const crossSectionCm2 = 0.02405 // π * (0.0875cm)² for 1.75mm filament
+	gramsUsed := crossSectionCm2 * (deltaMM / 10.0) * densityGCm3
+
+	if gramsUsed <= 0 || deltaMM <= 0 {
+		return nil
+	}
+
+	if _, err := pool.Exec(ctx, `
+		INSERT INTO usage_logs (print_job_id, filament_spool_id, mm_extruded, grams_used, logged_at)
+		VALUES ($1, $2, $3, $4, NOW())
+	`, jobID, spoolID, deltaMM, gramsUsed); err != nil {
+		return fmt.Errorf("usage_log insert failed: %w", err)
+	}
+
+	_, _ = pool.Exec(ctx, `
+		UPDATE filament_spools
+		SET remaining_grams = GREATEST(remaining_grams - $2::int, 0),
+		    updated_at = NOW()
+		WHERE id = $1
+	`, spoolID, int(gramsUsed))
+
+	slog.Debug("moonraker poller: logged usage",
+		"job_id", jobID, "spool_id", spoolID,
+		"mm_extruded", deltaMM, "grams_used", gramsUsed,
+	)
+	return nil
+}

backend/internal/workers/mqtt_subscriber.go

@@ -0,0 +1,170 @@
+package workers
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"sync"
+	"time"
+
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/clients"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// bambuJobState tracks the active print job detected via MQTT.
+type bambuJobState struct {
+	gcodeFile  string
+	gcodeState string
+	percent    int
+}
+
+// MQTTSubscriber listens to Bambu Lab MQTT telemetry topics and logs
+// filament usage events to PostgreSQL.
+type MQTTSubscriber struct {
+	Client *clients.MQTTClient
+	pool   *pgxpool.Pool
+
+	printerID   int
+	printerName string
+
+	mu    sync.Mutex
+	state bambuJobState
+}
+
+// MQTTSubscriberConfig holds configuration for the MQTT subscriber worker.
+type MQTTSubscriberConfig struct {
+	Pool        *pgxpool.Pool
+	PrinterID   int
+	PrinterName string
+}
+
+// NewMQTTSubscriber creates a new MQTTSubscriber worker. Set Client after
+// construction to wire the handler.
+func NewMQTTSubscriber(cfg MQTTSubscriberConfig) *MQTTSubscriber {
+	return &MQTTSubscriber{
+		pool:        cfg.Pool,
+		printerID:   cfg.PrinterID,
+		printerName: cfg.PrinterName,
+	}
+}
+
+// Run connects to MQTT and blocks until ctx is cancelled.
+func (w *MQTTSubscriber) Run(ctx context.Context) error {
+	slog.Info("mqtt subscriber: starting",
+		"printer_id", w.printerID,
+		"printer_name", w.printerName,
+	)
+
+	if w.Client == nil {
+		return fmt.Errorf("mqtt subscriber: Client is nil")
+	}
+
+	if err := w.Client.Connect(); err != nil {
+		return fmt.Errorf("mqtt subscriber: connect failed: %w", err)
+	}
+	defer w.Client.Disconnect()
+
+	slog.Info("mqtt subscriber: connected", "printer_id", w.printerID)
+
+	<-ctx.Done()
+	slog.Info("mqtt subscriber: shutting down", "printer_id", w.printerID)
+	return nil
+}
+
+// HandleBambuReport is the MQTT callback for Bambu telemetry messages.
+func (w *MQTTSubscriber) HandleBambuReport(report clients.BambuPrintReport) error {
+	w.mu.Lock()
+	prev := w.state
+	current := bambuJobState{
+		gcodeFile:  report.Print.GcodeFile,
+		gcodeState: report.Print.GcodeState,
+		percent:    report.Print.McPercent,
+	}
+	w.state = current
+	w.mu.Unlock()
+
+	if prev.gcodeState == current.gcodeState && prev.gcodeFile == current.gcodeFile {
+		return nil
+	}
+
+	slog.Info("mqtt subscriber: state change",
+		"printer_id", w.printerID,
+		"file", current.gcodeFile,
+		"state", current.gcodeState,
+		"percent", current.percent,
+	)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	switch current.gcodeState {
+	case "RUNNING":
+		return w.handleState(ctx, current, "printing")
+	case "FINISH":
+		return w.handleState(ctx, current, "completed")
+	case "FAILED":
+		return w.handleState(ctx, current, "failed")
+	}
+	return nil
+}
+
+func (w *MQTTSubscriber) handleState(ctx context.Context, s bambuJobState, status string) error {
+	jobID, err := w.ensurePrintJob(ctx, s.gcodeFile, status)
+	if err != nil {
+		return err
+	}
+
+	if status == "completed" || status == "failed" {
+		_, _ = w.pool.Exec(ctx, `
+			UPDATE print_jobs SET
+				job_status_id = (SELECT id FROM job_statuses WHERE name = $2),
+				completed_at = CASE WHEN $2 = 'completed' THEN NOW() ELSE completed_at END,
+				updated_at = NOW()
+			WHERE id = $1
+		`, jobID, status)
+	} else {
+		_, _ = w.pool.Exec(ctx, `
+			UPDATE print_jobs SET
+				job_status_id = (SELECT id FROM job_statuses WHERE name = $2),
+				started_at = COALESCE(started_at, NOW()),
+				updated_at = NOW()
+			WHERE id = $1
+		`, jobID, status)
+	}
+
+	slog.Info("mqtt subscriber: job updated",
+		"printer_id", w.printerID, "job_id", jobID, "status", status)
+	return nil
+}
+
+func (w *MQTTSubscriber) ensurePrintJob(ctx context.Context, filename, status string) (int, error) {
+	var jobID int
+	err := w.pool.QueryRow(ctx, `
+		SELECT id FROM print_jobs
+		WHERE printer_id = $1 AND file_name = $2 AND deleted_at IS NULL
+		ORDER BY created_at DESC LIMIT 1
+	`, w.printerID, filename).Scan(&jobID)
+
+	if err == nil {
+		return jobID, nil
+	}
+
+	var statusID int
+	err = w.pool.QueryRow(ctx, `SELECT id FROM job_statuses WHERE name = $1`, status).Scan(&statusID)
+	if err != nil {
+		return 0, fmt.Errorf("mqtt subscriber: unknown status '%s': %w", status, err)
+	}
+
+	err = w.pool.QueryRow(ctx, `
+		INSERT INTO print_jobs (printer_id, job_name, file_name, job_status_id, started_at)
+		VALUES ($1, $2, $2, $3, NOW())
+		RETURNING id
+	`, w.printerID, filename, statusID).Scan(&jobID)
+	if err != nil {
+		return 0, fmt.Errorf("mqtt subscriber: create print_job failed: %w", err)
+	}
+
+	slog.Info("mqtt subscriber: created print job",
+		"job_id", jobID, "file", filename, "status", status)
+	return jobID, nil
+}

frontend/src/App.tsx

@@ -1,28 +1,27 @@
-import { useState, useEffect } from 'react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { BrowserRouter, Routes, Route } from 'react-router-dom'
+import Dashboard from './pages/Dashboard'
+import InventoryPage from './pages/InventoryPage'
 
-function App() {
-  const [health, setHealth] = useState<any>(null)
-
-  useEffect(() => {
-    fetch('/api/health')
-      .then(r => r.json())
-      .then(setHealth)
-      .catch(console.error)
-  }, [])
+const queryClient = new QueryClient()
 
+export default function App() {
   return (
-    <div className="min-h-screen flex items-center justify-center">
-      <div className="p-6 rounded-lg bg-slate-800 shadow-xl max-w-md w-full">
-        <h1 className="text-2xl font-bold mb-4 text-emerald-400">Extrudex</h1>
-        <p className="text-slate-300 mb-4">React frontend scaffold</p>
-        {health && (
-          <pre className="text-xs bg-slate-900 p-3 rounded overflow-auto">
-            {JSON.stringify(health, null, 2)}
-          </pre>
-        )}
-      </div>
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <div className="min-h-screen bg-slate-900 text-slate-50">
+          <header className="bg-slate-800 border-b border-slate-700 px-4 py-3 flex items-center gap-3 sticky top-0 z-20">
+            <div className="w-8 h-8 rounded bg-emerald-500 flex items-center justify-center text-slate-900 font-bold text-lg">E</div>
+            <h1 className="text-lg font-semibold">Extrudex</h1>
+          </header>
+          <main className="p-4">
+            <Routes>
+              <Route path="/" element={<Dashboard />} />
+              <Route path="/inventory" element={<InventoryPage />} />
+            </Routes>
+          </main>
         </div>
+      </BrowserRouter>
+    </QueryClientProvider>
   )
 }
-
-export default App

frontend/src/components/ColorSwatch.tsx

@@ -0,0 +1,18 @@
+interface ColorSwatchProps {
+  colorHex: string
+  size?: number
+}
+
+export default function ColorSwatch({ colorHex, size = 24 }: ColorSwatchProps) {
+  return (
+    <div
+      className="rounded-full border border-slate-600 shadow-sm inline-block"
+      style={{
+        backgroundColor: colorHex.startsWith('#') ? colorHex : `#${colorHex}`,
+        width: size,
+        height: size,
+      }}
+      title={colorHex}
+    />
+  )
+}

frontend/src/components/LoadingSpinner.tsx

@@ -0,0 +1,8 @@
+export default function LoadingSpinner() {
+  return (
+    <div className="flex flex-col items-center gap-3">
+      <div className="w-10 h-10 border-4 border-emerald-500/30 border-t-emerald-400 rounded-full animate-spin" />
+      <p className="text-slate-400 text-sm">Loading dashboard…</p>
+    </div>
+  )
+}

frontend/src/components/RecentPrints.tsx

@@ -0,0 +1,76 @@
+import type { PrintJob } from '../types'
+import { Clock, FileText } from 'lucide-react'
+
+interface RecentPrintsProps {
+  jobs: PrintJob[]
+}
+
+export default function RecentPrints({ jobs }: RecentPrintsProps) {
+  if (jobs.length === 0) {
+    return (
+      <div className="rounded-xl border border-slate-700 bg-slate-800 p-6 text-center text-slate-400">
+        <FileText size={32} className="mx-auto mb-3 text-slate-500" />
+        <p>No recent print jobs</p>
+      </div>
+    )
+  }
+
+  const statusColor = (status: string) => {
+    switch (status.toLowerCase()) {
+      case 'completed': return 'text-emerald-400 bg-emerald-500/10'
+      case 'in_progress': return 'text-sky-400 bg-sky-500/10'
+      case 'failed': return 'text-red-400 bg-red-500/10'
+      default: return 'text-slate-400 bg-slate-500/10'
+    }
+  }
+
+  return (
+    <div className="rounded-xl border border-slate-700 bg-slate-800 overflow-hidden">
+      <div className="overflow-x-auto">
+        <table className="w-full text-left">
+          <thead>
+            <tr className="border-b border-slate-700">
+              <th className="px-4 py-3 text-sm font-medium text-slate-400">Name</th>
+              <th className="px-4 py-3 text-sm font-medium text-slate-400">Status</th>
+              <th className="px-4 py-3 text-sm font-medium text-slate-400">Duration</th>
+              <th className="px-4 py-3 text-sm font-medium text-slate-400">Filament</th>
+              <th className="px-4 py-3 text-sm font-medium text-slate-400">Cost</th>
+            </tr>
+          </thead>
+          <tbody>
+            {jobs.map((job) => (
+              <tr key={job.id} className="border-b border-slate-700/50 last:border-0 hover:bg-slate-700/30 transition-colors">
+                <td className="px-4 py-3 text-sm text-slate-100 font-medium">{job.name}</td>
+                <td className="px-4 py-3">
+                  <span className={`inline-flex items-center gap-1 px-2 py-1 rounded-full text-xs font-medium ${statusColor(job.status)}`}>
+                    {job.status}
+                  </span>
+                </td>
+                <td className="px-4 py-3 text-sm text-slate-300">
+                  <div className="flex items-center gap-1">
+                    <Clock size={14} />
+                    {formatDuration(job.duration_seconds)}
+                  </div>
+                </td>
+                <td className="px-4 py-3 text-sm text-slate-300">
+                  {job.filament_used_grams?.toFixed(1) ?? '-'} g
+                </td>
+                <td className="px-4 py-3 text-sm text-slate-300">
+                  ${job.cost_usd?.toFixed(2) ?? '-'}
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  )
+}
+
+function formatDuration(seconds: number): string {
+  if (!seconds) return '-'
+  const hrs = Math.floor(seconds / 3600)
+  const mins = Math.floor((seconds % 3600) / 60)
+  if (hrs > 0) return `${hrs}h ${mins}m`
+  return `${mins}m`
+}

frontend/src/components/SummaryCard.tsx

@@ -0,0 +1,31 @@
+import type { LucideIcon } from 'lucide-react'
+
+interface SummaryCardProps {
+  title: string
+  value: string | number
+  icon: LucideIcon
+  color: 'emerald' | 'amber' | 'sky' | 'violet'
+}
+
+const colorMap = {
+  emerald: { bg: 'bg-emerald-500/10', border: 'border-emerald-500/20', text: 'text-emerald-400', icon: 'text-emerald-400' },
+  amber:   { bg: 'bg-amber-500/10',  border: 'border-amber-500/20',  text: 'text-amber-400',  icon: 'text-amber-400' },
+  sky:     { bg: 'bg-sky-500/10',    border: 'border-sky-500/20',    text: 'text-sky-400',    icon: 'text-sky-400' },
+  violet:  { bg: 'bg-violet-500/10', border: 'border-violet-500/20', text: 'text-violet-400', icon: 'text-violet-400' },
+}
+
+export default function SummaryCard({ title, value, icon: Icon, color }: SummaryCardProps) {
+  const c = colorMap[color]
+
+  return (
+    <div className={`rounded-xl border ${c.border} ${c.bg} p-5 flex items-start justify-between`}>
+      <div>
+        <p className="text-sm font-medium text-slate-400 mb-1">{title}</p>
+        <p className={`text-3xl font-bold ${c.text}`}>{value}</p>
+      </div>
+      <div className={`p-2 rounded-lg ${c.bg}`}>
+        <Icon size={24} className={c.icon} />
+      </div>
+    </div>
+  )
+}

frontend/src/main.tsx

@@ -1,10 +1,25 @@
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { BrowserRouter } from 'react-router-dom'
 import './index.css'
 import App from './App'
 
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 30_000,
+      refetchOnWindowFocus: false,
+    },
+  },
+})
+
 createRoot(document.getElementById('root')!).render(
   <StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
         <App />
+      </BrowserRouter>
+    </QueryClientProvider>
   </StrictMode>,
 )

frontend/src/pages/Dashboard.tsx

@@ -0,0 +1,139 @@
+import { useQuery } from '@tanstack/react-query'
+import { getFilaments, getPrintJobs } from '../services/api'
+import SummaryCard from '../components/SummaryCard'
+import RecentPrints from '../components/RecentPrints'
+import LoadingSpinner from '../components/LoadingSpinner'
+import { Package, AlertTriangle, Printer, DollarSign, Plus, List } from 'lucide-react'
+
+export default function Dashboard() {
+  const {
+    data: filamentData,
+    isLoading: filamentLoading,
+    error: filamentError,
+  } = useQuery({
+    queryKey: ['filaments', 'count'],
+    queryFn: () => getFilaments({ limit: 1 }),
+  })
+
+  const {
+    data: lowStockData,
+    isLoading: lowStockLoading,
+    error: lowStockError,
+  } = useQuery({
+    queryKey: ['filaments', 'lowStock'],
+    queryFn: () => getFilaments({ low_stock: true, limit: 1 }),
+  })
+
+  const {
+    data: recentPrints,
+    isLoading: printsLoading,
+    error: printsError,
+  } = useQuery({
+    queryKey: ['printJobs', 'recent'],
+    queryFn: () => getPrintJobs({ limit: 5 }),
+  })
+
+  const {
+    data: allPrints,
+    isLoading: costLoading,
+    error: costError,
+  } = useQuery({
+    queryKey: ['printJobs', 'all'],
+    queryFn: () => getPrintJobs({ limit: 1000 }),
+  })
+
+  const totalSpools = filamentData?.total ?? 0
+  const lowStockCount = lowStockData?.total ?? 0
+  const recentPrintJobs = recentPrints?.data ?? []
+
+  // Calculate cost this month from all print jobs
+  const now = new Date()
+  const currentMonth = now.getMonth()
+  const currentYear = now.getFullYear()
+  const monthlyCost =
+    allPrints?.data
+      .filter((job) => {
+        const d = new Date(job.started_at)
+        return d.getMonth() === currentMonth && d.getFullYear() === currentYear
+      })
+      .reduce((sum, job) => sum + (job.cost_usd ?? 0), 0) ?? 0
+
+  const isLoading = filamentLoading || lowStockLoading || printsLoading || costLoading
+  const error = filamentError || lowStockError || printsError || costError
+
+  if (isLoading) {
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-slate-900">
+        <LoadingSpinner />
+      </div>
+    )
+  }
+
+  if (error) {
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-slate-900">
+        <div className="p-6 rounded-lg bg-red-900/30 border border-red-500 text-red-200 max-w-md">
+          <h2 className="text-xl font-bold mb-2">Error</h2>
+          <p className="text-sm">{(error as Error).message || 'Failed to load dashboard data.'}</p>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="min-h-screen bg-slate-900 p-4 md:p-8">
+      <div className="max-w-6xl mx-auto">
+        <header className="mb-8">
+          <h1 className="text-3xl font-bold text-emerald-400 mb-2">Dashboard</h1>
+          <p className="text-slate-400">Overview of your Extrudex inventory and prints</p>
+        </header>
+
+        {/* Summary Cards Grid */}
+        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4 mb-8">
+          <SummaryCard
+            title="Total Spools"
+            value={totalSpools}
+            icon={Package}
+            color="emerald"
+          />
+          <SummaryCard
+            title="Low Stock"
+            value={lowStockCount}
+            icon={AlertTriangle}
+            color={lowStockCount > 0 ? 'amber' : 'emerald'}
+          />
+          <SummaryCard
+            title="Recent Prints"
+            value={recentPrintJobs.length}
+            icon={Printer}
+            color="sky"
+          />
+          <SummaryCard
+            title="Cost This Month"
+            value={`$${monthlyCost.toFixed(2)}`}
+            icon={DollarSign}
+            color="violet"
+          />
+        </div>
+
+        {/* Quick Actions */}
+        <div className="flex flex-wrap gap-3 mb-8">
+          <button className="flex items-center gap-2 px-4 py-2 rounded-lg bg-emerald-600 hover:bg-emerald-500 text-white font-medium transition-colors active:scale-95 touch-manipulation">
+            <Plus size={18} />
+            Add Spool
+          </button>
+          <button className="flex items-center gap-2 px-4 py-2 rounded-lg bg-slate-700 hover:bg-slate-600 text-slate-100 font-medium transition-colors active:scale-95 touch-manipulation">
+            <List size={18} />
+            View Inventory
+          </button>
+        </div>
+
+        {/* Recent Prints Section */}
+        <section>
+          <h2 className="text-xl font-semibold text-slate-100 mb-4">Recent Prints</h2>
+          <RecentPrints jobs={recentPrintJobs} />
+        </section>
+      </div>
+    </div>
+  )
+}

frontend/src/pages/InventoryPage.tsx

@@ -0,0 +1,339 @@
+import { useState, useMemo } from 'react'
+import { useQuery } from '@tanstack/react-query'
+import { Search, Filter, ChevronLeft, ChevronRight, Trash2, Pencil, Plus, AlertTriangle } from 'lucide-react'
+import ColorSwatch from '../components/ColorSwatch'
+import { fetchFilaments, deleteFilament } from '../services/filamentService'
+import type { FilamentSpool, FilamentFilter } from '../types/filament'
+
+const PAGE_SIZE = 20
+
+type SortField = 'name' | 'remaining_grams' | 'cost_usd'
+type SortDir = 'asc' | 'desc'
+
+export default function InventoryPage() {
+  const [search, setSearch] = useState('')
+  const [material, setMaterial] = useState('')
+  const [finish, setFinish] = useState('')
+  const [lowStockOnly, setLowStockOnly] = useState(false)
+  const [sortBy, setSortBy] = useState<SortField>('name')
+  const [sortDir, setSortDir] = useState<SortDir>('asc')
+  const [page, setPage] = useState(0)
+  const [deleteId, setDeleteId] = useState<number | null>(null)
+
+  const filter: FilamentFilter = useMemo(() => ({
+    material: material || undefined,
+    finish: finish || undefined,
+    low_stock: lowStockOnly,
+    sort_by: sortBy,
+    sort_dir: sortDir,
+    limit: PAGE_SIZE,
+    offset: page * PAGE_SIZE,
+  }), [material, finish, lowStockOnly, sortBy, sortDir, page])
+
+  const { data, isLoading, error, refetch } = useQuery({
+    queryKey: ['filaments', filter],
+    queryFn: () => fetchFilaments(filter),
+  })
+
+  const filaments = data?.data ?? []
+  const total = data?.total ?? 0
+  const totalPages = Math.max(1, Math.ceil(total / PAGE_SIZE))
+
+  // Client-side search filter (name/barcode) since backend may not support it yet.
+  const filtered = useMemo(() => {
+    if (!search.trim()) return filaments
+    const q = search.toLowerCase()
+    return filaments.filter(
+      (f: FilamentSpool) =>
+        f.name.toLowerCase().includes(q) ||
+        (f.barcode && f.barcode.toLowerCase().includes(q))
+    )
+  }, [filaments, search])
+
+  const handleSort = (field: SortField) => {
+    if (sortBy === field) {
+      setSortDir(prev => (prev === 'asc' ? 'desc' : 'asc'))
+    } else {
+      setSortBy(field)
+      setSortDir('asc')
+    }
+    setPage(0)
+  }
+
+  const handleDelete = async (id: number) => {
+    await deleteFilament(id)
+    setDeleteId(null)
+    refetch()
+  }
+
+  const SortIndicator = ({ field }: { field: SortField }) => {
+    if (sortBy !== field) return <span className="text-slate-600 ml-1">↕</span>
+    return <span className="text-emerald-400 ml-1">{sortDir === 'asc' ? '↑' : '↓'}</span>
+  }
+
+  return (
+    <div className="space-y-4">
+      {/* Header */}
+      <div className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-3">
+        <div>
+          <h2 className="text-xl font-bold text-slate-100">Filament Inventory</h2>
+          <p className="text-sm text-slate-400">{total} spool(s) total</p>
+        </div>
+        <button className="inline-flex items-center gap-2 rounded-lg bg-emerald-600 px-4 py-2 text-sm font-semibold text-white hover:bg-emerald-500 active:bg-emerald-700 transition-colors">
+          <Plus size={16} /> Add Spool
+        </button>
+      </div>
+
+      {/* Filters */}
+      <div className="flex flex-col lg:flex-row gap-3">
+        {/* Search */}
+        <div className="relative flex-1">
+          <Search size={16} className="absolute left-3 top-1/2 -translate-y-1/2 text-slate-400" />
+          <input
+            type="text"
+            placeholder="Search by name or barcode…"
+            value={search}
+            onChange={e => { setSearch(e.target.value); setPage(0) }}
+            className="w-full rounded-lg bg-slate-800 border border-slate-700 pl-9 pr-3 py-2 text-sm text-slate-100 placeholder-slate-500 focus:outline-none focus:ring-2 focus:ring-emerald-500 focus:border-emerald-500"
+          />
+        </div>
+
+        {/* Material filter */}
+        <select
+          value={material}
+          onChange={e => { setMaterial(e.target.value); setPage(0) }}
+          className="rounded-lg bg-slate-800 border border-slate-700 px-3 py-2 text-sm text-slate-100 focus:outline-none focus:ring-2 focus:ring-emerald-500"
+        >
+          <option value="">All Materials</option>
+          <option value="PLA">PLA</option>
+          <option value="PETG">PETG</option>
+          <option value="ABS">ABS</option>
+          <option value="TPU">TPU</option>
+          <option value="ASA">ASA</option>
+          <option value="Nylon">Nylon</option>
+          <option value="PC">PC</option>
+        </select>
+
+        {/* Finish filter */}
+        <select
+          value={finish}
+          onChange={e => { setFinish(e.target.value); setPage(0) }}
+          className="rounded-lg bg-slate-800 border border-slate-700 px-3 py-2 text-sm text-slate-100 focus:outline-none focus:ring-2 focus:ring-emerald-500"
+        >
+          <option value="">All Finishes</option>
+          <option value="Basic">Basic</option>
+          <option value="Silk">Silk</option>
+          <option value="Matte">Matte</option>
+          <option value="Glossy">Glossy</option>
+          <option value="Wood">Wood</option>
+          <option value="Marble">Marble</option>
+        </select>
+
+        {/* Low stock toggle */}
+        <label className="inline-flex items-center gap-2 rounded-lg bg-slate-800 border border-slate-700 px-3 py-2 text-sm text-slate-100 cursor-pointer select-none hover:bg-slate-750">
+          <Filter size={14} className="text-amber-400" />
+          <input
+            type="checkbox"
+            checked={lowStockOnly}
+            onChange={e => { setLowStockOnly(e.target.checked); setPage(0) }}
+            className="accent-amber-500"
+          />
+          Low Stock Only
+        </label>
+      </div>
+
+      {/* Loading / Error */}
+      {isLoading && (
+        <div className="text-center py-12 text-slate-400">Loading spools…</div>
+      )}
+      {error && (
+        <div className="text-center py-12 text-red-400">
+          Failed to load inventory.
+          <button onClick={() => refetch()} className="ml-2 underline hover:text-red-300">Retry</button>
+        </div>
+      )}
+
+      {/* Desktop Table */}
+      {!isLoading && !error && (
+        <>
+          <div className="hidden md:block overflow-x-auto rounded-lg border border-slate-700">
+            <table className="w-full text-sm">
+              <thead className="bg-slate-800 text-slate-300">
+                <tr>
+                  <th className="px-4 py-3 text-left font-semibold cursor-pointer select-none hover:text-slate-100" onClick={() => handleSort('name')}>
+                    Name <SortIndicator field="name" />
+                  </th>
+                  <th className="px-4 py-3 text-left font-semibold">Material</th>
+                  <th className="px-4 py-3 text-left font-semibold">Finish</th>
+                  <th className="px-4 py-3 text-left font-semibold">Color</th>
+                  <th className="px-4 py-3 text-right font-semibold cursor-pointer select-none hover:text-slate-100" onClick={() => handleSort('remaining_grams')}>
+                    Remaining <SortIndicator field="remaining_grams" />
+                  </th>
+                  <th className="px-4 py-3 text-right font-semibold cursor-pointer select-none hover:text-slate-100" onClick={() => handleSort('cost_usd')}>
+                    Cost <SortIndicator field="cost_usd" />
+                  </th>
+                  <th className="px-4 py-3 text-center font-semibold">Status</th>
+                  <th className="px-4 py-3 text-right font-semibold">Actions</th>
+                </tr>
+              </thead>
+              <tbody className="divide-y divide-slate-700">
+                {filtered.length === 0 && (
+                  <tr>
+                    <td colSpan={8} className="px-4 py-8 text-center text-slate-500">No spools found.</td>
+                  </tr>
+                )}
+                {filtered.map((spool: FilamentSpool) => {
+                  const isLow = spool.remaining_grams <= spool.low_stock_threshold_grams
+                  return (
+                    <tr key={spool.id} className={`${isLow ? 'bg-red-900/20' : 'bg-slate-800/50'} hover:bg-slate-700/50 transition-colors`}>
+                      <td className="px-4 py-3 font-medium text-slate-100">{spool.name}</td>
+                      <td className="px-4 py-3 text-slate-300">{spool.material_base?.name ?? '—'}</td>
+                      <td className="px-4 py-3 text-slate-300">{spool.material_finish?.name ?? '—'}</td>
+                      <td className="px-4 py-3">
+                        <div className="flex items-center gap-2">
+                          <ColorSwatch colorHex={spool.color_hex} size={20} />
+                          <span className="text-xs text-slate-400 uppercase">{spool.color_hex}</span>
+                        </div>
+                      </td>
+                      <td className="px-4 py-3 text-right tabular-nums text-slate-200">{spool.remaining_grams.toLocaleString()} g</td>
+                      <td className="px-4 py-3 text-right tabular-nums text-slate-300">{spool.cost_usd != null ? `$${spool.cost_usd.toFixed(2)}` : '—'}</td>
+                      <td className="px-4 py-3 text-center">
+                        {isLow ? (
+                          <span className="inline-flex items-center gap-1 rounded-full bg-red-900/50 border border-red-700 px-2 py-0.5 text-xs font-medium text-red-300">
+                            <AlertTriangle size={12} /> Low
+                          </span>
+                        ) : (
+                          <span className="inline-flex items-center rounded-full bg-emerald-900/30 border border-emerald-700 px-2 py-0.5 text-xs font-medium text-emerald-300">OK</span>
+                        )}
+                      </td>
+                      <td className="px-4 py-3 text-right">
+                        <div className="flex items-center justify-end gap-2">
+                          <button className="p-1.5 rounded hover:bg-slate-600 text-slate-400 hover:text-blue-400 transition-colors" title="Edit">
+                            <Pencil size={14} />
+                          </button>
+                          <button
+                            onClick={() => setDeleteId(spool.id)}
+                            className="p-1.5 rounded hover:bg-slate-600 text-slate-400 hover:text-red-400 transition-colors"
+                            title="Delete"
+                          >
+                            <Trash2 size={14} />
+                          </button>
+                        </div>
+                      </td>
+                    </tr>
+                  )
+                })}
+              </tbody>
+            </table>
+          </div>
+
+          {/* Mobile Cards */}
+          <div className="md:hidden space-y-3">
+            {filtered.length === 0 && (
+              <div className="text-center py-12 text-slate-500">No spools found.</div>
+            )}
+            {filtered.map((spool: FilamentSpool) => {
+              const isLow = spool.remaining_grams <= spool.low_stock_threshold_grams
+              return (
+                <div key={spool.id} className={`rounded-lg border ${isLow ? 'border-red-700 bg-red-900/10' : 'border-slate-700 bg-slate-800'} p-4 space-y-2`}>
+                  <div className="flex items-start justify-between">
+                    <div>
+                      <div className="font-semibold text-slate-100">{spool.name}</div>
+                      <div className="text-xs text-slate-400 mt-0.5">{spool.material_base?.name ?? '—'} · {spool.material_finish?.name ?? '—'}</div>
+                    </div>
+                    {isLow ? (
+                      <span className="inline-flex items-center gap-1 rounded-full bg-red-900/50 border border-red-700 px-2 py-0.5 text-xs font-medium text-red-300">
+                        <AlertTriangle size={12} /> Low
+                      </span>
+                    ) : (
+                      <span className="inline-flex items-center rounded-full bg-emerald-900/30 border border-emerald-700 px-2 py-0.5 text-xs font-medium text-emerald-300">OK</span>
+                    )}
+                  </div>
+
+                  <div className="flex items-center gap-3 text-sm">
+                    <div className="flex items-center gap-2">
+                      <ColorSwatch colorHex={spool.color_hex} size={20} />
+                      <span className="text-slate-400 uppercase text-xs">{spool.color_hex}</span>
+                    </div>
+                  </div>
+
+                  <div className="flex items-center justify-between text-sm">
+                    <span className="text-slate-400">Remaining: <span className="text-slate-200 font-medium tabular-nums">{spool.remaining_grams.toLocaleString()} g</span></span>
+                    <span className="text-slate-400">{spool.cost_usd != null ? `$${spool.cost_usd.toFixed(2)}` : '—'}</span>
+                  </div>
+
+                  <div className="flex items-center justify-end gap-2 pt-1">
+                    <button className="flex items-center gap-1 rounded-md bg-slate-700 px-3 py-1.5 text-xs font-medium text-slate-200 hover:bg-slate-600">
+                      <Pencil size={12} /> Edit
+                    </button>
+                    <button
+                      onClick={() => setDeleteId(spool.id)}
+                      className="flex items-center gap-1 rounded-md bg-red-900/30 border border-red-700 px-3 py-1.5 text-xs font-medium text-red-300 hover:bg-red-900/50"
+                    >
+                      <Trash2 size={12} /> Delete
+                    </button>
+                  </div>
+                </div>
+              )
+            })}
+          </div>
+
+          {/* Pagination */}
+          <div className="flex items-center justify-between pt-2">
+            <span className="text-sm text-slate-400">
+              Showing {page * PAGE_SIZE + 1}–{Math.min((page + 1) * PAGE_SIZE, total)} of {total}
+            </span>
+            <div className="flex items-center gap-2">
+              <button
+                onClick={() => setPage(p => Math.max(0, p - 1))}
+                disabled={page === 0}
+                className="p-2 rounded-lg bg-slate-800 border border-slate-700 text-slate-300 hover:bg-slate-700 disabled:opacity-40 disabled:cursor-not-allowed transition-colors"
+              >
+                <ChevronLeft size={16} />
+              </button>
+              <span className="text-sm text-slate-300 tabular-nums">{page + 1} / {totalPages}</span>
+              <button
+                onClick={() => setPage(p => Math.min(totalPages - 1, p + 1))}
+                disabled={page >= totalPages - 1}
+                className="p-2 rounded-lg bg-slate-800 border border-slate-700 text-slate-300 hover:bg-slate-700 disabled:opacity-40 disabled:cursor-not-allowed transition-colors"
+              >
+                <ChevronRight size={16} />
+              </button>
+            </div>
+          </div>
+        </>
+      )}
+
+      {/* Delete confirmation modal */}
+      {deleteId !== null && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 backdrop-blur-sm p-4">
+          <div className="w-full max-w-sm rounded-xl bg-slate-800 border border-slate-700 p-6 shadow-2xl space-y-4">
+            <div className="flex items-center gap-3">
+              <div className="flex h-10 w-10 items-center justify-center rounded-full bg-red-900/30">
+                <AlertTriangle size={20} className="text-red-400" />
+              </div>
+              <div>
+                <h3 className="text-lg font-semibold text-slate-100">Delete Spool?</h3>
+                <p className="text-sm text-slate-400">This action cannot be undone.</p>
+              </div>
+            </div>
+            <div className="flex justify-end gap-3">
+              <button
+                onClick={() => setDeleteId(null)}
+                className="rounded-lg bg-slate-700 px-4 py-2 text-sm font-medium text-slate-200 hover:bg-slate-600 transition-colors"
+              >
+                Cancel
+              </button>
+              <button
+                onClick={() => handleDelete(deleteId)}
+                className="rounded-lg bg-red-600 px-4 py-2 text-sm font-medium text-white hover:bg-red-500 transition-colors"
+              >
+                Delete
+              </button>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

frontend/src/services/api.ts

@@ -0,0 +1,19 @@
+import axios from 'axios'
+import type { ListResponse, FilamentSpool, PrintJob } from '../types'
+
+const api = axios.create({
+  baseURL: '/api',
+  headers: { 'Content-Type': 'application/json' },
+})
+
+export async function getFilaments(params?: { low_stock?: boolean; limit?: number; offset?: number }) {
+  const res = await api.get<ListResponse<FilamentSpool>>('/filaments', { params })
+  return res.data
+}
+
+export async function getPrintJobs(params?: { limit?: number; offset?: number }) {
+  const res = await api.get<ListResponse<PrintJob>>('/print-jobs', { params })
+  return res.data
+}
+
+export default api

frontend/src/services/filamentService.ts

@@ -0,0 +1,24 @@
+import axios from 'axios'
+import type { FilamentSpool, ListResponse, FilamentFilter } from '../types/filament'
+
+const API_BASE = '/api'
+
+export async function fetchFilaments(filter: FilamentFilter): Promise<ListResponse<FilamentSpool>> {
+  const params = new URLSearchParams()
+  if (filter.material) params.set('material', filter.material)
+  if (filter.finish) params.set('finish', filter.finish)
+  if (filter.color) params.set('color', filter.color)
+  if (filter.low_stock) params.set('low_stock', 'true')
+  if (filter.search) params.set('search', filter.search)
+  if (filter.sort_by) params.set('sort_by', filter.sort_by)
+  if (filter.sort_dir) params.set('sort_dir', filter.sort_dir)
+  if (filter.limit !== undefined) params.set('limit', String(filter.limit))
+  if (filter.offset !== undefined) params.set('offset', String(filter.offset))
+
+  const res = await axios.get<ListResponse<FilamentSpool>>(`${API_BASE}/filaments?${params.toString()}`)
+  return res.data
+}
+
+export async function deleteFilament(id: number): Promise<void> {
+  await axios.delete(`${API_BASE}/filaments/${id}`)
+}

frontend/src/types/filament.ts

@@ -0,0 +1,72 @@
+// Extrudex domain types
+
+export interface MaterialBase {
+  id: number
+  name: string
+  density_g_cm3: number
+  extrusion_temp_min?: number
+  extrusion_temp_max?: number
+  bed_temp_min?: number
+  bed_temp_max?: number
+  created_at: string
+  updated_at: string
+}
+
+export interface MaterialFinish {
+  id: number
+  name: string
+  description?: string
+  created_at: string
+  updated_at: string
+}
+
+export interface MaterialModifier {
+  id: number
+  name: string
+  description?: string
+  created_at: string
+  updated_at: string
+}
+
+export interface FilamentSpool {
+  id: number
+  name: string
+  material_base_id: number
+  material_base?: MaterialBase
+  material_finish_id: number
+  material_finish?: MaterialFinish
+  material_modifier_id?: number
+  material_modifier?: MaterialModifier
+  color_hex: string
+  brand?: string
+  diameter_mm: number
+  initial_grams: number
+  remaining_grams: number
+  spool_weight_grams?: number
+  cost_usd?: number
+  low_stock_threshold_grams: number
+  notes?: string
+  barcode?: string
+  deleted_at?: string
+  created_at: string
+  updated_at: string
+}
+
+export interface ListResponse<T> {
+  data: T[]
+  total: number
+  limit: number
+  offset: number
+}
+
+export interface FilamentFilter {
+  material?: string
+  finish?: string
+  color?: string
+  low_stock?: boolean
+  search?: string
+  sort_by?: string
+  sort_dir?: 'asc' | 'desc'
+  limit?: number
+  offset?: number
+}

frontend/src/types/index.ts

@@ -0,0 +1,42 @@
+export interface FilamentSpool {
+  id: number;
+  name: string;
+  material_base_id: number;
+  material_finish_id: number;
+  material_modifier_id: number;
+  color_hex: string;
+  brand: string;
+  diameter_mm: number;
+  initial_grams: number;
+  remaining_grams: number;
+  spool_weight_grams: number;
+  cost_usd: number;
+  low_stock_threshold_grams: number;
+  notes: string;
+  barcode: string;
+  created_at: string;
+  updated_at: string;
+  deleted_at: string | null;
+}
+
+export interface PrintJob {
+  id: number;
+  name: string;
+  printer_id: number;
+  filament_id: number;
+  status: string;
+  duration_seconds: number;
+  filament_used_grams: number;
+  cost_usd: number;
+  started_at: string;
+  completed_at: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface ListResponse<T> {
+  data: T[];
+  total: number;
+  limit: number;
+  offset: number;
+}

frontend/tsconfig.json

@@ -15,6 +15,7 @@
     "noUnusedLocals": true,
     "noUnusedParameters": true,
     "noFallthroughCasesInSwitch": true,
+    "ignoreDeprecations": "5.0",
     "baseUrl": ".",
     "paths": {
       "@/*": ["src/*"]