Merge pull request 'CUB-112: Scaffold Go backend' (#37) from agent/dex/CUB-112-go-scaffold into dev

Reviewed-on: #37

backend/Dockerfile

@@ -1,37 +1,25 @@
-# ── Stage 1: Build ──────────────────────────────────────────
+# Build stage
-FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
+FROM golang:1.24-alpine AS builder
-WORKDIR /src
 
-# Copy csproj first for layer caching — restores before copying source
-COPY Extrudex.csproj .
-RUN dotnet restore
-
-# Copy the rest of the source
-COPY . .
-RUN dotnet publish Extrudex.csproj \
-    -c Release \
-    -o /app/publish \
-    --no-restore
-
-# ── Stage 2: Runtime ────────────────────────────────────────
-FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS runtime
 WORKDIR /app
 
-# Install curl for health check (not included in aspnet base image)
+# Copy go mod files first for caching
-RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
+COPY go.mod go.sum ./
+RUN go mod download
 
-# Non-root user for security
+# Copy source and build
-RUN adduser --disabled-password --gecos "" appuser
+COPY . .
-USER appuser
+RUN CGO_ENABLED=0 GOOS=linux go build -o server ./cmd/server
 
-# Copy published output from build stage
+# Final stage
-COPY --from=build /app/publish .
+FROM alpine:latest
+RUN apk --no-cache add ca-certificates
+
+WORKDIR /root/
+
+# Copy binary from builder
+COPY --from=builder /app/server .
 
-# ASP.NET Core listens on 8080 by default in .NET 8+
 EXPOSE 8080
 
-# Health check against /health endpoint
+CMD ["./server"]
-HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
-    CMD curl --fail http://localhost:8080/health || exit 1
-
-ENTRYPOINT ["dotnet", "Extrudex.dll"]

backend/Domain/Interfaces/IFilamentUsageService.cs

@@ -0,0 +1,50 @@
+using Extrudex.Domain.Entities;
+
+namespace Extrudex.Domain.Interfaces;
+
+/// <summary>
+/// Service for persisting and querying filament usage records.
+/// Tracks consumption per print job and per spool for COGS and inventory tracking.
+/// </summary>
+public interface IFilamentUsageService
+{
+    /// <summary>
+    /// Records a new filament usage entry for a print job.
+    /// </summary>
+    /// <param name="printJobId">The print job that consumed the filament.</param>
+    /// <param name="spoolId">The spool that provided the filament.</param>
+    /// <param name="printerId">The printer that executed the print.</param>
+    /// <param name="gramsUsed">Grams of filament consumed.</param>
+    /// <param name="mmExtruded">Millimeters of filament extruded.</param>
+    /// <param name="notes">Optional notes about this usage record.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The created FilamentUsage entity.</returns>
+    Task<FilamentUsage> RecordUsageAsync(
+        Guid printJobId,
+        Guid spoolId,
+        Guid printerId,
+        decimal gramsUsed,
+        decimal mmExtruded,
+        string? notes = null,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Retrieves all filament usage records for a specific print job.
+    /// </summary>
+    /// <param name="printJobId">The print job ID.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Collection of filament usage records for the print job.</returns>
+    Task<IReadOnlyList<FilamentUsage>> GetByPrintJobAsync(
+        Guid printJobId,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Retrieves all filament usage records for a specific spool.
+    /// </summary>
+    /// <param name="spoolId">The spool ID.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Collection of filament usage records for the spool.</returns>
+    Task<IReadOnlyList<FilamentUsage>> GetBySpoolAsync(
+        Guid spoolId,
+        CancellationToken cancellationToken = default);
+}

backend/Infrastructure/Services/FilamentUsageService.cs

@@ -0,0 +1,79 @@
+using Extrudex.Domain.Entities;
+using Extrudex.Domain.Interfaces;
+using Extrudex.Infrastructure.Data;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Logging;
+
+namespace Extrudex.Infrastructure.Services;
+
+/// <summary>
+/// EF Core–backed implementation of the filament usage service.
+/// Persists usage records to the database and provides query methods
+/// for retrieving usage by print job or spool.
+/// </summary>
+public class FilamentUsageService : IFilamentUsageService
+{
+    private readonly ExtrudexDbContext _dbContext;
+    private readonly ILogger<FilamentUsageService> _logger;
+
+    public FilamentUsageService(
+        ExtrudexDbContext dbContext,
+        ILogger<FilamentUsageService> logger)
+    {
+        _dbContext = dbContext;
+        _logger = logger;
+    }
+
+    /// <inheritdoc />
+    public async Task<FilamentUsage> RecordUsageAsync(
+        Guid printJobId,
+        Guid spoolId,
+        Guid printerId,
+        decimal gramsUsed,
+        decimal mmExtruded,
+        string? notes = null,
+        CancellationToken cancellationToken = default)
+    {
+        var usage = new FilamentUsage
+        {
+            PrintJobId = printJobId,
+            SpoolId = spoolId,
+            PrinterId = printerId,
+            GramsUsed = gramsUsed,
+            MmExtruded = mmExtruded,
+            RecordedAt = DateTime.UtcNow,
+            Notes = notes
+        };
+
+        _dbContext.FilamentUsages.Add(usage);
+        await _dbContext.SaveChangesAsync(cancellationToken);
+
+        _logger.LogInformation(
+            "Recorded filament usage: {Grams}g / {Mm}mm for print job {JobId} on spool {SpoolId}",
+            gramsUsed, mmExtruded, printJobId, spoolId);
+
+        return usage;
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<FilamentUsage>> GetByPrintJobAsync(
+        Guid printJobId,
+        CancellationToken cancellationToken = default)
+    {
+        return await _dbContext.FilamentUsages
+            .Where(u => u.PrintJobId == printJobId)
+            .OrderByDescending(u => u.RecordedAt)
+            .ToListAsync(cancellationToken);
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<FilamentUsage>> GetBySpoolAsync(
+        Guid spoolId,
+        CancellationToken cancellationToken = default)
+    {
+        return await _dbContext.FilamentUsages
+            .Where(u => u.SpoolId == spoolId)
+            .OrderByDescending(u => u.RecordedAt)
+            .ToListAsync(cancellationToken);
+    }
+}

backend/Infrastructure/Services/MoonrakerUsagePoller.cs

@@ -0,0 +1,390 @@
+using Extrudex.Domain.DTOs.Moonraker;
+using Extrudex.Domain.Entities;
+using Extrudex.Domain.Enums;
+using Extrudex.Domain.Interfaces;
+using Extrudex.Infrastructure.Data;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+
+namespace Extrudex.Infrastructure.Services;
+
+/// <summary>
+/// Configuration options for the Moonraker usage polling service.
+/// </summary>
+public class MoonrakerPollerOptions
+{
+    /// <summary>
+    /// How often to poll each Moonraker printer for filament usage data.
+    /// Default: 30 seconds.
+    /// </summary>
+    public TimeSpan PollInterval { get; set; } = TimeSpan.FromSeconds(30);
+
+    /// <summary>
+    /// Timeout for individual Moonraker HTTP requests.
+    /// Default: 10 seconds.
+    /// </summary>
+    public TimeSpan RequestTimeout { get; set; } = TimeSpan.FromSeconds(10);
+
+    /// <summary>
+    /// Whether the polling service is enabled. Default: true.
+    /// Set to false to disable polling (e.g., in development or testing).
+    /// </summary>
+    public bool Enabled { get; set; } = true;
+}
+
+/// <summary>
+/// Background service that periodically polls Moonraker-connected printers
+/// for filament usage data. When a print job is detected as complete,
+/// the usage data is persisted to the FilamentUsage table via
+/// <see cref="IFilamentUsageService"/>.
+///
+/// <para>Polling logic:</para>
+/// <list type="number">
+///   <item>Query the database for all active printers with ConnectionType == Moonraker.</item>
+///   <item>For each printer, call <see cref="IMoonrakerClient.GetPrintStatsAsync"/> for live data
+///         and <see cref="IMoonrakerClient.GetPrintHistoryAsync"/> for completed job history.</item>
+///   <item>If usage data is available and the print state is "complete",
+///         create or update a FilamentUsage record.</item>
+///   <item>If the printer is unreachable or returns malformed data, log a warning
+///         and continue to the next printer (no crash).</item>
+/// </list>
+///
+/// <para>Error handling:</para>
+/// <list type="bullet">
+///   <item>API unreachable: logged as warning, poller continues for other printers.</item>
+///   <item>Malformed response: logged as warning, poller continues.</item>
+///   <item>Database errors: logged as error, poller continues.</item>
+/// </list>
+/// </summary>
+public class MoonrakerUsagePoller : BackgroundService
+{
+    private readonly IServiceScopeFactory _scopeFactory;
+    private readonly ILogger<MoonrakerUsagePoller> _logger;
+    private readonly MoonrakerPollerOptions _options;
+
+    /// <summary>
+    /// Tracks which Moonraker print jobs have already been recorded,
+    /// keyed by "printerId:gcodeFileName" to avoid duplicate recording.
+    /// </summary>
+    private readonly HashSet<string> _recordedJobs = new();
+
+    public MoonrakerUsagePoller(
+        IServiceScopeFactory scopeFactory,
+        ILogger<MoonrakerUsagePoller> logger,
+        IOptions<MoonrakerPollerOptions> options)
+    {
+        _scopeFactory = scopeFactory;
+        _logger = logger;
+        _options = options.Value;
+    }
+
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        if (!_options.Enabled)
+        {
+            _logger.LogInformation("Moonraker usage poller is disabled via configuration.");
+            return;
+        }
+
+        _logger.LogInformation(
+            "Moonraker usage poller starting. Poll interval: {Interval}",
+            _options.PollInterval);
+
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            try
+            {
+                await PollAllPrintersAsync(stoppingToken);
+            }
+            catch (Exception ex)
+            {
+                _logger.LogError(ex,
+                    "Unexpected error in Moonraker usage poller cycle. Continuing.");
+            }
+
+            await Task.Delay(_options.PollInterval, stoppingToken);
+        }
+
+        _logger.LogInformation("Moonraker usage poller stopping.");
+    }
+
+    private async Task PollAllPrintersAsync(CancellationToken cancellationToken)
+    {
+        using var scope = _scopeFactory.CreateScope();
+        var dbContext = scope.ServiceProvider.GetRequiredService<ExtrudexDbContext>();
+        var moonrakerClient = scope.ServiceProvider.GetRequiredService<IMoonrakerClient>();
+        var usageService = scope.ServiceProvider.GetRequiredService<IFilamentUsageService>();
+
+        var printers = await dbContext.Printers
+            .Where(p => p.IsActive && p.ConnectionType == ConnectionType.Moonraker)
+            .ToListAsync(cancellationToken);
+
+        if (printers.Count == 0)
+        {
+            _logger.LogDebug("No active Moonraker printers found.");
+            return;
+        }
+
+        _logger.LogDebug("Polling {Count} Moonraker printer(s).", printers.Count);
+
+        foreach (var printer in printers)
+        {
+            await PollPrinterAsync(
+                printer, moonrakerClient, usageService, dbContext, cancellationToken);
+        }
+    }
+
+    private async Task PollPrinterAsync(
+        Printer printer,
+        IMoonrakerClient moonrakerClient,
+        IFilamentUsageService usageService,
+        ExtrudexDbContext dbContext,
+        CancellationToken cancellationToken)
+    {
+        _logger.LogDebug(
+            "Polling Moonraker printer {PrinterName} ({Host}:{Port})",
+            printer.Name, printer.HostnameOrIp, printer.Port);
+
+        try
+        {
+            var printStats = await moonrakerClient.GetPrintStatsAsync(
+                printer.HostnameOrIp,
+                printer.Port,
+                printer.ApiKey,
+                cancellationToken);
+
+            if (printStats is null)
+            {
+                _logger.LogDebug(
+                    "No print stats available from printer {PrinterName}.", printer.Name);
+                return;
+            }
+
+            printer.LastSeenAt = DateTime.UtcNow;
+            await dbContext.SaveChangesAsync(cancellationToken);
+
+            _logger.LogDebug(
+                "Printer {PrinterName}: state={State}, filament={Mm}mm, file={File}",
+                printer.Name, printStats.State, printStats.FilamentUsedMm, printStats.Filename);
+
+            decimal mmExtruded = printStats.FilamentUsedMm;
+            if (mmExtruded <= 0)
+            {
+                _logger.LogDebug(
+                    "Printer {PrinterName} has no filament usage to record.", printer.Name);
+                return;
+            }
+
+            if (!IsCompleteState(printStats.State))
+            {
+                _logger.LogDebug(
+                    "Printer {PrinterName} print state '{State}' is not complete; skipping.",
+                    printer.Name, printStats.State);
+                return;
+            }
+
+            string gcodeFileName = printStats.Filename ?? $"unknown-{Guid.NewGuid():N}";
+            var deduplicationKey = $"{printer.Id}:{gcodeFileName}";
+            if (_recordedJobs.Contains(deduplicationKey))
+            {
+                _logger.LogDebug(
+                    "Printer {PrinterName} job '{File}' already recorded; skipping.",
+                    printer.Name, gcodeFileName);
+                return;
+            }
+
+            DateTime? startedAt = null;
+            DateTime? completedAt = null;
+            try
+            {
+                var history = await moonrakerClient.GetPrintHistoryAsync(
+                    printer.HostnameOrIp, printer.Port, printer.ApiKey,
+                    limit: 1, cancellationToken);
+
+                if (history.Items.Count > 0)
+                {
+                    var latestJob = history.Items[0];
+                    startedAt = latestJob.StartTime;
+                    completedAt = latestJob.EndTime;
+                }
+            }
+            catch (Exception ex)
+            {
+                _logger.LogDebug(ex,
+                    "Could not fetch history for printer {PrinterName}; proceeding with stats only.",
+                    printer.Name);
+            }
+
+            var printJob = await FindOrCreatePrintJobAsync(
+                dbContext, printer, mmExtruded, gcodeFileName,
+                startedAt, completedAt, cancellationToken);
+
+            if (printJob is null)
+            {
+                _logger.LogWarning(
+                    "Could not find or create print job for printer {PrinterName}. No active spool found.",
+                    printer.Name);
+                return;
+            }
+
+            var spool = await dbContext.Spools.FindAsync(
+                new object[] { printJob.SpoolId }, cancellationToken);
+
+            var gramsUsed = CalculateGramsUsed(mmExtruded, spool);
+
+            await usageService.RecordUsageAsync(
+                printJobId: printJob.Id,
+                spoolId: printJob.SpoolId,
+                printerId: printer.Id,
+                gramsUsed: gramsUsed,
+                mmExtruded: mmExtruded,
+                notes: $"Moonraker auto-recorded: {gcodeFileName}",
+                cancellationToken: cancellationToken);
+
+            _recordedJobs.Add(deduplicationKey);
+
+            _logger.LogInformation(
+                "Recorded Moonraker usage for printer {PrinterName}: {Mm}mm / {Grams}g, job '{File}'",
+                printer.Name, mmExtruded, gramsUsed, gcodeFileName);
+        }
+        catch (HttpRequestException ex)
+        {
+            _logger.LogWarning(ex,
+                "Moonraker API unreachable for printer {PrinterName} ({Host}:{Port}). Will retry next cycle.",
+                printer.Name, printer.HostnameOrIp, printer.Port);
+        }
+        catch (TaskCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            throw;
+        }
+        catch (TaskCanceledException ex)
+        {
+            _logger.LogWarning(ex,
+                "Moonraker request timed out for printer {PrinterName} ({Host}:{Port}).",
+                printer.Name, printer.HostnameOrIp, printer.Port);
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex,
+                "Unexpected error polling Moonraker printer {PrinterName}. Continuing to next printer.",
+                printer.Name);
+        }
+    }
+
+    private static bool IsCompleteState(string state) =>
+        state.Equals("complete", StringComparison.OrdinalIgnoreCase) ||
+        state.Equals("completed", StringComparison.OrdinalIgnoreCase);
+
+    private async Task<PrintJob?> FindOrCreatePrintJobAsync(
+        ExtrudexDbContext dbContext,
+        Printer printer,
+        decimal mmExtruded,
+        string gcodeFileName,
+        DateTime? startedAt,
+        DateTime? completedAt,
+        CancellationToken cancellationToken)
+    {
+        if (!string.IsNullOrEmpty(gcodeFileName))
+        {
+            var existingJob = await dbContext.PrintJobs
+                .Where(j => j.PrinterId == printer.Id &&
+                            j.GcodeFilePath == gcodeFileName &&
+                            j.DataSource == DataSource.Moonraker &&
+                            j.Status != JobStatus.Cancelled)
+                .OrderByDescending(j => j.CreatedAt)
+                .FirstOrDefaultAsync(cancellationToken);
+
+            if (existingJob is not null)
+            {
+                existingJob.MmExtruded = mmExtruded;
+                existingJob.GramsDerived = CalculateGramsUsed(
+                    mmExtruded,
+                    await dbContext.Spools.FindAsync(
+                        new object[] { existingJob.SpoolId }, cancellationToken));
+                existingJob.Status = JobStatus.Completed;
+                existingJob.CompletedAt = completedAt ?? DateTime.UtcNow;
+                existingJob.StartedAt ??= startedAt;
+                await dbContext.SaveChangesAsync(cancellationToken);
+                return existingJob;
+            }
+        }
+
+        var spool = await FindActiveSpoolForPrinterAsync(dbContext, printer, cancellationToken);
+        if (spool is null) return null;
+
+        var gramsDerived = CalculateGramsUsed(mmExtruded, spool);
+
+        var newJob = new PrintJob
+        {
+            PrinterId = printer.Id,
+            SpoolId = spool.Id,
+            PrintName = gcodeFileName ?? "Moonraker Print",
+            GcodeFilePath = gcodeFileName,
+            MmExtruded = mmExtruded,
+            GramsDerived = gramsDerived,
+            FilamentDiameterAtPrintMm = spool.FilamentDiameterMm,
+            MaterialDensityAtPrint = GetMaterialDensity(spool),
+            DataSource = DataSource.Moonraker,
+            Status = JobStatus.Completed,
+            StartedAt = startedAt ?? DateTime.UtcNow,
+            CompletedAt = completedAt ?? DateTime.UtcNow,
+            Notes = "Auto-created by Moonraker usage poller"
+        };
+
+        dbContext.PrintJobs.Add(newJob);
+        await dbContext.SaveChangesAsync(cancellationToken);
+
+        return newJob;
+    }
+
+    private static async Task<Spool?> FindActiveSpoolForPrinterAsync(
+        ExtrudexDbContext dbContext,
+        Printer printer,
+        CancellationToken cancellationToken)
+    {
+        var amsSpool = await dbContext.AmsSlots
+            .Include(s => s.Spool)
+            .ThenInclude(s => s!.MaterialBase)
+            .Include(s => s.AmsUnit)
+            .Where(s => s.AmsUnit.PrinterId == printer.Id && s.Spool != null && s.Spool.IsActive)
+            .Select(s => s.Spool)
+            .FirstOrDefaultAsync(cancellationToken);
+
+        if (amsSpool is not null) return amsSpool;
+
+        return await dbContext.Spools
+            .Include(s => s.MaterialBase)
+            .Where(s => s.IsActive)
+            .OrderByDescending(s => s.WeightRemainingGrams)
+            .FirstOrDefaultAsync(cancellationToken);
+    }
+
+    private static decimal CalculateGramsUsed(decimal mmExtruded, Spool? spool)
+    {
+        if (spool is null) return 0m;
+        var diameterMm = spool.FilamentDiameterMm;
+        var densityGcm3 = GetMaterialDensity(spool);
+        var radiusMm = diameterMm / 2m;
+        var crossSectionArea = Math.PI * (double)radiusMm * (double)radiusMm;
+        var volumeMm3 = (double)mmExtruded * crossSectionArea;
+        var volumeCm3 = volumeMm3 / 1000.0;
+        var grams = volumeCm3 * (double)densityGcm3;
+        return Math.Round((decimal)grams, 2);
+    }
+
+    private static decimal GetMaterialDensity(Spool? spool)
+    {
+        return spool?.MaterialBase?.Name?.ToUpperInvariant() switch
+        {
+            "PLA" => 1.24m,
+            "PETG" => 1.27m,
+            "ABS" => 1.04m,
+            "ASA" => 1.07m,
+            "TPU" => 1.21m,
+            "NYLON" or "PA" => 1.13m,
+            "PC" => 1.20m,
+            _ => 1.24m
+        };
+    }
+}

backend/Program.cs

@@ -61,6 +61,14 @@ builder.Services.AddSingleton<ILowStockDetector, LowStockDetector>();
 // ── Usage Logging ───────────────────────────────────────────
 builder.Services.AddScoped<IUsageLogService, UsageLogService>();
 
+// ── Filament Usage Service ──────────────────────────────────
+builder.Services.AddScoped<IFilamentUsageService, FilamentUsageService>();
+
+// ── Moonraker Usage Poller (Background Service) ─────────────
+builder.Services.Configure<MoonrakerPollerOptions>(
+    builder.Configuration.GetSection("MoonrakerPoller"));
+builder.Services.AddHostedService<MoonrakerUsagePoller>();
+
 // ── FluentValidation ──────────────────────────────────────
 // Registers all validators from the API assembly into DI.
 builder.Services.AddValidatorsFromAssembly(Assembly.GetExecutingAssembly());

backend/appsettings.json

@@ -23,5 +23,11 @@
   },
   "FilamentAlerts": {
     "LowStockThresholdPercent": 20
+  },
+  "MoonrakerPoller": {
+    "Enabled": true,
+    "PollInterval": "00:00:30",
+    "RequestTimeout": "00:00:10"
   }
+}
 }

backend/cmd/server/main.go

@@ -0,0 +1,80 @@
+package main
+
+import (
+	"context"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/config"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/db"
+	"github.com/CubeCraft-Creations/Extrudex/backend/internal/router"
+)
+
+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)
+		os.Exit(1)
+	}
+	defer db.ClosePool(dbPool)
+
+	slog.Info("database connected")
+
+	// Create router
+	r := router.New(cfg, dbPool)
+
+	// Create HTTP server
+	server := &http.Server{
+		Addr:         ":" + cfg.Port,
+		Handler:      r,
+		ReadTimeout:  15 * time.Second,
+		WriteTimeout: 15 * time.Second,
+		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 {
+			slog.Error("server error", "error", err)
+			os.Exit(1)
+		}
+	}()
+
+	// Wait for shutdown signal
+	quit := make(chan os.Signal, 1)
+	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+	<-quit
+
+	slog.Info("server shutting down")
+
+	// Graceful shutdown
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	if err := server.Shutdown(ctx); err != nil {
+		slog.Error("server shutdown error", "error", err)
+	}
+
+	db.ClosePool(dbPool)
+	slog.Info("server stopped")
+}

backend/go.mod

@@ -0,0 +1,9 @@
+module github.com/CubeCraft-Creations/Extrudex/backend
+
+go 1.24
+
+require (
+	github.com/go-chi/chi/v5 v5.2.0
+	github.com/jackc/pgx/v5 v5.7.4
+	github.com/kelseyhightower/envconfig v1.4.0
+)

backend/internal/config/config.go

@@ -0,0 +1,24 @@
+package config
+
+import (
+	"fmt"
+
+	"github.com/kelseyhightower/envconfig"
+)
+
+// Config holds all application configuration loaded from environment variables.
+type Config struct {
+	DatabaseURL string `envconfig:"database_url" required:"true"`
+	Port        string `envconfig:"port" default:"8080"`
+	CorsOrigin  string `envconfig:"cors_origin" default:"*"`
+	LogLevel    string `envconfig:"log_level" default:"info"`
+}
+
+// Load reads configuration from environment variables and returns a populated Config.
+func Load() (*Config, error) {
+	var cfg Config
+	if err := envconfig.Process("", &cfg); err != nil {
+		return nil, fmt.Errorf("failed to load config: %w", err)
+	}
+	return &cfg, nil
+}

backend/internal/db/db.go

@@ -0,0 +1,34 @@
+package db
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// NewPool creates a new pgx connection pool and verifies connectivity with a ping.
+func NewPool(databaseURL string) (*pgxpool.Pool, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	pool, err := pgxpool.New(ctx, databaseURL)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create db pool: %w", err)
+	}
+
+	if err := pool.Ping(ctx); err != nil {
+		pool.Close()
+		return nil, fmt.Errorf("failed to ping db: %w", err)
+	}
+
+	return pool, nil
+}
+
+// ClosePool gracefully closes the connection pool.
+func ClosePool(pool *pgxpool.Pool) {
+	if pool != nil {
+		pool.Close()
+	}
+}

backend/internal/handlers/health.go

@@ -0,0 +1,50 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// HealthHandler provides a health check endpoint that verifies database connectivity.
+type HealthHandler struct {
+	dbPool *pgxpool.Pool
+}
+
+// NewHealthHandler creates a new HealthHandler with the given database pool.
+func NewHealthHandler(dbPool *pgxpool.Pool) *HealthHandler {
+	return &HealthHandler{dbPool: dbPool}
+}
+
+// ServeHTTP handles GET /health requests.
+func (h *HealthHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
+	defer cancel()
+
+	dbConnected := false
+	if h.dbPool != nil {
+		if err := h.dbPool.Ping(ctx); err == nil {
+			dbConnected = true
+		} else {
+			slog.Warn("health check db ping failed", "error", err)
+		}
+	}
+
+	resp := map[string]any{
+		"status":       "ok",
+		"timestamp":    time.Now().UTC().Format(time.RFC3339),
+		"db_connected": dbConnected,
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	if !dbConnected {
+		w.WriteHeader(http.StatusServiceUnavailable)
+	}
+	if err := json.NewEncoder(w).Encode(resp); err != nil {
+		slog.Error("failed to encode health response", "error", err)
+	}
+}

backend/internal/repositories/.gitkeep

@@ -0,0 +1 @@
+# Repositories

backend/internal/router/router.go

@@ -0,0 +1,45 @@
+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/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 {
+	r := chi.NewRouter()
+
+	// Middleware
+	r.Use(middleware.RequestID)
+	r.Use(middleware.RealIP)
+	r.Use(middleware.Logger)
+	r.Use(middleware.Recoverer)
+	r.Use(middleware.Timeout(60 * time.Second))
+
+	// CORS
+	r.Use(func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.Header().Set("Access-Control-Allow-Origin", cfg.CorsOrigin)
+			w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
+			w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
+			if r.Method == http.MethodOptions {
+				w.WriteHeader(http.StatusNoContent)
+				return
+			}
+			next.ServeHTTP(w, r)
+		})
+	})
+
+	// Health check
+	healthHandler := handlers.NewHealthHandler(dbPool)
+	r.Get("/health", healthHandler.ServeHTTP)
+
+	return r
+}

backend/internal/services/.gitkeep

@@ -0,0 +1 @@
+# Services