refactor(db): port preview environments to sqlc

Tranche 3: all 30 raw sites in preview_environments.go — list/detail
joins, access-check reads, create/update/delete, promote, user cleanup,
TTL sweep, and the status-sync UPDATE...FROM CASE. Deployments and
preview_environments schema.sql definitions completed to match runtime.
Shared mapper converts generated rows to the PreviewEnvironment DTO;
DeleteServiceByID from tranche 2 is reused for clone teardown.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

ROADMAP2.md

@@ -252,9 +252,12 @@ goroutines; this fixes correctness *and* unlocks the ops surface.
 - [x] **Graph deploy pipeline** — creates services in dependency order,
   resolves vars/secrets, triggers builds. `deployTemplateGraph`,
   `POST /templates/deploy` (inline), `POST /projects/:id/import-compose`.
-- [ ] **Visual template builder** — canvas mode: drop git/image/db
-  nodes, wire refs, set order, save/publish. Reuses existing canvas
-  primitives (dflow's `templates/compose` is exactly this).
+- [x] **Visual template builder** — canvas mode in the template editor:
+  web/worker/cron/database nodes, handles wire `depends_on`, inspector
+  edits image/repo/engine/port/env/volumes, live validation, applies
+  back to the version-2 graph JSON. Positions persist under
+  `config.canvas`; flat legacy configs open as a single node.
+  `builder-model.ts` + `TemplateBuilder.tsx`.
 - [x] **Catalog growth** — seeded graph stacks for n8n, Gitea,
   Nextcloud, Vaultwarden, Umami, Immich (Plausible already shipped).
   `TestSeedTemplatesResolveCleanly` keeps every seed parseable,
@@ -507,15 +510,19 @@ and wired refs, one click or one CLI call.
     deployment history, env-doctor issues surfaced on the service view.
   - [x] **env var edit + domain management + replica scaling** (PR #61 —
     mobile v1.5: variables editor, domains screen, scale + sleep
-    settings, notifications tab). **cron execution history** still open.
+    settings, notifications tab, cron jobs screen with run-now and
+    execution history).
   - [x] **Push notifications** — per-user `notification_channels`
     (ntfy + Gotify): every `insertUserNotification` fans out best-effort
     to enabled channels; CRUD + live test-ping via web settings, CLI
     `notifications channels`, and MCP. FCM/APNs remain optional.
-  - [ ] **Offline resilience** — cached last-known state + unreachable
-    banner.
-- [ ] **Status/offline resilience** — app + CLI degrade gracefully when
-  the instance is unreachable (cached last-known state, clear banner).
+  - [x] **Offline resilience** — AsyncStorage-persisted query cache
+    (7d, high-churn keys excluded) + banner when the instance is
+    unreachable (`/health` ping + expo-network).
+- [x] **Status/offline resilience** — web persists the query cache to
+  localStorage (24h) and PlatformShell shows a "last-known data" banner
+  on offline/unreachable; CLI exits `ExitUnavailable` with a clean
+  "cannot reach" message (no stack traces).
 
 ## 10. Carried-over debt (ROADMAP.md items still open)
 
@@ -530,12 +537,21 @@ and wired refs, one click or one CLI call.
   workspace, CLI `environments` + MCP parity. Per-env vars/domains ride the
   service's own scope (one env per service); promote ships via preview
   promote.
-- [ ] **sqlc port** — ~140 raw `database/sql` sites → `sqlc/queries/`.
+- [ ] **sqlc port** — ~300 raw `database/sql` sites → `sqlc/queries/`. Done in tranches (dynamic queries stay raw): metrics storage + service domains ported.
 - [ ] **Tests** — canvas/wizard frontend coverage, deployment/template/
   webhook table tests, Playwright e2e golden path.
-- [ ] **First-run wizard** — admin → GitHub App (manifest flow from
-  Phase G makes this self-serve) → Tunnel → done.
-- [ ] **Self-upgrade loop verification**, docs freshness, v1.0.0 release.
+- [x] **First-run wizard** — public `GET /setup/status` + authed
+  `POST /setup/complete`; `/setup` page steps admin account → GitHub App
+  manifest flow (callback returns to the wizard via a session marker) →
+  optional Cloudflare tunnel token → done. Shell redirects signed-in
+  users to `/setup` while `needs_setup`; installs with existing projects
+  auto-complete so nobody gets nagged retroactively.
+- [x] **Self-upgrade loop verification** — live-verified: admin
+  `POST /agents/:id/upgrade` → `self_upgrade` command → agent downloads
+  `/api/agents/download/linux-amd64` → sha256 verify → `--version`
+  sanity → atomic rename → result posts → `syscall.Exec` re-exec. Agent
+  ran `v0.0.1-old`, came back `v9.9.9-test`, command row `completed`.
+- [ ] **Docs freshness, v1.0.0 release.**
 
 ## 11. Deliberately not imported from dflow
 

app/backend/internal/api/cron_test.go

@@ -0,0 +1,66 @@
+package api
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestCalculateNextRun(t *testing.T) {
+	cases := []struct {
+		name     string
+		schedule string
+		timezone string
+		wantErr  bool
+	}{
+		{"every minute", "* * * * *", "", false},
+		{"daily at 4am", "0 4 * * *", "UTC", false},
+		{"weekday run", "0 9 * * 1-5", "Europe/Prague", false},
+		{"whitespace tolerated", "  */15 * * * *  ", "", false},
+		{"empty schedule", "", "", true},
+		{"bad field count", "* * *", "", true},
+		{"garbage", "not a cron", "", true},
+		{"bad timezone", "0 4 * * *", "Mars/Olympus", true},
+	}
+	now := time.Now()
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			next, err := calculateNextRun(tc.schedule, tc.timezone)
+			if tc.wantErr {
+				if err == nil {
+					t.Fatalf("expected error, got next=%v", next)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if next == nil {
+				t.Fatal("expected non-nil next run")
+			}
+			if !next.After(now) {
+				t.Errorf("next run %v is not after %v", next, now)
+			}
+		})
+	}
+}
+
+func TestCalculateNextRunTimezone(t *testing.T) {
+	// CRON_TZ must change the computed instant: 04:00 in a fixed-offset zone
+	// lands at a different UTC hour than 04:00 UTC.
+	utcNext, err := calculateNextRun("0 4 * * *", "UTC")
+	if err != nil {
+		t.Fatalf("utc: %v", err)
+	}
+	tokyoNext, err := calculateNextRun("0 4 * * *", "Asia/Tokyo")
+	if err != nil {
+		t.Fatalf("tokyo: %v", err)
+	}
+	if utcNext.Equal(*tokyoNext) {
+		t.Fatalf("timezone had no effect: both %v", utcNext)
+	}
+	if !strings.EqualFold(utcNext.Location().String(), "Local") {
+		// UTC-scheduled runs still land in server-local time representation.
+		t.Logf("utc next: %v / tokyo next: %v", utcNext, tokyoNext)
+	}
+}

app/backend/internal/api/deployments.go

@@ -803,9 +803,15 @@ func splitImageReference(image, fallbackTag string) (string, string) {
 		return "", fallbackTag
 	}
 
+	// Digest-pinned refs (name[:tag]@sha256:…) carry no usable tag — the
+	// colon lives inside the digest and must not be split.
+	if strings.Contains(image, "@") {
+		return image, fallbackTag
+	}
+
 	lastSlash := strings.LastIndex(image, "/")
 	lastColon := strings.LastIndex(image, ":")
-	if lastColon > lastSlash && !strings.Contains(image[lastColon:], "@") {
+	if lastColon > lastSlash {
 		return image[:lastColon], image[lastColon+1:]
 	}
 

app/backend/internal/api/deployments_test.go

@@ -0,0 +1,46 @@
+package api
+
+import "testing"
+
+func TestSplitImageReference(t *testing.T) {
+	cases := []struct {
+		name      string
+		image     string
+		fallback  string
+		wantImage string
+		wantTag   string
+	}{
+		{"empty uses fallback tag", "", "latest", "", "latest"},
+		{"bare image", "nginx", "latest", "nginx", "latest"},
+		{"tagged image", "nginx:1.27", "latest", "nginx", "1.27"},
+		{"registry with port untagged", "registry.local:5000/app", "latest", "registry.local:5000/app", "latest"},
+		{"registry with port tagged", "registry.local:5000/app:v2", "latest", "registry.local:5000/app", "v2"},
+		{"digest stays whole", "nginx@sha256:abc123", "latest", "nginx@sha256:abc123", "latest"},
+		{"tag and digest", "nginx:1.27@sha256:abc", "latest", "nginx:1.27@sha256:abc", "latest"},
+		{"namespaced tagged", "ghcr.io/owner/repo:dev", "latest", "ghcr.io/owner/repo", "dev"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			img, tag := splitImageReference(tc.image, tc.fallback)
+			if img != tc.wantImage || tag != tc.wantTag {
+				t.Fatalf("splitImageReference(%q, %q) = (%q, %q), want (%q, %q)",
+					tc.image, tc.fallback, img, tag, tc.wantImage, tc.wantTag)
+			}
+		})
+	}
+}
+
+func TestMapEngineStatusToDBStatus(t *testing.T) {
+	cases := map[string]string{
+		"running":   "deployed",
+		"building":  "building",
+		"failed":    "failed",
+		"cancelled": "cancelled",
+		"queued":    "queued",
+	}
+	for in, want := range cases {
+		if got := mapEngineStatusToDBStatus(in); got != want {
+			t.Fatalf("mapEngineStatusToDBStatus(%q) = %q, want %q", in, got, want)
+		}
+	}
+}

app/backend/internal/api/domains.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"database/sql"
 	"encoding/json"
+	"fmt"
 	"net"
 	"net/http"
 	"regexp"
@@ -44,19 +45,26 @@ func validHostname(d string) bool {
 }
 
 func loadServiceDomains(db *database.DB, serviceID uuid.UUID) []ServiceDomain {
-	rows, err := db.Query(
-		`SELECT id, service_id, domain, is_default, cert_type, cert_status, last_checked_at, created_at
-		 FROM service_domains WHERE service_id = $1 ORDER BY is_default DESC, created_at ASC`, serviceID)
+	rows, err := sqlcdb.New(db.DB).ListServiceDomains(context.Background(), serviceID)
 	if err != nil {
 		return nil
 	}
-	defer rows.Close()
-	out := []ServiceDomain{}
-	for rows.Next() {
-		var d ServiceDomain
-		if err := rows.Scan(&d.ID, &d.ServiceID, &d.Domain, &d.IsDefault, &d.CertType, &d.CertStatus, &d.LastCheckedAt, &d.CreatedAt); err == nil {
-			out = append(out, d)
+	out := make([]ServiceDomain, 0, len(rows))
+	for _, r := range rows {
+		d := ServiceDomain{
+			ID:         r.ID,
+			ServiceID:  r.ServiceID,
+			Domain:     r.Domain,
+			IsDefault:  r.IsDefault,
+			CertType:   r.CertType,
+			CertStatus: r.CertStatus,
+			CreatedAt:  r.CreatedAt,
 		}
+		if r.LastCheckedAt.Valid {
+			t := r.LastCheckedAt.Time
+			d.LastCheckedAt = &t
+		}
+		out = append(out, d)
 	}
 	return out
 }
@@ -104,22 +112,20 @@ func dnsLabel(name string) string {
 // base domain; spread services union every eligible node's base domain.
 // Local services get nothing — there is no instance-level base domain yet.
 func serviceAutoDomains(db *database.DB, serviceID uuid.UUID) []string {
-	var name string
-	var nodeID sql.NullString
-	var spread bool
-	if err := db.QueryRow(
-		`SELECT name, node_id, COALESCE(spread, false) FROM services WHERE id = $1`, serviceID,
-	).Scan(&name, &nodeID, &spread); err != nil {
+	ctx := context.Background()
+	q := sqlcdb.New(db.DB)
+	brief, err := q.GetServicePlacementBrief(ctx, serviceID)
+	if err != nil {
 		return nil
 	}
-	label := dnsLabel(name)
+	label := dnsLabel(brief.Name)
 	if label == "" {
 		return nil
 	}
 
 	var bases []string
-	ctx := context.Background()
-	q := sqlcdb.New(db.DB)
+	nodeID := brief.NodeID
+	spread := brief.Spread
 	switch {
 	case nodeID.Valid && nodeID.String != "":
 		if a, err := q.GetAgent(ctx, nodeID.String); err == nil && a.DefaultDomain != "" {
@@ -142,24 +148,25 @@ func serviceAutoDomains(db *database.DB, serviceID uuid.UUID) []string {
 // syncDefaultDomain writes the is_default row back to services.domain so
 // legacy reads (CLI tables, public_url) keep working.
 func syncDefaultDomain(db *database.DB, serviceID uuid.UUID) {
-	var domain string
-	err := db.QueryRow(
-		`SELECT domain FROM service_domains WHERE service_id = $1 AND is_default`, serviceID).Scan(&domain)
+	ctx := context.Background()
+	q := sqlcdb.New(db.DB)
+	domain, err := q.GetServiceDomainDefault(ctx, serviceID)
 	if err == sql.ErrNoRows {
-		err = db.QueryRow(
-			`SELECT domain FROM service_domains WHERE service_id = $1 ORDER BY created_at ASC LIMIT 1`, serviceID).Scan(&domain)
+		domain, err = q.GetServiceDomainFirst(ctx, serviceID)
 	}
 	if err == sql.ErrNoRows {
 		domain = ""
 	}
-	_, _ = db.Exec(`UPDATE services SET domain = $1 WHERE id = $2`, domain, serviceID)
+	_ = q.SetServiceLegacyDomain(ctx, sqlcdb.SetServiceLegacyDomainParams{Domain: domain, ID: serviceID})
 }
 
 // serviceAccess loads the maintenance/basic-auth columns for the runtime spec.
 func serviceAccess(db *database.DB, serviceID uuid.UUID) (maintenance bool, basicAuth string) {
-	_ = db.QueryRow(`SELECT maintenance_mode, basic_auth_users FROM services WHERE id = $1`, serviceID).
-		Scan(&maintenance, &basicAuth)
-	return maintenance, basicAuth
+	row, err := sqlcdb.New(db.DB).GetServiceAccess(context.Background(), serviceID)
+	if err != nil {
+		return false, ""
+	}
+	return row.MaintenanceMode, row.BasicAuthUsers
 }
 
 // maintenanceURL is the redirect target for maintenance mode — the public
@@ -204,11 +211,12 @@ func basicAuthUsernames(encoded string) []string {
 // serviceWriteAccess mirrors the service update handler's access check.
 func serviceWriteAccess(c *gin.Context, db *database.DB, serviceID uuid.UUID) bool {
 	userID, _ := c.Get("user_id")
-	var ok bool
-	err := db.QueryRow(
-		`SELECT EXISTS(SELECT 1 FROM services s JOIN projects p ON s.project_id = p.id
-			WHERE s.id = $1 AND (p.owner_id = $2 OR $3::bool))`,
-		serviceID, userID, contextIsAdmin(c)).Scan(&ok)
+	uid, _ := uuid.Parse(fmt.Sprint(userID))
+	ok, err := sqlcdb.New(db.DB).ServiceWriteAccess(context.Background(), sqlcdb.ServiceWriteAccessParams{
+		ID:      serviceID,
+		OwnerID: uid,
+		Column3: contextIsAdmin(c),
+	})
 	return err == nil && ok
 }
 
@@ -255,9 +263,11 @@ func handleAddServiceDomain(c *gin.Context) {
 		return
 	}
 
+	ctx := c.Request.Context()
+	q := sqlcdb.New(db.(*database.DB).DB)
+
 	// First domain on a service becomes the default automatically.
-	var count int
-	_ = db.(*database.DB).QueryRow(`SELECT COUNT(*) FROM service_domains WHERE service_id = $1`, serviceID).Scan(&count)
+	count, _ := q.CountServiceDomains(ctx, serviceID)
 	makeDefault := req.IsDefault || count == 0
 
 	tx, err := db.(*database.DB).Begin()
@@ -266,19 +276,18 @@ func handleAddServiceDomain(c *gin.Context) {
 		return
 	}
 	defer tx.Rollback()
+	qtx := q.WithTx(tx)
 	if makeDefault {
-		if _, err := tx.Exec(`UPDATE service_domains SET is_default = false WHERE service_id = $1`, serviceID); err != nil {
+		if err := qtx.ClearServiceDomainDefault(ctx, serviceID); err != nil {
 			respondError(c, http.StatusInternalServerError, "INTERNAL", "Failed to add domain")
 			return
 		}
 	}
-	var inserted ServiceDomain
-	err = tx.QueryRow(
-		`INSERT INTO service_domains (service_id, domain, is_default)
-		 VALUES ($1, $2, $3)
-		 RETURNING id, service_id, domain, is_default, cert_type, cert_status, created_at`,
-		serviceID, domain, makeDefault).
-		Scan(&inserted.ID, &inserted.ServiceID, &inserted.Domain, &inserted.IsDefault, &inserted.CertType, &inserted.CertStatus, &inserted.CreatedAt)
+	row, err := qtx.CreateServiceDomain(ctx, sqlcdb.CreateServiceDomainParams{
+		ServiceID: serviceID,
+		Domain:    domain,
+		IsDefault: makeDefault,
+	})
 	if err != nil {
 		if strings.Contains(err.Error(), "duplicate") || strings.Contains(err.Error(), "unique") {
 			respondError(c, http.StatusConflict, "CONFLICT", "Domain already attached to this service")
@@ -292,7 +301,15 @@ func handleAddServiceDomain(c *gin.Context) {
 		return
 	}
 	syncDefaultDomain(db.(*database.DB), serviceID)
-	c.JSON(http.StatusCreated, gin.H{"domain": inserted})
+	c.JSON(http.StatusCreated, gin.H{"domain": ServiceDomain{
+		ID:         row.ID,
+		ServiceID:  row.ServiceID,
+		Domain:     row.Domain,
+		IsDefault:  row.IsDefault,
+		CertType:   row.CertType,
+		CertStatus: row.CertStatus,
+		CreatedAt:  row.CreatedAt,
+	}})
 }
 
 func handleDeleteServiceDomain(c *gin.Context) {
@@ -315,9 +332,8 @@ func handleDeleteServiceDomain(c *gin.Context) {
 		respondError(c, http.StatusBadRequest, "VALIDATION", "Invalid domain ID")
 		return
 	}
-	res, err := db.(*database.DB).Exec(
-		`DELETE FROM service_domains WHERE id = $1 AND service_id = $2`, domainID, serviceID)
-	affected, _ := res.RowsAffected()
+	affected, err := sqlcdb.New(db.(*database.DB).DB).DeleteServiceDomain(
+		c.Request.Context(), sqlcdb.DeleteServiceDomainParams{ID: domainID, ServiceID: serviceID})
 	if err != nil || affected == 0 {
 		respondError(c, http.StatusNotFound, "NOT_FOUND", "Domain not found")
 		return
@@ -346,14 +362,12 @@ func handleSetDefaultDomain(c *gin.Context) {
 		respondError(c, http.StatusBadRequest, "VALIDATION", "Invalid domain ID")
 		return
 	}
-	res, err := db.(*database.DB).Exec(
-		`UPDATE service_domains SET is_default = (id = $1) WHERE service_id = $2`,
-		domainID, serviceID)
+	affected, err := sqlcdb.New(db.(*database.DB).DB).SetServiceDomainDefault(
+		c.Request.Context(), sqlcdb.SetServiceDomainDefaultParams{ID: domainID, ServiceID: serviceID})
 	if err != nil {
 		respondError(c, http.StatusInternalServerError, "INTERNAL", "Failed to set default domain")
 		return
 	}
-	affected, _ := res.RowsAffected()
 	if affected == 0 {
 		respondError(c, http.StatusNotFound, "NOT_FOUND", "Domain not found")
 		return
@@ -421,7 +435,7 @@ func handleCheckServiceDomains(c *gin.Context) {
 			r.Status = "ok"
 		}
 		results = append(results, r)
-		_, _ = dbh.Exec(`UPDATE service_domains SET last_checked_at = NOW() WHERE id = $1`, d.ID)
+		_ = sqlcdb.New(dbh.DB).TouchServiceDomainChecked(c.Request.Context(), d.ID)
 	}
 	c.JSON(http.StatusOK, gin.H{"domains": results})
 }

app/backend/internal/api/domains_test.go

@@ -1,6 +1,29 @@
 package api
 
-import "testing"
+import (
+	"context"
+	"os"
+	"strings"
+	"time"
+	"testing"
+
+	"containr/internal/database"
+	"containr/internal/database/sqlcdb"
+
+	"github.com/google/uuid"
+)
+
+func testDSNString(t *testing.T) string {
+	t.Helper()
+	dsn := os.Getenv("METRICS_TEST_DSN")
+	if dsn == "" {
+		dsn = os.Getenv("DATABASE_URL")
+	}
+	if dsn == "" {
+		t.Skip("METRICS_TEST_DSN not set")
+	}
+	return dsn
+}
 
 func TestDNSLabel(t *testing.T) {
 	cases := map[string]string{
@@ -24,3 +47,294 @@ func TestDNSLabelLengthCap(t *testing.T) {
 		t.Fatalf("label over 63 chars: %d", len(got))
 	}
 }
+
+// Live invariant test against real Postgres — set METRICS_TEST_DSN (or
+// DATABASE_URL). Verifies the generated domain queries preserve the
+// default-domain and legacy services.domain invariants.
+func TestServiceDomainsLiveInvariants(t *testing.T) {
+	dsn := testDSNString(t)
+	db, err := database.NewConnection(dsn)
+	if err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	defer db.Close()
+	ctx := context.Background()
+	q := sqlcdb.New(db.DB)
+
+	userID := uuid.New()
+	projectID := uuid.New()
+	envID := uuid.New()
+	serviceID := uuid.New()
+	suffix := strings.ReplaceAll(serviceID.String()[:8], "-", "")
+
+	must := func(err error) {
+		t.Helper()
+		if err != nil {
+			t.Fatalf("setup: %v", err)
+		}
+	}
+	_, err = db.Exec(`INSERT INTO users (id, email, password_hash, name) VALUES ($1, $2, 'x', 'test')`,
+		userID, "domtest-"+suffix+"@test.local")
+	must(err)
+	_, err = db.Exec(`INSERT INTO projects (id, name, owner_id, is_approved) VALUES ($1, $2, $3, true)`,
+		projectID, "domtest-"+suffix, userID)
+	must(err)
+	_, err = db.Exec(`INSERT INTO environments (id, name, project_id) VALUES ($1, 'production', $2)`,
+		envID, projectID)
+	must(err)
+	_, err = db.Exec(`INSERT INTO services (id, name, project_id, environment_id, service_type, source_type)
+		VALUES ($1, 'domtest-`+suffix+`', $2, $3, 'web', 'image')`,
+		serviceID, projectID, envID)
+	must(err)
+	defer func() {
+		_, _ = db.Exec(`DELETE FROM users WHERE id = $1`, userID)
+	}()
+
+	d1, err := q.CreateServiceDomain(ctx, sqlcdb.CreateServiceDomainParams{
+		ServiceID: serviceID, Domain: "a-" + suffix + ".example.com", IsDefault: true})
+	if err != nil {
+		t.Fatalf("create d1: %v", err)
+	}
+	d2, err := q.CreateServiceDomain(ctx, sqlcdb.CreateServiceDomainParams{
+		ServiceID: serviceID, Domain: "b-" + suffix + ".example.com", IsDefault: false})
+	if err != nil {
+		t.Fatalf("create d2: %v", err)
+	}
+
+	syncDefaultDomain(db, serviceID)
+	var legacy string
+	if err := db.QueryRow(`SELECT domain FROM services WHERE id = $1`, serviceID).Scan(&legacy); err != nil {
+		t.Fatalf("read legacy: %v", err)
+	}
+	if legacy != d1.Domain {
+		t.Fatalf("legacy domain = %q, want %q", legacy, d1.Domain)
+	}
+
+	// Switch default: exactly one row stays default, legacy follows.
+	if err := q.ClearServiceDomainDefault(ctx, serviceID); err != nil {
+		t.Fatalf("clear: %v", err)
+	}
+	if _, err := q.SetServiceDomainDefault(ctx, sqlcdb.SetServiceDomainDefaultParams{
+		ID: d2.ID, ServiceID: serviceID}); err != nil {
+		t.Fatalf("set default: %v", err)
+	}
+	syncDefaultDomain(db, serviceID)
+	if err := db.QueryRow(`SELECT domain FROM services WHERE id = $1`, serviceID).Scan(&legacy); err != nil {
+		t.Fatalf("read legacy2: %v", err)
+	}
+	if legacy != d2.Domain {
+		t.Fatalf("legacy after switch = %q, want %q", legacy, d2.Domain)
+	}
+
+	doms := loadServiceDomains(db, serviceID)
+	if len(doms) != 2 || !doms[0].IsDefault || doms[0].Domain != d2.Domain {
+		t.Fatalf("list order wrong: %+v", doms)
+	}
+
+	// Deleting the default falls back to the remaining domain.
+	if _, err := q.DeleteServiceDomain(ctx, sqlcdb.DeleteServiceDomainParams{
+		ID: d2.ID, ServiceID: serviceID}); err != nil {
+		t.Fatalf("delete d2: %v", err)
+	}
+	syncDefaultDomain(db, serviceID)
+	if err := db.QueryRow(`SELECT domain FROM services WHERE id = $1`, serviceID).Scan(&legacy); err != nil {
+		t.Fatalf("read legacy3: %v", err)
+	}
+	if legacy != d1.Domain {
+		t.Fatalf("legacy after delete = %q, want %q", legacy, d1.Domain)
+	}
+}
+
+// Live clone test: cloneServiceRow must copy config, domains, and variables
+// verbatim, start stopped, and land in the target project/environment.
+func TestCloneServiceRowLive(t *testing.T) {
+	dsn := testDSNString(t)
+	db, err := database.NewConnection(dsn)
+	if err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	defer db.Close()
+	ctx := context.Background()
+	q := sqlcdb.New(db.DB)
+
+	userID := uuid.New()
+	projectID := uuid.New()
+	envID := uuid.New()
+	serviceID := uuid.New()
+	suffix := strings.ReplaceAll(serviceID.String()[:8], "-", "")
+	must := func(err error) {
+		t.Helper()
+		if err != nil {
+			t.Fatalf("setup: %v", err)
+		}
+	}
+	_, err = db.Exec(`INSERT INTO users (id, email, password_hash, name) VALUES ($1, $2, 'x', 'test')`,
+		userID, "clone-"+suffix+"@test.local")
+	must(err)
+	_, err = db.Exec(`INSERT INTO projects (id, name, owner_id, is_approved) VALUES ($1, $2, $3, true)`,
+		projectID, "clone-"+suffix, userID)
+	must(err)
+	_, err = db.Exec(`INSERT INTO environments (id, name, project_id) VALUES ($1, 'production', $2)`,
+		envID, projectID)
+	must(err)
+	_, err = db.Exec(`INSERT INTO services (id, name, project_id, environment_id, service_type, source_type,
+		image_name, port, volumes, traefik_labels, maintenance_mode)
+		VALUES ($1, $2, $3, $4, 'web', 'image', 'traefik/whoami:latest', 80,
+			'[{"mount":"/data"}]'::jsonb,
+			'{"middlewares.rl.ratelimit.average":"100"}'::jsonb, true)`,
+		serviceID, "clonesrc-"+suffix, projectID, envID)
+	must(err)
+	defer func() { _, _ = db.Exec(`DELETE FROM users WHERE id = $1`, userID) }()
+
+	if _, err := q.CreateServiceDomain(ctx, sqlcdb.CreateServiceDomainParams{
+		ServiceID: serviceID, Domain: "src-" + suffix + ".example.com", IsDefault: true}); err != nil {
+		t.Fatalf("seed domain: %v", err)
+	}
+	if _, err := db.Exec(`INSERT INTO environment_variables (id, service_id, key, value, is_secret)
+		VALUES ($1, $2, 'FOO', 'bar', false)`, uuid.New(), serviceID); err != nil {
+		t.Fatalf("seed var: %v", err)
+	}
+
+	cloneID, err := cloneServiceRow(db, serviceID, projectID, "clone-"+suffix, "")
+	if err != nil {
+		t.Fatalf("clone: %v", err)
+	}
+
+	var status, imageName, env string
+	var maintenance bool
+	var volumes, labels []byte
+	if err := db.QueryRow(`SELECT status, image_name, COALESCE(environment,''), maintenance_mode,
+		volumes, traefik_labels FROM services WHERE id = $1`, cloneID).
+		Scan(&status, &imageName, &env, &maintenance, &volumes, &labels); err != nil {
+		t.Fatalf("read clone: %v", err)
+	}
+	if status != "stopped" || imageName != "traefik/whoami:latest" || env != "production" {
+		t.Fatalf("clone mismatch: %v %v %v", status, imageName, env)
+	}
+	if !maintenance || string(volumes) == "[]" || string(labels) == "{}" {
+		t.Fatalf("clone dropped config: maint=%v vol=%s labels=%s", maintenance, volumes, labels)
+	}
+	doms := loadServiceDomains(db, cloneID)
+	if len(doms) != 1 || doms[0].Domain != "src-"+suffix+".example.com" || !doms[0].IsDefault {
+		t.Fatalf("domains not cloned: %+v", doms)
+	}
+	var varVal string
+	if err := db.QueryRow(`SELECT value FROM environment_variables WHERE service_id = $1 AND key = 'FOO'`,
+		cloneID).Scan(&varVal); err != nil || varVal != "bar" {
+		t.Fatalf("vars not cloned: %v %q", err, varVal)
+	}
+}
+
+// Live preview-environment test: generated queries must preserve the
+// access-check join, the status-sync CASE, and the sweep listing.
+func TestPreviewEnvironmentsLiveInvariants(t *testing.T) {
+	dsn := testDSNString(t)
+	db, err := database.NewConnection(dsn)
+	if err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	defer db.Close()
+	ctx := context.Background()
+	q := sqlcdb.New(db.DB)
+
+	userID := uuid.New()
+	projectID := uuid.New()
+	envID := uuid.New()
+	srcID := uuid.New()
+	cloneID := uuid.New()
+	previewID := uuid.New()
+	suffix := strings.ReplaceAll(previewID.String()[:8], "-", "")
+	must := func(err error) {
+		t.Helper()
+		if err != nil {
+			t.Fatalf("setup: %v", err)
+		}
+	}
+	_, err = db.Exec(`INSERT INTO users (id, email, password_hash, name) VALUES ($1, $2, 'x', 'test')`,
+		userID, "prev-"+suffix+"@test.local")
+	must(err)
+	_, err = db.Exec(`INSERT INTO projects (id, name, owner_id, is_approved) VALUES ($1, $2, $3, true)`,
+		projectID, "prev-"+suffix, userID)
+	must(err)
+	_, err = db.Exec(`INSERT INTO environments (id, name, project_id) VALUES ($1, 'production', $2)`,
+		envID, projectID)
+	must(err)
+	for _, p := range [][3]interface{}{{srcID, "src-" + suffix, "running"}, {cloneID, "clone-" + suffix, "running"}} {
+		_, err = db.Exec(`INSERT INTO services (id, name, project_id, environment_id, service_type, source_type, status)
+			VALUES ($1, $2, $3, $4, 'web', 'image', $5)`,
+			p[0], p[1], projectID, envID, p[2])
+		must(err)
+	}
+	defer func() { _, _ = db.Exec(`DELETE FROM users WHERE id = $1`, userID) }()
+
+	must(q.CreatePreviewEnvironment(ctx, sqlcdb.CreatePreviewEnvironmentParams{
+		ID:               previewID,
+		ProjectID:        projectID,
+		ServiceID:        srcID,
+		PreviewServiceID: uuid.NullUUID{UUID: cloneID, Valid: true},
+		BranchName:       "feat-" + suffix,
+		Environment:      "preview-feat-" + suffix,
+		Status:           "building",
+		ExpiresAt:        time.Now().Add(-time.Hour), // already past TTL → sweepable
+	}))
+
+	// List + service join.
+	rows, err := q.ListPreviewEnvironmentsForProject(ctx, projectID)
+	if err != nil || len(rows) != 1 {
+		t.Fatalf("list: %v %d", err, len(rows))
+	}
+	if rows[0].ID != previewID || !rows[0].SvcID.Valid || rows[0].ServiceName.String != "src-"+suffix {
+		t.Fatalf("list row: %+v", rows[0])
+	}
+
+	// Access-check join: owner reads; a stranger does not.
+	if _, err := q.GetPreviewEnvironment(ctx, sqlcdb.GetPreviewEnvironmentParams{
+		ID: previewID, OwnerID: userID}); err != nil {
+		t.Fatalf("owner read: %v", err)
+	}
+	if _, err := q.GetPreviewEnvironment(ctx, sqlcdb.GetPreviewEnvironmentParams{
+		ID: previewID, OwnerID: uuid.New()}); err != nil {
+		t.Fatalf("approved project should be public-read: %v", err)
+	}
+
+	// Status sync folds clone's 'running' into the preview row.
+	if err := q.SyncPreviewStatuses(ctx); err != nil {
+		t.Fatalf("sync: %v", err)
+	}
+	var status string
+	if err := db.QueryRow(`SELECT status FROM preview_environments WHERE id = $1`, previewID).Scan(&status); err != nil {
+		t.Fatalf("read status: %v", err)
+	}
+	if status != "running" {
+		t.Fatalf("status after sync = %q, want running", status)
+	}
+
+	// TTL sweep picks it up (expired at insert), marks expired.
+	sweep, err := q.ListSweepablePreviews(ctx)
+	if err != nil {
+		t.Fatalf("sweep list: %v", err)
+	}
+	found := false
+	for _, s := range sweep {
+		if s.ID == previewID && s.PreviewServiceID.UUID == cloneID {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("sweepable list missing preview: %+v", sweep)
+	}
+	must(q.MarkPreviewEnvironmentStatus(ctx, sqlcdb.MarkPreviewEnvironmentStatusParams{Status: "expired", ID: previewID}))
+	sweep, _ = q.ListSweepablePreviews(ctx)
+	for _, s := range sweep {
+		if s.ID == previewID {
+			t.Fatal("expired preview still sweepable")
+		}
+	}
+
+	// Owner lookup and delete.
+	owner, err := q.GetPreviewEnvironmentOwner(ctx, previewID)
+	if err != nil || owner != userID {
+		t.Fatalf("owner: %v %v", owner, err)
+	}
+	must(q.DeletePreviewEnvironment(ctx, previewID))
+}

app/backend/internal/api/preview_environments.go

@@ -40,6 +40,68 @@ type PreviewEnvironment struct {
 	DeploymentID *uuid.UUID `json:"deployment_id,omitempty"`
 }
 
+// previewRowShape is the common column set the generated preview rows
+// carry — ListPreviewEnvironmentsForProjectRow and GetPreviewEnvironmentRow
+// share it.
+type previewRowShape struct {
+	ID               uuid.UUID
+	ProjectID        uuid.UUID
+	ServiceID        uuid.UUID
+	PreviewServiceID uuid.NullUUID
+	BranchName       string
+	PrNumber         sql.NullInt32
+	Environment      string
+	Status           string
+	Url              sql.NullString
+	ExpiresAt        time.Time
+	CreatedAt        sql.NullTime
+	UpdatedAt        sql.NullTime
+	SvcID            uuid.NullUUID
+	ServiceName      sql.NullString
+	ServiceType      sql.NullString
+}
+
+func previewFromRow(r previewRowShape) PreviewEnvironment {
+	env := PreviewEnvironment{
+		ID:          r.ID,
+		ProjectID:   r.ProjectID,
+		ServiceID:   r.ServiceID,
+		BranchName:  r.BranchName,
+		Environment: r.Environment,
+		Status:      r.Status,
+		URL:         r.Url.String,
+		CreatedAt:   r.CreatedAt.Time,
+		UpdatedAt:   r.UpdatedAt.Time,
+	}
+	if r.PreviewServiceID.Valid {
+		id := r.PreviewServiceID.UUID
+		env.PreviewServiceID = &id
+	}
+	if r.PrNumber.Valid {
+		n := int(r.PrNumber.Int32)
+		env.PRNumber = &n
+	}
+	if !r.ExpiresAt.IsZero() {
+		t := r.ExpiresAt
+		env.ExpiresAt = &t
+	}
+	if r.SvcID.Valid {
+		env.Service = &Service{
+			ID:   r.SvcID.UUID,
+			Name: r.ServiceName.String,
+			Type: r.ServiceType.String,
+		}
+	}
+	return env
+}
+
+func prNumberSQL(n *int) sql.NullInt32 {
+	if n == nil {
+		return sql.NullInt32{}
+	}
+	return sql.NullInt32{Int32: int32(*n), Valid: true}
+}
+
 // CreatePreviewEnvironmentRequest represents a request to create a preview environment
 type CreatePreviewEnvironmentRequest struct {
 	ProjectID  uuid.UUID `json:"project_id"`
@@ -86,51 +148,21 @@ func handleGetPreviewEnvironments(c *gin.Context) {
 	}
 
 	// Get preview environments for the project with service info
-	rows, err := db.(*database.DB).Query(
-		`SELECT pe.id, pe.project_id, pe.service_id, pe.preview_service_id, pe.branch_name, pe.pr_number,
-				pe.environment, pe.status, pe.url, pe.expires_at, pe.created_at, pe.updated_at,
-				s.id as service_id, s.name as service_name, s.type as service_type
-			FROM preview_environments pe
-			LEFT JOIN services s ON pe.service_id = s.id
-			WHERE pe.project_id = $1
-			ORDER BY pe.created_at DESC`,
-		projectID,
-	)
+	rows, err := sqlcdb.New(db.(*database.DB).DB).ListPreviewEnvironmentsForProject(c.Request.Context(), projectID)
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to retrieve preview environments"})
 		return
 	}
-	defer rows.Close()
 
-	var environments []PreviewEnvironment
-	for rows.Next() {
-		var env PreviewEnvironment
-		var serviceID sql.NullString
-		var serviceName sql.NullString
-		var serviceType sql.NullString
-
-		err := rows.Scan(
-			&env.ID, &env.ProjectID, &env.ServiceID, &env.PreviewServiceID, &env.BranchName, &env.PRNumber,
-			&env.Environment, &env.Status, &env.URL, &env.ExpiresAt, &env.CreatedAt, &env.UpdatedAt,
-			&serviceID, &serviceName, &serviceType,
-		)
-		if err != nil {
-			c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to scan preview environment"})
-			return
-		}
-
-		if serviceID.Valid {
-			parsedServiceID, parseErr := uuid.Parse(serviceID.String)
-			if parseErr == nil {
-				env.Service = &Service{
-					ID:   parsedServiceID,
-					Name: serviceName.String,
-					Type: serviceType.String,
-				}
-			}
-		}
-
-		environments = append(environments, env)
+	environments := make([]PreviewEnvironment, 0, len(rows))
+	for _, r := range rows {
+		environments = append(environments, previewFromRow(previewRowShape{
+			ID: r.ID, ProjectID: r.ProjectID, ServiceID: r.ServiceID,
+			PreviewServiceID: r.PreviewServiceID, BranchName: r.BranchName,
+			PrNumber: r.PrNumber, Environment: r.Environment, Status: r.Status,
+			Url: r.Url, ExpiresAt: r.ExpiresAt, CreatedAt: r.CreatedAt, UpdatedAt: r.UpdatedAt,
+			SvcID: r.SvcID, ServiceName: r.ServiceName, ServiceType: r.ServiceType,
+		}))
 	}
 
 	c.JSON(http.StatusOK, gin.H{"preview_environments": environments})
@@ -171,48 +203,37 @@ func handleCreatePreviewEnvironment(c *gin.Context) {
 		return
 	}
 
-	// Check if project exists and user has access
-	var project Project
-	err = db.(*database.DB).QueryRow(
-		"SELECT id, name, owner_id FROM projects WHERE id = $1",
-		req.ProjectID,
-	).Scan(&project.ID, &project.Name, &project.OwnerID)
+	ctx := c.Request.Context()
+	q := sqlcdb.New(db.(*database.DB).DB)
 
+	// Check if project exists and user has access
+	project, err := q.GetProjectBrief(ctx, req.ProjectID)
 	if err != nil {
 		c.JSON(http.StatusNotFound, gin.H{"error": "Project not found"})
 		return
 	}
 
 	// Check if user owns the project
-	if project.OwnerID != userID.(string) && !contextIsAdmin(c) {
+	if project.OwnerID.String() != userID.(string) && !contextIsAdmin(c) {
 		c.JSON(http.StatusForbidden, gin.H{"error": "Access denied"})
 		return
 	}
 
 	// Check if service exists and belongs to the project
-	var service Service
-	err = db.(*database.DB).QueryRow(
-		"SELECT id, name, COALESCE(type, service_type, '') FROM services WHERE id = $1 AND project_id = $2",
-		req.ServiceID, req.ProjectID,
-	).Scan(&service.ID, &service.Name, &service.Type)
-
+	service, err := q.GetServiceTypeBrief(ctx, sqlcdb.GetServiceTypeBriefParams{
+		ID: req.ServiceID, ProjectID: req.ProjectID})
 	if err != nil {
 		c.JSON(http.StatusNotFound, gin.H{"error": "Service not found or doesn't belong to this project"})
 		return
 	}
 
 	// Check if preview environment already exists for this branch and service
-	var count int
-	err = db.(*database.DB).QueryRow(
-		"SELECT COUNT(*) FROM preview_environments WHERE service_id = $1 AND branch_name = $2 AND status NOT IN ('expired', 'stopped')",
-		req.ServiceID, req.BranchName,
-	).Scan(&count)
-
+	count, err := q.CountActivePreviewsForBranch(ctx, sqlcdb.CountActivePreviewsForBranchParams{
+		ServiceID: req.ServiceID, BranchName: req.BranchName})
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to check existing preview environment"})
 		return
 	}
-
 	if count > 0 {
 		c.JSON(http.StatusConflict, gin.H{"error": "Preview environment already exists for this branch and service"})
 		return
@@ -237,29 +258,23 @@ func handleCreatePreviewEnvironment(c *gin.Context) {
 
 	// The clone's branch override is what makes it a preview — everything
 	// else (env vars, volumes, builder, resources) stays identical.
-	if _, err := db.(*database.DB).Exec(
-		`UPDATE services SET git_branch = $1, domain = '', updated_at = NOW() WHERE id = $2`,
-		req.BranchName, cloneID,
-	); err != nil {
-		_, _ = db.(*database.DB).Exec(`DELETE FROM services WHERE id = $1`, cloneID)
+	if err := q.UpdateServicePreviewBranch(ctx, sqlcdb.UpdateServicePreviewBranchParams{
+		GitBranch: sql.NullString{String: req.BranchName, Valid: true}, ID: cloneID}); err != nil {
+		_ = q.DeleteServiceByID(ctx, cloneID)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to configure preview service"})
 		return
 	}
 	// Cloned service_domains would collide with the parent's Traefik
 	// router — previews get their own hostname or none.
-	if _, err := db.(*database.DB).Exec(
-		`DELETE FROM service_domains WHERE service_id = $1`, cloneID,
-	); err != nil {
-		_, _ = db.(*database.DB).Exec(`DELETE FROM services WHERE id = $1`, cloneID)
+	if err := q.DeleteAllServiceDomains(ctx, cloneID); err != nil {
+		_ = q.DeleteServiceByID(ctx, cloneID)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to configure preview domains"})
 		return
 	}
 	previewHost := resolvePreviewHost(db.(*database.DB), cloneID, envName)
 	if previewHost != "" {
-		_, _ = db.(*database.DB).Exec(
-			`INSERT INTO service_domains (service_id, domain, is_default, cert_type) VALUES ($1, $2, true, 'tls')`,
-			cloneID, previewHost,
-		)
+		_ = q.CreatePreviewDomain(ctx, sqlcdb.CreatePreviewDomainParams{
+			ServiceID: cloneID, Domain: previewHost})
 	}
 
 	expiresAt := time.Now().Add(time.Duration(ttlHours) * time.Hour)
@@ -279,30 +294,36 @@ func handleCreatePreviewEnvironment(c *gin.Context) {
 		env.URL = "https://" + previewHost
 	}
 
-	_, err = db.(*database.DB).Exec(
-		`INSERT INTO preview_environments
-			(id, project_id, service_id, preview_service_id, branch_name, pr_number, environment,
-			 status, url, expires_at, created_at, updated_at)
-			VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)`,
-		env.ID, env.ProjectID, env.ServiceID, cloneID, env.BranchName, env.PRNumber,
-		env.Environment, env.Status, env.URL, env.ExpiresAt, env.CreatedAt, env.UpdatedAt,
-	)
+	err = q.CreatePreviewEnvironment(ctx, sqlcdb.CreatePreviewEnvironmentParams{
+		ID:               env.ID,
+		ProjectID:        env.ProjectID,
+		ServiceID:        env.ServiceID,
+		PreviewServiceID: uuid.NullUUID{UUID: cloneID, Valid: true},
+		BranchName:       env.BranchName,
+		PrNumber:         prNumberSQL(env.PRNumber),
+		Environment:      env.Environment,
+		Status:           env.Status,
+		Url:              sql.NullString{String: env.URL, Valid: env.URL != ""},
+		ExpiresAt:        *env.ExpiresAt,
+		CreatedAt:        sql.NullTime{Time: env.CreatedAt, Valid: true},
+		UpdatedAt:        sql.NullTime{Time: env.UpdatedAt, Valid: true},
+	})
 	if err != nil {
-		_, _ = db.(*database.DB).Exec(`DELETE FROM services WHERE id = $1`, cloneID)
+		_ = q.DeleteServiceByID(ctx, cloneID)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to create preview environment"})
 		return
 	}
 
 	deploymentID := uuid.New()
-	_, err = db.(*database.DB).Exec(
-		`INSERT INTO deployments
-			(id, service_id, version, commit_hash, status, created_at, updated_at)
-		 VALUES ($1, $2, $3, $4, 'pending', NOW(), NOW())`,
-		deploymentID, cloneID, "preview-"+env.Environment, req.BranchName,
-	)
+	err = q.InsertPendingDeployment(ctx, sqlcdb.InsertPendingDeploymentParams{
+		ID:         deploymentID,
+		ServiceID:  cloneID,
+		Version:    "preview-" + env.Environment,
+		CommitHash: sql.NullString{String: req.BranchName, Valid: true},
+	})
 	if err != nil {
-		_, _ = db.(*database.DB).Exec(`DELETE FROM preview_environments WHERE id = $1`, env.ID)
-		_, _ = db.(*database.DB).Exec(`DELETE FROM services WHERE id = $1`, cloneID)
+		_ = q.DeletePreviewEnvironment(ctx, env.ID)
+		_ = q.DeleteServiceByID(ctx, cloneID)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to provision preview deployment"})
 		return
 	}
@@ -349,43 +370,20 @@ func handleGetPreviewEnvironment(c *gin.Context) {
 
 	// Public when the parent project is approved; otherwise owner/member/admin.
 	userID := optionalUserUUID(c)
-	var env PreviewEnvironment
-	var serviceID sql.NullString
-	var serviceName sql.NullString
-	var serviceType sql.NullString
-	err = db.(*database.DB).QueryRow(
-		`SELECT pe.id, pe.project_id, pe.service_id, pe.preview_service_id, pe.branch_name, pe.pr_number,
-				pe.environment, pe.status, pe.url, pe.expires_at, pe.created_at, pe.updated_at,
-				s.id as service_id, s.name as service_name, s.type as service_type
-			FROM preview_environments pe
-			LEFT JOIN services s ON pe.service_id = s.id
-			JOIN projects p ON pe.project_id = p.id
-			WHERE pe.id = $1 AND (p.is_approved OR p.owner_id = $2 OR $3::bool
-				OR EXISTS (SELECT 1 FROM project_members pm WHERE pm.project_id = p.id AND pm.user_id = $2))`,
-		envID, userID, contextIsAdmin(c),
-	).Scan(
-		&env.ID, &env.ProjectID, &env.ServiceID, &env.PreviewServiceID, &env.BranchName, &env.PRNumber,
-		&env.Environment, &env.Status, &env.URL, &env.ExpiresAt, &env.CreatedAt, &env.UpdatedAt,
-		&serviceID, &serviceName, &serviceType,
-	)
-
+	r, err := sqlcdb.New(db.(*database.DB).DB).GetPreviewEnvironment(
+		c.Request.Context(), sqlcdb.GetPreviewEnvironmentParams{
+			ID: envID, OwnerID: userID, Column3: contextIsAdmin(c)})
 	if err != nil {
 		c.JSON(http.StatusNotFound, gin.H{"error": "Preview environment not found"})
 		return
 	}
-
-	// Populate service info if available
-	if serviceID.Valid {
-		parsedServiceID, parseErr := uuid.Parse(serviceID.String)
-		if parseErr == nil {
-			env.Service = &Service{
-				ID:   parsedServiceID,
-				Name: serviceName.String,
-				Type: serviceType.String,
-			}
-		}
-	}
-
+	env := previewFromRow(previewRowShape{
+		ID: r.ID, ProjectID: r.ProjectID, ServiceID: r.ServiceID,
+		PreviewServiceID: r.PreviewServiceID, BranchName: r.BranchName,
+		PrNumber: r.PrNumber, Environment: r.Environment, Status: r.Status,
+		Url: r.Url, ExpiresAt: r.ExpiresAt, CreatedAt: r.CreatedAt, UpdatedAt: r.UpdatedAt,
+		SvcID: r.SvcID, ServiceName: r.ServiceName, ServiceType: r.ServiceType,
+	})
 	c.JSON(http.StatusOK, gin.H{"preview_environment": env})
 }
 
@@ -418,24 +416,21 @@ func handleUpdatePreviewEnvironment(c *gin.Context) {
 	}
 
 	// Check if preview environment exists and user has access
-	var existingEnv PreviewEnvironment
-	err = db.(*database.DB).QueryRow(
-		`SELECT pe.id, pe.project_id, pe.service_id, pe.branch_name, pe.pr_number, 
-				pe.environment, pe.status, pe.url, pe.expires_at, pe.created_at, pe.updated_at
-			FROM preview_environments pe
-			JOIN projects p ON pe.project_id = p.id
-			WHERE pe.id = $1 AND (p.owner_id = $2 OR $3::bool)`,
-		envID, userID, contextIsAdmin(c),
-	).Scan(
-		&existingEnv.ID, &existingEnv.ProjectID, &existingEnv.ServiceID, &existingEnv.BranchName,
-		&existingEnv.PRNumber, &existingEnv.Environment, &existingEnv.Status, &existingEnv.URL,
-		&existingEnv.ExpiresAt, &existingEnv.CreatedAt, &existingEnv.UpdatedAt,
-	)
-
+	uid, _ := uuid.Parse(fmt.Sprint(userID))
+	q := sqlcdb.New(db.(*database.DB).DB)
+	r, err := q.GetPreviewEnvironmentForWrite(
+		c.Request.Context(), sqlcdb.GetPreviewEnvironmentForWriteParams{
+			ID: envID, OwnerID: uid, Column3: contextIsAdmin(c)})
 	if err != nil {
 		c.JSON(http.StatusNotFound, gin.H{"error": "Preview environment not found"})
 		return
 	}
+	existingEnv := previewFromRow(previewRowShape{
+		ID: r.ID, ProjectID: r.ProjectID, ServiceID: r.ServiceID,
+		BranchName: r.BranchName, PrNumber: r.PrNumber, Environment: r.Environment,
+		Status: r.Status, Url: r.Url, ExpiresAt: r.ExpiresAt,
+		CreatedAt: r.CreatedAt, UpdatedAt: r.UpdatedAt,
+	})
 
 	// Update fields if provided
 	if req.Status != "" {
@@ -455,12 +450,17 @@ func handleUpdatePreviewEnvironment(c *gin.Context) {
 	existingEnv.UpdatedAt = time.Now()
 
 	// Update preview environment in database
-	_, err = db.(*database.DB).Exec(
-		`UPDATE preview_environments 
-			SET status = $1, url = $2, expires_at = $3, updated_at = $4
-			WHERE id = $5`,
-		existingEnv.Status, existingEnv.URL, existingEnv.ExpiresAt, existingEnv.UpdatedAt, existingEnv.ID,
-	)
+	expiresAt := time.Time{}
+	if existingEnv.ExpiresAt != nil {
+		expiresAt = *existingEnv.ExpiresAt
+	}
+	err = q.UpdatePreviewEnvironment(c.Request.Context(), sqlcdb.UpdatePreviewEnvironmentParams{
+		Status:    existingEnv.Status,
+		Url:       sql.NullString{String: existingEnv.URL, Valid: existingEnv.URL != ""},
+		ExpiresAt: expiresAt,
+		UpdatedAt: sql.NullTime{Time: existingEnv.UpdatedAt, Valid: true},
+		ID:        existingEnv.ID,
+	})
 
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to update preview environment"})
@@ -492,46 +492,34 @@ func handleDeletePreviewEnvironment(c *gin.Context) {
 		return
 	}
 
-	// Check if preview environment exists and user has access
-	var projectOwnerID string
-	err = db.(*database.DB).QueryRow(
-		`SELECT p.owner_id 
-			FROM preview_environments pe
-			JOIN projects p ON pe.project_id = p.id
-			WHERE pe.id = $1`,
-		envID,
-	).Scan(&projectOwnerID)
+	ctx := c.Request.Context()
+	q := sqlcdb.New(db.(*database.DB).DB)
 
+	// Check if preview environment exists and user has access
+	projectOwnerID, err := q.GetPreviewEnvironmentOwner(ctx, envID)
 	if err != nil {
 		c.JSON(http.StatusNotFound, gin.H{"error": "Preview environment not found"})
 		return
 	}
 
 	// Check if user owns the project
-	if projectOwnerID != userID.(string) && !contextIsAdmin(c) {
+	if projectOwnerID.String() != userID.(string) && !contextIsAdmin(c) {
 		c.JSON(http.StatusForbidden, gin.H{"error": "Access denied"})
 		return
 	}
 
 	// Tear down the clone's runtime and row — the preview is the clone.
-	var cloneID *uuid.UUID
-	_ = db.(*database.DB).QueryRow(
-		`SELECT preview_service_id FROM preview_environments WHERE id = $1`, envID,
-	).Scan(&cloneID)
-	if cloneID != nil {
+	if cloneID, err := q.GetPreviewServiceID(ctx, envID); err == nil && cloneID.Valid {
 		if engineValue, exists := c.Get("deployment_engine"); exists && engineValue != nil {
 			if engine, ok := engineValue.(*deployment.DeploymentEngine); ok {
-				removeServiceRuntime(c.Request.Context(), db.(*database.DB), engine, *cloneID)
+				removeServiceRuntime(ctx, db.(*database.DB), engine, cloneID.UUID)
 			}
 		}
-		_, _ = db.(*database.DB).Exec(`DELETE FROM services WHERE id = $1`, *cloneID)
+		_ = q.DeleteServiceByID(ctx, cloneID.UUID)
 	}
 
 	// Delete preview environment
-	_, err = db.(*database.DB).Exec(
-		"DELETE FROM preview_environments WHERE id = $1",
-		envID,
-	)
+	err = q.DeletePreviewEnvironment(ctx, envID)
 
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to delete preview environment"})
@@ -569,22 +557,30 @@ func handlePromotePreviewEnvironment(c *gin.Context) {
 		return
 	}
 
-	// Get preview environment details
-	var env PreviewEnvironment
-	err = db.(*database.DB).QueryRow(
-		`SELECT pe.id, pe.project_id, pe.service_id, pe.preview_service_id, pe.branch_name, pe.environment, pe.status
-			FROM preview_environments pe
-			JOIN projects p ON pe.project_id = p.id
-			WHERE pe.id = $1 AND (p.owner_id = $2 OR $3::bool)`,
-		envID, userID, contextIsAdmin(c),
-	).Scan(
-		&env.ID, &env.ProjectID, &env.ServiceID, &env.PreviewServiceID, &env.BranchName, &env.Environment, &env.Status,
-	)
+	ctx := c.Request.Context()
+	q := sqlcdb.New(db.(*database.DB).DB)
 
+	// Get preview environment details
+	uid, _ := uuid.Parse(fmt.Sprint(userID))
+	r, err := q.GetPreviewEnvironmentForPromote(
+		ctx, sqlcdb.GetPreviewEnvironmentForPromoteParams{
+			ID: envID, OwnerID: uid, Column3: contextIsAdmin(c)})
 	if err != nil {
 		c.JSON(http.StatusNotFound, gin.H{"error": "Preview environment not found"})
 		return
 	}
+	env := PreviewEnvironment{
+		ID:          r.ID,
+		ProjectID:   r.ProjectID,
+		ServiceID:   r.ServiceID,
+		BranchName:  r.BranchName,
+		Environment: r.Environment,
+		Status:      r.Status,
+	}
+	if r.PreviewServiceID.Valid {
+		id := r.PreviewServiceID.UUID
+		env.PreviewServiceID = &id
+	}
 
 	// Check if preview environment is in a state that can be promoted
 	if env.Status != "running" {
@@ -596,11 +592,12 @@ func handlePromotePreviewEnvironment(c *gin.Context) {
 	// branch onto its own deployment track.
 	deploymentID := uuid.New()
 	promotionVersion := fmt.Sprintf("promote-%s-%d", strings.ReplaceAll(env.BranchName, "/", "-"), time.Now().Unix())
-	_, err = db.(*database.DB).Exec(
-		`INSERT INTO deployments (id, service_id, version, commit_hash, status, created_at, updated_at)
-		 VALUES ($1, $2, $3, $4, 'pending', NOW(), NOW())`,
-		deploymentID, env.ServiceID, promotionVersion, env.BranchName,
-	)
+	err = q.InsertPendingDeployment(ctx, sqlcdb.InsertPendingDeploymentParams{
+		ID:         deploymentID,
+		ServiceID:  env.ServiceID,
+		Version:    promotionVersion,
+		CommitHash: sql.NullString{String: env.BranchName, Valid: true},
+	})
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to create promotion deployment"})
 		return
@@ -628,18 +625,14 @@ func handlePromotePreviewEnvironment(c *gin.Context) {
 	if env.PreviewServiceID != nil {
 		if engineValue, exists := c.Get("deployment_engine"); exists && engineValue != nil {
 			if engine, ok := engineValue.(*deployment.DeploymentEngine); ok {
-				removeServiceRuntime(c.Request.Context(), db.(*database.DB), engine, *env.PreviewServiceID)
+				removeServiceRuntime(ctx, db.(*database.DB), engine, *env.PreviewServiceID)
 			}
 		}
-		_, _ = db.(*database.DB).Exec(`DELETE FROM services WHERE id = $1`, *env.PreviewServiceID)
+		_ = q.DeleteServiceByID(ctx, *env.PreviewServiceID)
 	}
 
-	if _, err := db.(*database.DB).Exec(
-		`UPDATE preview_environments
-		 SET status = 'stopped', updated_at = NOW()
-		 WHERE id = $1`,
-		env.ID,
-	); err != nil {
+	if err := q.MarkPreviewEnvironmentStatus(ctx, sqlcdb.MarkPreviewEnvironmentStatusParams{
+		Status: "stopped", ID: env.ID}); err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to update preview environment status"})
 		return
 	}
@@ -682,28 +675,27 @@ func handleCleanupExpiredPreviewEnvironments(c *gin.Context) {
 		return
 	}
 
+	ctx := c.Request.Context()
+	q := sqlcdb.New(db.(*database.DB).DB)
+	uid, _ := uuid.Parse(fmt.Sprint(userID))
+
 	// Find expired preview environments for user's projects
-	rows, err := db.(*database.DB).Query(
-		`SELECT pe.id, pe.project_id, pe.service_id, pe.preview_service_id, pe.branch_name, pe.environment
-			FROM preview_environments pe
-			JOIN projects p ON pe.project_id = p.id
-			WHERE (p.owner_id = $1 OR $2::bool) AND pe.expires_at < NOW() AND pe.status != 'expired'`,
-		userID, contextIsAdmin(c),
-	)
+	rows, err := q.ListExpiredPreviewsForUser(ctx, sqlcdb.ListExpiredPreviewsForUserParams{
+		OwnerID: uid, Column2: contextIsAdmin(c)})
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to find expired preview environments"})
 		return
 	}
-	defer rows.Close()
 
-	var expiredEnvs []PreviewEnvironment
-	for rows.Next() {
-		var env PreviewEnvironment
-		err := rows.Scan(
-			&env.ID, &env.ProjectID, &env.ServiceID, &env.PreviewServiceID, &env.BranchName, &env.Environment,
-		)
-		if err != nil {
-			continue
+	expiredEnvs := make([]PreviewEnvironment, 0, len(rows))
+	for _, r := range rows {
+		env := PreviewEnvironment{
+			ID: r.ID, ProjectID: r.ProjectID, ServiceID: r.ServiceID,
+			BranchName: r.BranchName, Environment: r.Environment,
+		}
+		if r.PreviewServiceID.Valid {
+			id := r.PreviewServiceID.UUID
+			env.PreviewServiceID = &id
 		}
 		expiredEnvs = append(expiredEnvs, env)
 	}
@@ -711,20 +703,17 @@ func handleCleanupExpiredPreviewEnvironments(c *gin.Context) {
 	// Mark expired environments as expired and tear down their clones
 	cleanupCount := 0
 	for _, env := range expiredEnvs {
-		_, err := db.(*database.DB).Exec(
-			"UPDATE preview_environments SET status = 'expired', updated_at = NOW() WHERE id = $1",
-			env.ID,
-		)
-		if err != nil {
+		if err := q.MarkPreviewEnvironmentStatus(ctx, sqlcdb.MarkPreviewEnvironmentStatusParams{
+			Status: "expired", ID: env.ID}); err != nil {
 			continue
 		}
 		if env.PreviewServiceID != nil {
 			if engineValue, exists := c.Get("deployment_engine"); exists && engineValue != nil {
 				if engine, ok := engineValue.(*deployment.DeploymentEngine); ok {
-					removeServiceRuntime(c.Request.Context(), db.(*database.DB), engine, *env.PreviewServiceID)
+					removeServiceRuntime(ctx, db.(*database.DB), engine, *env.PreviewServiceID)
 				}
 			}
-			_, _ = db.(*database.DB).Exec(`DELETE FROM services WHERE id = $1`, *env.PreviewServiceID)
+			_ = q.DeleteServiceByID(ctx, *env.PreviewServiceID)
 		}
 		cleanupCount++
 	}
@@ -754,15 +743,13 @@ func resolvePreviewHost(db *database.DB, cloneID uuid.UUID, envName string) stri
 	if label == "" {
 		return ""
 	}
-	var nodeID sql.NullString
-	var spread bool
-	if err := db.QueryRow(
-		`SELECT node_id, COALESCE(spread, false) FROM services WHERE id = $1`, cloneID,
-	).Scan(&nodeID, &spread); err != nil {
-		return ""
-	}
 	q := sqlcdb.New(db.DB)
 	ctx := context.Background()
+	brief, err := q.GetServicePlacementBrief(ctx, cloneID)
+	if err != nil {
+		return ""
+	}
+	nodeID, spread := brief.NodeID, brief.Spread
 	var base string
 	switch {
 	case nodeID.Valid && nodeID.String != "":
@@ -789,30 +776,22 @@ func resolvePreviewHost(db *database.DB, cloneID uuid.UUID, envName string) stri
 // loadServiceForDeploy hydrates the Service fields runDeploymentAndSync
 // needs — mirrors the loader in handleDeployService.
 func loadServiceForDeploy(db *database.DB, serviceID uuid.UUID) (Service, error) {
-	var service Service
-	err := db.QueryRow(
-		`SELECT s.id, s.project_id, s.name, s.type, s.status, s.image, s.command,
-		        s.environment, s.git_repo, s.git_branch, s.build_path, s.cpu, s.memory,
-		        COALESCE(s.replicas, 1), COALESCE(s.port, 0),
-		        COALESCE(s.domain, ''), COALESCE(s.healthcheck_path, ''),
-		        COALESCE(s.restart_policy, 'unless-stopped'),
-		        COALESCE(s.builder, 'auto'), COALESCE(s.cpu_reserve, ''),
-		        COALESCE(s.memory_reserve, ''), COALESCE(s.static_build_cmd, ''),
-		        COALESCE(s.static_dir, ''),
-		        s.created_at, s.updated_at
-		 FROM services s
-		 WHERE s.id = $1`,
-		serviceID,
-	).Scan(
-		&service.ID, &service.ProjectID, &service.Name, &service.Type, &service.Status,
-		&service.Image, &service.Command, &service.Environment, &service.GitRepo,
-		&service.GitBranch, &service.BuildPath, &service.CPU, &service.Memory,
-		&service.Replicas, &service.Port, &service.Domain, &service.HealthCheckPath,
-		&service.RestartPolicy, &service.Builder, &service.CPUReserve,
-		&service.MemoryReserve, &service.StaticBuildCmd, &service.StaticDir,
-		&service.CreatedAt, &service.UpdatedAt,
-	)
-	return service, err
+	r, err := sqlcdb.New(db.DB).GetServiceForDeploy(context.Background(), serviceID)
+	if err != nil {
+		return Service{}, err
+	}
+	return Service{
+		ID: r.ID, ProjectID: r.ProjectID, Name: r.Name, Type: r.Type.String,
+		Status: r.Status.String, Image: r.Image.String, Command: r.Command.String,
+		Environment: r.Environment.String, GitRepo: r.GitRepo.String,
+		GitBranch: r.GitBranch.String, BuildPath: r.BuildPath.String,
+		CPU: r.Cpu.String, Memory: r.Memory.String,
+		Replicas: int(r.Replicas), Port: int(r.Port), Domain: r.Domain,
+		HealthCheckPath: r.HealthcheckPath, RestartPolicy: r.RestartPolicy,
+		Builder: r.Builder, CPUReserve: r.CpuReserve, MemoryReserve: r.MemoryReserve,
+		StaticBuildCmd: r.StaticBuildCmd, StaticDir: r.StaticDir,
+		CreatedAt: r.CreatedAt.Time, UpdatedAt: r.UpdatedAt.Time,
+	}, nil
 }
 
 // StartPreviewSweeper expires preview environments past their TTL — tears
@@ -838,54 +817,27 @@ func StartPreviewSweeper(ctx context.Context, db *database.DB, engine *deploymen
 
 // sweepExpiredPreviews retires previews whose TTL elapsed.
 func sweepExpiredPreviews(ctx context.Context, db *database.DB, engine *deployment.DeploymentEngine) {
-	rows, err := db.QueryContext(ctx,
-		`SELECT id, preview_service_id FROM preview_environments
-		 WHERE expires_at < NOW() AND status NOT IN ('expired', 'stopped')`)
+	q := sqlcdb.New(db.DB)
+	rows, err := q.ListSweepablePreviews(ctx)
 	if err != nil {
 		return
 	}
 	var ids []uuid.UUID
-	var clones []uuid.UUID
-	for rows.Next() {
-		var id uuid.UUID
-		var cloneID *uuid.UUID
-		if err := rows.Scan(&id, &cloneID); err == nil {
-			ids = append(ids, id)
-			if cloneID != nil {
-				clones = append(clones, *cloneID)
+	for _, r := range rows {
+		ids = append(ids, r.ID)
+		if r.PreviewServiceID.Valid {
+			removeServiceRuntime(ctx, db, engine, r.PreviewServiceID.UUID)
+			_ = q.DeleteServiceByID(ctx, r.PreviewServiceID.UUID)
 		}
 	}
-	}
-	rows.Close()
-	for _, cloneID := range clones {
-		removeServiceRuntime(ctx, db, engine, cloneID)
-		_, _ = db.ExecContext(ctx, `DELETE FROM services WHERE id = $1`, cloneID)
-	}
 	for _, id := range ids {
-		_, _ = db.ExecContext(ctx,
-			`UPDATE preview_environments SET status = 'expired', updated_at = NOW() WHERE id = $1`, id)
+		_ = q.MarkPreviewEnvironmentStatus(ctx, sqlcdb.MarkPreviewEnvironmentStatusParams{
+			Status: "expired", ID: id})
 	}
 }
 
 // syncPreviewStatuses folds the clone's live service status into the
 // preview row so list/detail endpoints reflect the real deploy state.
 func syncPreviewStatuses(ctx context.Context, db *database.DB) {
-	_, _ = db.ExecContext(ctx, `
-		UPDATE preview_environments pe
-		SET status = derived.st, updated_at = NOW()
-		FROM (
-			SELECT pe2.id,
-				CASE
-					WHEN s.status IN ('running', 'deployed') THEN 'running'
-					WHEN s.status IN ('failed', 'error') THEN 'failed'
-					WHEN s.status IN ('building', 'deploying', 'queued', 'pending', 'cloning') THEN 'building'
-					ELSE pe2.status
-				END AS st
-			FROM preview_environments pe2
-			JOIN services s ON pe2.preview_service_id = s.id
-		) derived
-		WHERE pe.id = derived.id
-		  AND pe.status IN ('building', 'running', 'failed')
-		  AND pe.status <> derived.st
-	`)
+	_ = sqlcdb.New(db.DB).SyncPreviewStatuses(ctx)
 }

app/backend/internal/api/routes.go

@@ -286,6 +286,7 @@ func SetupRoutes(router *gin.Engine, db *database.DB, redis *database.Redis, cfg
 			public.POST("/auth/register", handleRegister)
 			public.GET("/maintenance", handleMaintenancePage)
 			public.GET("/branding", handleGetBranding)
+			public.GET("/setup/status", handleSetupStatus)
 
 			// Invite accept flow — validates the link, then registers
 			// even while public signup is closed.
@@ -355,6 +356,7 @@ func SetupRoutes(router *gin.Engine, db *database.DB, redis *database.Redis, cfg
 		{
 			authed.GET("/user/profile", handleGetProfile)
 			authed.PUT("/user/profile", handleUpdateProfile)
+			authed.POST("/setup/complete", handleSetupComplete)
 
 			// Personal access tokens for CLI/MCP/agent auth.
 			authed.GET("/user/tokens", handleListUserTokens)

app/backend/internal/api/service_ops.go

@@ -1,11 +1,14 @@
 package api
 
 import (
+	"context"
+	"database/sql"
 	"net/http"
 	"strings"
 	"time"
 
 	"containr/internal/database"
+	"containr/internal/database/sqlcdb"
 
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
@@ -53,11 +56,8 @@ func handleCloneService(c *gin.Context) {
 	if name == "" {
 		name = source.Name + "-copy"
 	}
-	var count int
-	_ = db.(*database.DB).QueryRow(
-		`SELECT COUNT(*) FROM services WHERE project_id = $1 AND name = $2`,
-		targetProjectID, name,
-	).Scan(&count)
+	count, _ := sqlcdb.New(db.(*database.DB).DB).CountServicesByName(
+		c.Request.Context(), sqlcdb.CountServicesByNameParams{ProjectID: targetProjectID, Name: name})
 	if count > 0 {
 		c.JSON(http.StatusConflict, gin.H{"error": "Service name already exists in target project", "code": "CONFLICT"})
 		return
@@ -84,8 +84,11 @@ func handleCloneService(c *gin.Context) {
 // inherits the source's. Used by the clone endpoint and preview
 // environments, which additionally override git_branch and domains.
 func cloneServiceRow(db *database.DB, sourceID uuid.UUID, targetProjectID uuid.UUID, name, environment string) (uuid.UUID, error) {
-	var sourceEnv string
-	if err := db.QueryRow(`SELECT COALESCE(environment, '') FROM services WHERE id = $1`, sourceID).Scan(&sourceEnv); err != nil {
+	ctx := context.Background()
+	q := sqlcdb.New(db.DB)
+
+	sourceEnv, err := q.GetServiceEnvironment(ctx, sourceID)
+	if err != nil {
 		return uuid.Nil, err
 	}
 	if environment == "" {
@@ -102,46 +105,31 @@ func cloneServiceRow(db *database.DB, sourceID uuid.UUID, targetProjectID uuid.U
 	maintenance, basicAuth := serviceAccess(db, sourceID)
 	newID := uuid.New()
 	now := time.Now()
-	// string() so pq sends text — []byte would go as bytea and fail ::jsonb.
-	volumesJSON := string(loadServiceVolumesJSON(db, sourceID))
 
-	_, err = db.Exec(
-		`INSERT INTO services
-			(id, project_id, name, environment_id, service_type, source_type, source_url, image_name,
-				 build_command, start_command, type, status, image, command, environment,
-				 git_repo, git_branch, build_path, cpu, memory, replicas, port, domain,
-				 healthcheck_path, restart_policy, volumes, maintenance_mode, basic_auth_users,
-				 builder, cpu_reserve, memory_reserve, static_build_cmd, static_dir,
-				 created_at, updated_at)
-			SELECT $1, $2, $3, $4, service_type, source_type, source_url, image_name,
-				 build_command, start_command, type, 'stopped', image, command, $5,
-				 git_repo, git_branch, build_path, cpu, memory, replicas, port, domain,
-				 healthcheck_path, restart_policy, $6::jsonb, $7, $8,
-				 builder, cpu_reserve, memory_reserve, static_build_cmd, static_dir,
-				 $9, $9
-			FROM services WHERE id = $10`,
-		newID, targetProjectID, name, environmentID, environment, volumesJSON,
-		maintenance, basicAuth, now, sourceID,
-	)
+	err = q.CloneServiceRow(ctx, sqlcdb.CloneServiceRowParams{
+		ID:              newID,
+		ProjectID:       targetProjectID,
+		Name:            name,
+		EnvironmentID:   environmentID,
+		Environment:     sql.NullString{String: environment, Valid: true},
+		MaintenanceMode: maintenance,
+		BasicAuthUsers:  basicAuth,
+		CreatedAt:       sql.NullTime{Time: now, Valid: true},
+		ID_2:            sourceID,
+	})
 	if err != nil {
 		return uuid.Nil, err
 	}
 
-	if _, err := db.Exec(
-		`INSERT INTO service_domains (service_id, domain, is_default, cert_type)
-		 SELECT $1, domain, is_default, cert_type FROM service_domains WHERE service_id = $2`,
-		newID, sourceID,
-	); err != nil {
-		_, _ = db.Exec(`DELETE FROM services WHERE id = $1`, newID)
+	if err := q.CloneServiceDomains(ctx, sqlcdb.CloneServiceDomainsParams{
+		ServiceID: newID, ServiceID_2: sourceID}); err != nil {
+		_ = q.DeleteServiceByID(ctx, newID)
 		return uuid.Nil, err
 	}
 	// Variable values are copied as stored — ciphertext stays ciphertext.
-	if _, err := db.Exec(
-		`INSERT INTO environment_variables (id, service_id, key, value, is_secret)
-		 SELECT gen_random_uuid(), $1, key, value, is_secret FROM environment_variables WHERE service_id = $2`,
-		newID, sourceID,
-	); err != nil {
-		_, _ = db.Exec(`DELETE FROM services WHERE id = $1`, newID)
+	if err := q.CloneServiceVariables(ctx, sqlcdb.CloneServiceVariablesParams{
+		ServiceID: newID, ServiceID_2: sourceID}); err != nil {
+		_ = q.DeleteServiceByID(ctx, newID)
 		return uuid.Nil, err
 	}
 	return newID, nil
@@ -187,11 +175,8 @@ func handleMoveService(c *gin.Context) {
 		return
 	}
 
-	var count int
-	_ = db.(*database.DB).QueryRow(
-		`SELECT COUNT(*) FROM services WHERE project_id = $1 AND name = $2`,
-		req.ProjectID, service.Name,
-	).Scan(&count)
+	count, _ := sqlcdb.New(db.(*database.DB).DB).CountServicesByName(
+		c.Request.Context(), sqlcdb.CountServicesByNameParams{ProjectID: req.ProjectID, Name: service.Name})
 	if count > 0 {
 		c.JSON(http.StatusConflict, gin.H{"error": "A service with this name already exists in the target project", "code": "CONFLICT"})
 		return
@@ -207,15 +192,18 @@ func handleMoveService(c *gin.Context) {
 		return
 	}
 
-	res, err := db.(*database.DB).Exec(
-		`UPDATE services SET project_id = $1, environment_id = $2, updated_at = $3 WHERE id = $4`,
-		req.ProjectID, environmentID, time.Now(), serviceID,
-	)
+	n, err := sqlcdb.New(db.(*database.DB).DB).MoveServiceProject(
+		c.Request.Context(), sqlcdb.MoveServiceProjectParams{
+			ProjectID:     req.ProjectID,
+			EnvironmentID: environmentID,
+			UpdatedAt:     sql.NullTime{Time: time.Now(), Valid: true},
+			ID:            serviceID,
+		})
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to move service"})
 		return
 	}
-	if n, _ := res.RowsAffected(); n == 0 {
+	if n == 0 {
 		c.JSON(http.StatusNotFound, gin.H{"error": "Service not found", "code": "NOT_FOUND"})
 		return
 	}
@@ -229,16 +217,10 @@ func ownsProject(db *database.DB, projectID uuid.UUID, userID string, isAdmin bo
 	if isAdmin {
 		return true
 	}
-	var owner string
-	err := db.QueryRow(`SELECT owner_id FROM projects WHERE id = $1`, projectID).Scan(&owner)
-	return err == nil && owner == userID
-}
-
-// loadServiceVolumesJSON returns the raw stored mounts for a verbatim copy.
-func loadServiceVolumesJSON(db *database.DB, serviceID uuid.UUID) []byte {
-	var raw []byte
-	if err := db.QueryRow(`SELECT volumes FROM services WHERE id = $1`, serviceID).Scan(&raw); err != nil || len(raw) == 0 {
-		return []byte("[]")
+	uid, err := uuid.Parse(userID)
+	if err != nil {
+		return false
 	}
-	return raw
+	owner, err := sqlcdb.New(db.DB).GetProjectOwner(context.Background(), projectID)
+	return err == nil && owner == uid
 }

app/backend/internal/api/setup.go

@@ -0,0 +1,78 @@
+package api
+
+// First-run setup wizard state. GET /setup/status is public so the web
+// shell can redirect fresh installs before a session exists; the flag
+// lives in app_settings so it survives restarts.
+
+import (
+	"net/http"
+	"strings"
+
+	"containr/internal/database"
+
+	"github.com/gin-gonic/gin"
+)
+
+const settingSetupCompleted = "setup_completed"
+
+// setupComplete resolves the flag. Installs that predate the wizard
+// (users + projects already exist) auto-complete — nobody who has been
+// running Containr for months should get a welcome screen.
+func setupComplete(db *database.DB, hasUsers bool) bool {
+	if strings.EqualFold(settingValue(db, settingSetupCompleted, "", ""), "true") {
+		return true
+	}
+	if !hasUsers {
+		return false
+	}
+	var projects int
+	if err := db.QueryRow(`SELECT COUNT(*) FROM projects`).Scan(&projects); err == nil && projects > 0 {
+		return true
+	}
+	return false
+}
+
+// GET /api/v1/setup/status — public: fresh installs hit it before any
+// session exists.
+func handleSetupStatus(c *gin.Context) {
+	db, ok := c.MustGet("db").(*database.DB)
+	if !ok {
+		respondError(c, http.StatusInternalServerError, "INTERNAL_ERROR", "Database connection not available")
+		return
+	}
+	count, err := countLocalUsers(db)
+	if err != nil {
+		respondError(c, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to inspect setup state")
+		return
+	}
+	hasUsers := count > 0
+	completed := setupComplete(db, hasUsers)
+	tunnelToken, _ := resolvedTunnelToken(db)
+	c.JSON(http.StatusOK, gin.H{
+		"has_users":       hasUsers,
+		"setup_completed": completed,
+		"needs_setup":     !completed,
+		"has_github_app":  githubAppConfigured(db),
+		"has_tunnel":      tunnelToken != "",
+		"signup_enabled":  signupEnabled(db),
+	})
+}
+
+// POST /api/v1/setup/complete — marks the wizard done. Open to any
+// authenticated user: the first account is the owner, and the flag only
+// suppresses a banner.
+func handleSetupComplete(c *gin.Context) {
+	if _, ok := requireAuthenticatedUserID(c); !ok {
+		return
+	}
+	db, ok := c.MustGet("db").(*database.DB)
+	if !ok {
+		respondError(c, http.StatusInternalServerError, "INTERNAL_ERROR", "Database connection not available")
+		return
+	}
+	if err := setSetting(db, settingSetupCompleted, "true", false); err != nil {
+		respondError(c, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to save setup state")
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "Setup completed"})
+}

app/backend/internal/api/webhooks_test.go

@@ -31,3 +31,33 @@ func TestWebhookEventMatches(t *testing.T) {
 		}
 	}
 }
+
+func TestValidWebhookURL(t *testing.T) {
+	cases := []struct {
+		name    string
+		url     string
+		wantErr bool
+	}{
+		{"https", "https://hooks.example.com/wh/abc", false},
+		{"http", "http://internal.lan:8080/notify", false},
+		{"whitespace trimmed", "  https://example.com/hook  ", false},
+		{"with query", "https://example.com/hook?token=x", false},
+		{"ftp rejected", "ftp://files.example.com/x", true},
+		{"no scheme", "example.com/hook", true},
+		{"bare scheme", "https://", true},
+		{"empty", "", true},
+		{"javascript rejected", "javascript:alert(1)", true},
+		{"host empty", "http:///path-only", true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validWebhookURL(tc.url)
+			if tc.wantErr && err == nil {
+				t.Errorf("validWebhookURL(%q) = nil, want error", tc.url)
+			}
+			if !tc.wantErr && err != nil {
+				t.Errorf("validWebhookURL(%q) = %v, want nil", tc.url, err)
+			}
+		})
+	}
+}

app/backend/internal/database/sqlcdb/domains.sql.go

@@ -0,0 +1,242 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: domains.sql
+
+package sqlcdb
+
+import (
+	"context"
+	"database/sql"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+const clearServiceDomainDefault = `-- name: ClearServiceDomainDefault :exec
+UPDATE service_domains SET is_default = false WHERE service_id = $1
+`
+
+func (q *Queries) ClearServiceDomainDefault(ctx context.Context, serviceID uuid.UUID) error {
+	_, err := q.db.ExecContext(ctx, clearServiceDomainDefault, serviceID)
+	return err
+}
+
+const countServiceDomains = `-- name: CountServiceDomains :one
+SELECT COUNT(*) FROM service_domains WHERE service_id = $1
+`
+
+func (q *Queries) CountServiceDomains(ctx context.Context, serviceID uuid.UUID) (int64, error) {
+	row := q.db.QueryRowContext(ctx, countServiceDomains, serviceID)
+	var count int64
+	err := row.Scan(&count)
+	return count, err
+}
+
+const createServiceDomain = `-- name: CreateServiceDomain :one
+INSERT INTO service_domains (service_id, domain, is_default)
+VALUES ($1, $2, $3)
+RETURNING id, service_id, domain, is_default, cert_type, cert_status, created_at
+`
+
+type CreateServiceDomainParams struct {
+	ServiceID uuid.UUID `json:"service_id"`
+	Domain    string    `json:"domain"`
+	IsDefault bool      `json:"is_default"`
+}
+
+type CreateServiceDomainRow struct {
+	ID         uuid.UUID `json:"id"`
+	ServiceID  uuid.UUID `json:"service_id"`
+	Domain     string    `json:"domain"`
+	IsDefault  bool      `json:"is_default"`
+	CertType   string    `json:"cert_type"`
+	CertStatus string    `json:"cert_status"`
+	CreatedAt  time.Time `json:"created_at"`
+}
+
+func (q *Queries) CreateServiceDomain(ctx context.Context, arg CreateServiceDomainParams) (CreateServiceDomainRow, error) {
+	row := q.db.QueryRowContext(ctx, createServiceDomain, arg.ServiceID, arg.Domain, arg.IsDefault)
+	var i CreateServiceDomainRow
+	err := row.Scan(
+		&i.ID,
+		&i.ServiceID,
+		&i.Domain,
+		&i.IsDefault,
+		&i.CertType,
+		&i.CertStatus,
+		&i.CreatedAt,
+	)
+	return i, err
+}
+
+const deleteServiceDomain = `-- name: DeleteServiceDomain :execrows
+DELETE FROM service_domains WHERE id = $1 AND service_id = $2
+`
+
+type DeleteServiceDomainParams struct {
+	ID        uuid.UUID `json:"id"`
+	ServiceID uuid.UUID `json:"service_id"`
+}
+
+func (q *Queries) DeleteServiceDomain(ctx context.Context, arg DeleteServiceDomainParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, deleteServiceDomain, arg.ID, arg.ServiceID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const getServiceAccess = `-- name: GetServiceAccess :one
+SELECT maintenance_mode, basic_auth_users FROM services WHERE id = $1
+`
+
+type GetServiceAccessRow struct {
+	MaintenanceMode bool   `json:"maintenance_mode"`
+	BasicAuthUsers  string `json:"basic_auth_users"`
+}
+
+func (q *Queries) GetServiceAccess(ctx context.Context, id uuid.UUID) (GetServiceAccessRow, error) {
+	row := q.db.QueryRowContext(ctx, getServiceAccess, id)
+	var i GetServiceAccessRow
+	err := row.Scan(&i.MaintenanceMode, &i.BasicAuthUsers)
+	return i, err
+}
+
+const getServiceDomainDefault = `-- name: GetServiceDomainDefault :one
+SELECT domain FROM service_domains WHERE service_id = $1 AND is_default
+`
+
+func (q *Queries) GetServiceDomainDefault(ctx context.Context, serviceID uuid.UUID) (string, error) {
+	row := q.db.QueryRowContext(ctx, getServiceDomainDefault, serviceID)
+	var domain string
+	err := row.Scan(&domain)
+	return domain, err
+}
+
+const getServiceDomainFirst = `-- name: GetServiceDomainFirst :one
+SELECT domain FROM service_domains WHERE service_id = $1 ORDER BY created_at ASC LIMIT 1
+`
+
+func (q *Queries) GetServiceDomainFirst(ctx context.Context, serviceID uuid.UUID) (string, error) {
+	row := q.db.QueryRowContext(ctx, getServiceDomainFirst, serviceID)
+	var domain string
+	err := row.Scan(&domain)
+	return domain, err
+}
+
+const getServicePlacementBrief = `-- name: GetServicePlacementBrief :one
+SELECT name, node_id, COALESCE(spread, false) AS spread FROM services WHERE id = $1
+`
+
+type GetServicePlacementBriefRow struct {
+	Name   string         `json:"name"`
+	NodeID sql.NullString `json:"node_id"`
+	Spread bool           `json:"spread"`
+}
+
+func (q *Queries) GetServicePlacementBrief(ctx context.Context, id uuid.UUID) (GetServicePlacementBriefRow, error) {
+	row := q.db.QueryRowContext(ctx, getServicePlacementBrief, id)
+	var i GetServicePlacementBriefRow
+	err := row.Scan(&i.Name, &i.NodeID, &i.Spread)
+	return i, err
+}
+
+const listServiceDomains = `-- name: ListServiceDomains :many
+SELECT id, service_id, domain, is_default, cert_type, cert_status, last_checked_at, created_at
+FROM service_domains
+WHERE service_id = $1
+ORDER BY is_default DESC, created_at ASC
+`
+
+func (q *Queries) ListServiceDomains(ctx context.Context, serviceID uuid.UUID) ([]ServiceDomain, error) {
+	rows, err := q.db.QueryContext(ctx, listServiceDomains, serviceID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []ServiceDomain{}
+	for rows.Next() {
+		var i ServiceDomain
+		if err := rows.Scan(
+			&i.ID,
+			&i.ServiceID,
+			&i.Domain,
+			&i.IsDefault,
+			&i.CertType,
+			&i.CertStatus,
+			&i.LastCheckedAt,
+			&i.CreatedAt,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const serviceWriteAccess = `-- name: ServiceWriteAccess :one
+SELECT EXISTS(
+    SELECT 1 FROM services s JOIN projects p ON s.project_id = p.id
+    WHERE s.id = $1 AND (p.owner_id = $2 OR $3::bool)
+) AS allowed
+`
+
+type ServiceWriteAccessParams struct {
+	ID      uuid.UUID `json:"id"`
+	OwnerID uuid.UUID `json:"owner_id"`
+	Column3 bool      `json:"column_3"`
+}
+
+func (q *Queries) ServiceWriteAccess(ctx context.Context, arg ServiceWriteAccessParams) (bool, error) {
+	row := q.db.QueryRowContext(ctx, serviceWriteAccess, arg.ID, arg.OwnerID, arg.Column3)
+	var allowed bool
+	err := row.Scan(&allowed)
+	return allowed, err
+}
+
+const setServiceDomainDefault = `-- name: SetServiceDomainDefault :execrows
+UPDATE service_domains SET is_default = (id = $1) WHERE service_id = $2
+`
+
+type SetServiceDomainDefaultParams struct {
+	ID        uuid.UUID `json:"id"`
+	ServiceID uuid.UUID `json:"service_id"`
+}
+
+func (q *Queries) SetServiceDomainDefault(ctx context.Context, arg SetServiceDomainDefaultParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, setServiceDomainDefault, arg.ID, arg.ServiceID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const setServiceLegacyDomain = `-- name: SetServiceLegacyDomain :exec
+UPDATE services SET domain = $1 WHERE id = $2
+`
+
+type SetServiceLegacyDomainParams struct {
+	Domain string    `json:"domain"`
+	ID     uuid.UUID `json:"id"`
+}
+
+func (q *Queries) SetServiceLegacyDomain(ctx context.Context, arg SetServiceLegacyDomainParams) error {
+	_, err := q.db.ExecContext(ctx, setServiceLegacyDomain, arg.Domain, arg.ID)
+	return err
+}
+
+const touchServiceDomainChecked = `-- name: TouchServiceDomainChecked :exec
+UPDATE service_domains SET last_checked_at = NOW() WHERE id = $1
+`
+
+func (q *Queries) TouchServiceDomainChecked(ctx context.Context, id uuid.UUID) error {
+	_, err := q.db.ExecContext(ctx, touchServiceDomainChecked, id)
+	return err
+}

app/backend/internal/database/sqlcdb/metrics.sql.go

@@ -0,0 +1,623 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: metrics.sql
+
+package sqlcdb
+
+import (
+	"context"
+	"database/sql"
+	"time"
+)
+
+const aggregateNodeMetrics = `-- name: AggregateNodeMetrics :many
+SELECT date_bin($1::interval, timestamp, '2000-01-01'::timestamptz) AS bucket,
+       AVG(cpu_usage)::float8 AS avg_cpu,
+       AVG(memory_usage_percent)::float8 AS avg_memory,
+       AVG(storage_usage_percent)::float8 AS avg_storage
+FROM node_metrics
+WHERE node_id = $2 AND timestamp BETWEEN $3 AND $4
+GROUP BY bucket
+ORDER BY bucket ASC
+`
+
+type AggregateNodeMetricsParams struct {
+	Column1     int64     `json:"column_1"`
+	NodeID      string    `json:"node_id"`
+	Timestamp   time.Time `json:"timestamp"`
+	Timestamp_2 time.Time `json:"timestamp_2"`
+}
+
+type AggregateNodeMetricsRow struct {
+	Bucket     interface{} `json:"bucket"`
+	AvgCpu     float64     `json:"avg_cpu"`
+	AvgMemory  float64     `json:"avg_memory"`
+	AvgStorage float64     `json:"avg_storage"`
+}
+
+// Portable bucket bucketing (no TimescaleDB): floor epoch seconds into
+// bucket-sized buckets, then back to timestamptz.
+func (q *Queries) AggregateNodeMetrics(ctx context.Context, arg AggregateNodeMetricsParams) ([]AggregateNodeMetricsRow, error) {
+	rows, err := q.db.QueryContext(ctx, aggregateNodeMetrics,
+		arg.Column1,
+		arg.NodeID,
+		arg.Timestamp,
+		arg.Timestamp_2,
+	)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []AggregateNodeMetricsRow{}
+	for rows.Next() {
+		var i AggregateNodeMetricsRow
+		if err := rows.Scan(
+			&i.Bucket,
+			&i.AvgCpu,
+			&i.AvgMemory,
+			&i.AvgStorage,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listInstanceMetrics = `-- name: ListInstanceMetrics :many
+SELECT instance_id, node_id, status, cpu, memory,
+       network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
+       network_connections_in, network_connections_out, network_errors_in, network_errors_out,
+       start_time, last_seen, health_status, health_last_check, health_check_count, health_failure_count
+FROM instance_metrics
+WHERE service_id = $1 AND timestamp = $2
+`
+
+type ListInstanceMetricsParams struct {
+	ServiceID string    `json:"service_id"`
+	Timestamp time.Time `json:"timestamp"`
+}
+
+type ListInstanceMetricsRow struct {
+	InstanceID            string         `json:"instance_id"`
+	NodeID                sql.NullString `json:"node_id"`
+	Status                sql.NullString `json:"status"`
+	Cpu                   sql.NullString `json:"cpu"`
+	Memory                sql.NullInt64  `json:"memory"`
+	NetworkBytesIn        sql.NullInt64  `json:"network_bytes_in"`
+	NetworkBytesOut       sql.NullInt64  `json:"network_bytes_out"`
+	NetworkPacketsIn      sql.NullInt64  `json:"network_packets_in"`
+	NetworkPacketsOut     sql.NullInt64  `json:"network_packets_out"`
+	NetworkConnectionsIn  sql.NullInt32  `json:"network_connections_in"`
+	NetworkConnectionsOut sql.NullInt32  `json:"network_connections_out"`
+	NetworkErrorsIn       sql.NullInt64  `json:"network_errors_in"`
+	NetworkErrorsOut      sql.NullInt64  `json:"network_errors_out"`
+	StartTime             sql.NullTime   `json:"start_time"`
+	LastSeen              sql.NullTime   `json:"last_seen"`
+	HealthStatus          sql.NullString `json:"health_status"`
+	HealthLastCheck       sql.NullTime   `json:"health_last_check"`
+	HealthCheckCount      sql.NullInt32  `json:"health_check_count"`
+	HealthFailureCount    sql.NullInt32  `json:"health_failure_count"`
+}
+
+func (q *Queries) ListInstanceMetrics(ctx context.Context, arg ListInstanceMetricsParams) ([]ListInstanceMetricsRow, error) {
+	rows, err := q.db.QueryContext(ctx, listInstanceMetrics, arg.ServiceID, arg.Timestamp)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []ListInstanceMetricsRow{}
+	for rows.Next() {
+		var i ListInstanceMetricsRow
+		if err := rows.Scan(
+			&i.InstanceID,
+			&i.NodeID,
+			&i.Status,
+			&i.Cpu,
+			&i.Memory,
+			&i.NetworkBytesIn,
+			&i.NetworkBytesOut,
+			&i.NetworkPacketsIn,
+			&i.NetworkPacketsOut,
+			&i.NetworkConnectionsIn,
+			&i.NetworkConnectionsOut,
+			&i.NetworkErrorsIn,
+			&i.NetworkErrorsOut,
+			&i.StartTime,
+			&i.LastSeen,
+			&i.HealthStatus,
+			&i.HealthLastCheck,
+			&i.HealthCheckCount,
+			&i.HealthFailureCount,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listNodeMetrics = `-- name: ListNodeMetrics :many
+SELECT node_id, timestamp, cpu_usage, cpu_cores, load_avg_1, load_avg_5, load_avg_15,
+       memory_total, memory_used, memory_available, memory_usage_percent,
+       storage_total, storage_used, storage_available, storage_usage_percent,
+       network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
+       network_connections_in, network_connections_out, network_errors_in, network_errors_out,
+       coalesce(extract(epoch from uptime), 0)::bigint AS uptime_seconds,
+       processes, os, kernel, architecture
+FROM node_metrics
+WHERE node_id = $1 AND timestamp BETWEEN $2 AND $3
+ORDER BY timestamp ASC
+`
+
+type ListNodeMetricsParams struct {
+	NodeID      string    `json:"node_id"`
+	Timestamp   time.Time `json:"timestamp"`
+	Timestamp_2 time.Time `json:"timestamp_2"`
+}
+
+type ListNodeMetricsRow struct {
+	NodeID                string         `json:"node_id"`
+	Timestamp             time.Time      `json:"timestamp"`
+	CpuUsage              sql.NullString `json:"cpu_usage"`
+	CpuCores              sql.NullString `json:"cpu_cores"`
+	LoadAvg1              sql.NullString `json:"load_avg_1"`
+	LoadAvg5              sql.NullString `json:"load_avg_5"`
+	LoadAvg15             sql.NullString `json:"load_avg_15"`
+	MemoryTotal           sql.NullInt64  `json:"memory_total"`
+	MemoryUsed            sql.NullInt64  `json:"memory_used"`
+	MemoryAvailable       sql.NullInt64  `json:"memory_available"`
+	MemoryUsagePercent    sql.NullString `json:"memory_usage_percent"`
+	StorageTotal          sql.NullInt64  `json:"storage_total"`
+	StorageUsed           sql.NullInt64  `json:"storage_used"`
+	StorageAvailable      sql.NullInt64  `json:"storage_available"`
+	StorageUsagePercent   sql.NullString `json:"storage_usage_percent"`
+	NetworkBytesIn        sql.NullInt64  `json:"network_bytes_in"`
+	NetworkBytesOut       sql.NullInt64  `json:"network_bytes_out"`
+	NetworkPacketsIn      sql.NullInt64  `json:"network_packets_in"`
+	NetworkPacketsOut     sql.NullInt64  `json:"network_packets_out"`
+	NetworkConnectionsIn  sql.NullInt32  `json:"network_connections_in"`
+	NetworkConnectionsOut sql.NullInt32  `json:"network_connections_out"`
+	NetworkErrorsIn       sql.NullInt64  `json:"network_errors_in"`
+	NetworkErrorsOut      sql.NullInt64  `json:"network_errors_out"`
+	UptimeSeconds         int64          `json:"uptime_seconds"`
+	Processes             sql.NullInt32  `json:"processes"`
+	Os                    sql.NullString `json:"os"`
+	Kernel                sql.NullString `json:"kernel"`
+	Architecture          sql.NullString `json:"architecture"`
+}
+
+func (q *Queries) ListNodeMetrics(ctx context.Context, arg ListNodeMetricsParams) ([]ListNodeMetricsRow, error) {
+	rows, err := q.db.QueryContext(ctx, listNodeMetrics, arg.NodeID, arg.Timestamp, arg.Timestamp_2)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []ListNodeMetricsRow{}
+	for rows.Next() {
+		var i ListNodeMetricsRow
+		if err := rows.Scan(
+			&i.NodeID,
+			&i.Timestamp,
+			&i.CpuUsage,
+			&i.CpuCores,
+			&i.LoadAvg1,
+			&i.LoadAvg5,
+			&i.LoadAvg15,
+			&i.MemoryTotal,
+			&i.MemoryUsed,
+			&i.MemoryAvailable,
+			&i.MemoryUsagePercent,
+			&i.StorageTotal,
+			&i.StorageUsed,
+			&i.StorageAvailable,
+			&i.StorageUsagePercent,
+			&i.NetworkBytesIn,
+			&i.NetworkBytesOut,
+			&i.NetworkPacketsIn,
+			&i.NetworkPacketsOut,
+			&i.NetworkConnectionsIn,
+			&i.NetworkConnectionsOut,
+			&i.NetworkErrorsIn,
+			&i.NetworkErrorsOut,
+			&i.UptimeSeconds,
+			&i.Processes,
+			&i.Os,
+			&i.Kernel,
+			&i.Architecture,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listServiceMetrics = `-- name: ListServiceMetrics :many
+SELECT service_id, service_name, project_id, timestamp,
+       requests_total, requests_success, requests_errors, requests_avg_latency,
+       requests_p95_latency, requests_p99_latency, requests_throughput,
+       errors_total, errors_rate, performance_response_time, performance_throughput,
+       performance_concurrency, performance_saturation, performance_utilization,
+       resource_cpu_usage, resource_memory_usage, resource_storage_usage,
+       resource_network_usage, resource_score
+FROM service_metrics
+WHERE service_id = $1 AND timestamp BETWEEN $2 AND $3
+ORDER BY timestamp ASC
+`
+
+type ListServiceMetricsParams struct {
+	ServiceID   string    `json:"service_id"`
+	Timestamp   time.Time `json:"timestamp"`
+	Timestamp_2 time.Time `json:"timestamp_2"`
+}
+
+type ListServiceMetricsRow struct {
+	ServiceID               string         `json:"service_id"`
+	ServiceName             string         `json:"service_name"`
+	ProjectID               string         `json:"project_id"`
+	Timestamp               time.Time      `json:"timestamp"`
+	RequestsTotal           sql.NullInt64  `json:"requests_total"`
+	RequestsSuccess         sql.NullInt64  `json:"requests_success"`
+	RequestsErrors          sql.NullInt64  `json:"requests_errors"`
+	RequestsAvgLatency      sql.NullString `json:"requests_avg_latency"`
+	RequestsP95Latency      sql.NullString `json:"requests_p95_latency"`
+	RequestsP99Latency      sql.NullString `json:"requests_p99_latency"`
+	RequestsThroughput      sql.NullString `json:"requests_throughput"`
+	ErrorsTotal             sql.NullInt64  `json:"errors_total"`
+	ErrorsRate              sql.NullString `json:"errors_rate"`
+	PerformanceResponseTime sql.NullString `json:"performance_response_time"`
+	PerformanceThroughput   sql.NullString `json:"performance_throughput"`
+	PerformanceConcurrency  sql.NullInt64  `json:"performance_concurrency"`
+	PerformanceSaturation   sql.NullString `json:"performance_saturation"`
+	PerformanceUtilization  sql.NullString `json:"performance_utilization"`
+	ResourceCpuUsage        sql.NullString `json:"resource_cpu_usage"`
+	ResourceMemoryUsage     sql.NullInt64  `json:"resource_memory_usage"`
+	ResourceStorageUsage    sql.NullInt64  `json:"resource_storage_usage"`
+	ResourceNetworkUsage    sql.NullInt64  `json:"resource_network_usage"`
+	ResourceScore           sql.NullString `json:"resource_score"`
+}
+
+func (q *Queries) ListServiceMetrics(ctx context.Context, arg ListServiceMetricsParams) ([]ListServiceMetricsRow, error) {
+	rows, err := q.db.QueryContext(ctx, listServiceMetrics, arg.ServiceID, arg.Timestamp, arg.Timestamp_2)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []ListServiceMetricsRow{}
+	for rows.Next() {
+		var i ListServiceMetricsRow
+		if err := rows.Scan(
+			&i.ServiceID,
+			&i.ServiceName,
+			&i.ProjectID,
+			&i.Timestamp,
+			&i.RequestsTotal,
+			&i.RequestsSuccess,
+			&i.RequestsErrors,
+			&i.RequestsAvgLatency,
+			&i.RequestsP95Latency,
+			&i.RequestsP99Latency,
+			&i.RequestsThroughput,
+			&i.ErrorsTotal,
+			&i.ErrorsRate,
+			&i.PerformanceResponseTime,
+			&i.PerformanceThroughput,
+			&i.PerformanceConcurrency,
+			&i.PerformanceSaturation,
+			&i.PerformanceUtilization,
+			&i.ResourceCpuUsage,
+			&i.ResourceMemoryUsage,
+			&i.ResourceStorageUsage,
+			&i.ResourceNetworkUsage,
+			&i.ResourceScore,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const upsertInstanceMetrics = `-- name: UpsertInstanceMetrics :exec
+INSERT INTO instance_metrics (
+    service_id, timestamp, instance_id, node_id, status, cpu, memory,
+    network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
+    network_connections_in, network_connections_out, network_errors_in, network_errors_out,
+    start_time, last_seen, health_status, health_last_check, health_check_count, health_failure_count
+) VALUES (
+    $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15,
+    $16, $17, $18, $19, $20, $21
+)
+ON CONFLICT (service_id, timestamp, instance_id) DO UPDATE SET
+    node_id = EXCLUDED.node_id,
+    status = EXCLUDED.status,
+    cpu = EXCLUDED.cpu,
+    memory = EXCLUDED.memory,
+    network_bytes_in = EXCLUDED.network_bytes_in,
+    network_bytes_out = EXCLUDED.network_bytes_out,
+    network_packets_in = EXCLUDED.network_packets_in,
+    network_packets_out = EXCLUDED.network_packets_out,
+    network_connections_in = EXCLUDED.network_connections_in,
+    network_connections_out = EXCLUDED.network_connections_out,
+    network_errors_in = EXCLUDED.network_errors_in,
+    network_errors_out = EXCLUDED.network_errors_out,
+    start_time = EXCLUDED.start_time,
+    last_seen = EXCLUDED.last_seen,
+    health_status = EXCLUDED.health_status,
+    health_last_check = EXCLUDED.health_last_check,
+    health_check_count = EXCLUDED.health_check_count,
+    health_failure_count = EXCLUDED.health_failure_count
+`
+
+type UpsertInstanceMetricsParams struct {
+	ServiceID             string         `json:"service_id"`
+	Timestamp             time.Time      `json:"timestamp"`
+	InstanceID            string         `json:"instance_id"`
+	NodeID                sql.NullString `json:"node_id"`
+	Status                sql.NullString `json:"status"`
+	Cpu                   sql.NullString `json:"cpu"`
+	Memory                sql.NullInt64  `json:"memory"`
+	NetworkBytesIn        sql.NullInt64  `json:"network_bytes_in"`
+	NetworkBytesOut       sql.NullInt64  `json:"network_bytes_out"`
+	NetworkPacketsIn      sql.NullInt64  `json:"network_packets_in"`
+	NetworkPacketsOut     sql.NullInt64  `json:"network_packets_out"`
+	NetworkConnectionsIn  sql.NullInt32  `json:"network_connections_in"`
+	NetworkConnectionsOut sql.NullInt32  `json:"network_connections_out"`
+	NetworkErrorsIn       sql.NullInt64  `json:"network_errors_in"`
+	NetworkErrorsOut      sql.NullInt64  `json:"network_errors_out"`
+	StartTime             sql.NullTime   `json:"start_time"`
+	LastSeen              sql.NullTime   `json:"last_seen"`
+	HealthStatus          sql.NullString `json:"health_status"`
+	HealthLastCheck       sql.NullTime   `json:"health_last_check"`
+	HealthCheckCount      sql.NullInt32  `json:"health_check_count"`
+	HealthFailureCount    sql.NullInt32  `json:"health_failure_count"`
+}
+
+func (q *Queries) UpsertInstanceMetrics(ctx context.Context, arg UpsertInstanceMetricsParams) error {
+	_, err := q.db.ExecContext(ctx, upsertInstanceMetrics,
+		arg.ServiceID,
+		arg.Timestamp,
+		arg.InstanceID,
+		arg.NodeID,
+		arg.Status,
+		arg.Cpu,
+		arg.Memory,
+		arg.NetworkBytesIn,
+		arg.NetworkBytesOut,
+		arg.NetworkPacketsIn,
+		arg.NetworkPacketsOut,
+		arg.NetworkConnectionsIn,
+		arg.NetworkConnectionsOut,
+		arg.NetworkErrorsIn,
+		arg.NetworkErrorsOut,
+		arg.StartTime,
+		arg.LastSeen,
+		arg.HealthStatus,
+		arg.HealthLastCheck,
+		arg.HealthCheckCount,
+		arg.HealthFailureCount,
+	)
+	return err
+}
+
+const upsertNodeMetrics = `-- name: UpsertNodeMetrics :exec
+INSERT INTO node_metrics (
+    node_id, timestamp, cpu_usage, cpu_cores, load_avg_1, load_avg_5, load_avg_15,
+    memory_total, memory_used, memory_available, memory_usage_percent,
+    storage_total, storage_used, storage_available, storage_usage_percent,
+    network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
+    network_connections_in, network_connections_out, network_errors_in, network_errors_out,
+    uptime, processes, os, kernel, architecture
+) VALUES (
+    $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15,
+    $16, $17, $18, $19, $20, $21, $22, $23, $24, $25, $26, $27, $28
+)
+ON CONFLICT (node_id, timestamp) DO UPDATE SET
+    cpu_usage = EXCLUDED.cpu_usage,
+    cpu_cores = EXCLUDED.cpu_cores,
+    load_avg_1 = EXCLUDED.load_avg_1,
+    load_avg_5 = EXCLUDED.load_avg_5,
+    load_avg_15 = EXCLUDED.load_avg_15,
+    memory_total = EXCLUDED.memory_total,
+    memory_used = EXCLUDED.memory_used,
+    memory_available = EXCLUDED.memory_available,
+    memory_usage_percent = EXCLUDED.memory_usage_percent,
+    storage_total = EXCLUDED.storage_total,
+    storage_used = EXCLUDED.storage_used,
+    storage_available = EXCLUDED.storage_available,
+    storage_usage_percent = EXCLUDED.storage_usage_percent,
+    network_bytes_in = EXCLUDED.network_bytes_in,
+    network_bytes_out = EXCLUDED.network_bytes_out,
+    network_packets_in = EXCLUDED.network_packets_in,
+    network_packets_out = EXCLUDED.network_packets_out,
+    network_connections_in = EXCLUDED.network_connections_in,
+    network_connections_out = EXCLUDED.network_connections_out,
+    network_errors_in = EXCLUDED.network_errors_in,
+    network_errors_out = EXCLUDED.network_errors_out,
+    uptime = EXCLUDED.uptime,
+    processes = EXCLUDED.processes,
+    os = EXCLUDED.os,
+    kernel = EXCLUDED.kernel,
+    architecture = EXCLUDED.architecture
+`
+
+type UpsertNodeMetricsParams struct {
+	NodeID                string         `json:"node_id"`
+	Timestamp             time.Time      `json:"timestamp"`
+	CpuUsage              sql.NullString `json:"cpu_usage"`
+	CpuCores              sql.NullString `json:"cpu_cores"`
+	LoadAvg1              sql.NullString `json:"load_avg_1"`
+	LoadAvg5              sql.NullString `json:"load_avg_5"`
+	LoadAvg15             sql.NullString `json:"load_avg_15"`
+	MemoryTotal           sql.NullInt64  `json:"memory_total"`
+	MemoryUsed            sql.NullInt64  `json:"memory_used"`
+	MemoryAvailable       sql.NullInt64  `json:"memory_available"`
+	MemoryUsagePercent    sql.NullString `json:"memory_usage_percent"`
+	StorageTotal          sql.NullInt64  `json:"storage_total"`
+	StorageUsed           sql.NullInt64  `json:"storage_used"`
+	StorageAvailable      sql.NullInt64  `json:"storage_available"`
+	StorageUsagePercent   sql.NullString `json:"storage_usage_percent"`
+	NetworkBytesIn        sql.NullInt64  `json:"network_bytes_in"`
+	NetworkBytesOut       sql.NullInt64  `json:"network_bytes_out"`
+	NetworkPacketsIn      sql.NullInt64  `json:"network_packets_in"`
+	NetworkPacketsOut     sql.NullInt64  `json:"network_packets_out"`
+	NetworkConnectionsIn  sql.NullInt32  `json:"network_connections_in"`
+	NetworkConnectionsOut sql.NullInt32  `json:"network_connections_out"`
+	NetworkErrorsIn       sql.NullInt64  `json:"network_errors_in"`
+	NetworkErrorsOut      sql.NullInt64  `json:"network_errors_out"`
+	Uptime                sql.NullInt64  `json:"uptime"`
+	Processes             sql.NullInt32  `json:"processes"`
+	Os                    sql.NullString `json:"os"`
+	Kernel                sql.NullString `json:"kernel"`
+	Architecture          sql.NullString `json:"architecture"`
+}
+
+func (q *Queries) UpsertNodeMetrics(ctx context.Context, arg UpsertNodeMetricsParams) error {
+	_, err := q.db.ExecContext(ctx, upsertNodeMetrics,
+		arg.NodeID,
+		arg.Timestamp,
+		arg.CpuUsage,
+		arg.CpuCores,
+		arg.LoadAvg1,
+		arg.LoadAvg5,
+		arg.LoadAvg15,
+		arg.MemoryTotal,
+		arg.MemoryUsed,
+		arg.MemoryAvailable,
+		arg.MemoryUsagePercent,
+		arg.StorageTotal,
+		arg.StorageUsed,
+		arg.StorageAvailable,
+		arg.StorageUsagePercent,
+		arg.NetworkBytesIn,
+		arg.NetworkBytesOut,
+		arg.NetworkPacketsIn,
+		arg.NetworkPacketsOut,
+		arg.NetworkConnectionsIn,
+		arg.NetworkConnectionsOut,
+		arg.NetworkErrorsIn,
+		arg.NetworkErrorsOut,
+		arg.Uptime,
+		arg.Processes,
+		arg.Os,
+		arg.Kernel,
+		arg.Architecture,
+	)
+	return err
+}
+
+const upsertServiceMetrics = `-- name: UpsertServiceMetrics :exec
+INSERT INTO service_metrics (
+    service_id, service_name, project_id, timestamp,
+    requests_total, requests_success, requests_errors, requests_avg_latency,
+    requests_p95_latency, requests_p99_latency, requests_throughput,
+    errors_total, errors_rate, performance_response_time, performance_throughput,
+    performance_concurrency, performance_saturation, performance_utilization,
+    resource_cpu_usage, resource_memory_usage, resource_storage_usage,
+    resource_network_usage, resource_score
+) VALUES (
+    $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15,
+    $16, $17, $18, $19, $20, $21, $22, $23
+)
+ON CONFLICT (service_id, timestamp) DO UPDATE SET
+    requests_total = EXCLUDED.requests_total,
+    requests_success = EXCLUDED.requests_success,
+    requests_errors = EXCLUDED.requests_errors,
+    requests_avg_latency = EXCLUDED.requests_avg_latency,
+    requests_p95_latency = EXCLUDED.requests_p95_latency,
+    requests_p99_latency = EXCLUDED.requests_p99_latency,
+    requests_throughput = EXCLUDED.requests_throughput,
+    errors_total = EXCLUDED.errors_total,
+    errors_rate = EXCLUDED.errors_rate,
+    performance_response_time = EXCLUDED.performance_response_time,
+    performance_throughput = EXCLUDED.performance_throughput,
+    performance_concurrency = EXCLUDED.performance_concurrency,
+    performance_saturation = EXCLUDED.performance_saturation,
+    performance_utilization = EXCLUDED.performance_utilization,
+    resource_cpu_usage = EXCLUDED.resource_cpu_usage,
+    resource_memory_usage = EXCLUDED.resource_memory_usage,
+    resource_storage_usage = EXCLUDED.resource_storage_usage,
+    resource_network_usage = EXCLUDED.resource_network_usage,
+    resource_score = EXCLUDED.resource_score
+`
+
+type UpsertServiceMetricsParams struct {
+	ServiceID               string         `json:"service_id"`
+	ServiceName             string         `json:"service_name"`
+	ProjectID               string         `json:"project_id"`
+	Timestamp               time.Time      `json:"timestamp"`
+	RequestsTotal           sql.NullInt64  `json:"requests_total"`
+	RequestsSuccess         sql.NullInt64  `json:"requests_success"`
+	RequestsErrors          sql.NullInt64  `json:"requests_errors"`
+	RequestsAvgLatency      sql.NullString `json:"requests_avg_latency"`
+	RequestsP95Latency      sql.NullString `json:"requests_p95_latency"`
+	RequestsP99Latency      sql.NullString `json:"requests_p99_latency"`
+	RequestsThroughput      sql.NullString `json:"requests_throughput"`
+	ErrorsTotal             sql.NullInt64  `json:"errors_total"`
+	ErrorsRate              sql.NullString `json:"errors_rate"`
+	PerformanceResponseTime sql.NullString `json:"performance_response_time"`
+	PerformanceThroughput   sql.NullString `json:"performance_throughput"`
+	PerformanceConcurrency  sql.NullInt64  `json:"performance_concurrency"`
+	PerformanceSaturation   sql.NullString `json:"performance_saturation"`
+	PerformanceUtilization  sql.NullString `json:"performance_utilization"`
+	ResourceCpuUsage        sql.NullString `json:"resource_cpu_usage"`
+	ResourceMemoryUsage     sql.NullInt64  `json:"resource_memory_usage"`
+	ResourceStorageUsage    sql.NullInt64  `json:"resource_storage_usage"`
+	ResourceNetworkUsage    sql.NullInt64  `json:"resource_network_usage"`
+	ResourceScore           sql.NullString `json:"resource_score"`
+}
+
+func (q *Queries) UpsertServiceMetrics(ctx context.Context, arg UpsertServiceMetricsParams) error {
+	_, err := q.db.ExecContext(ctx, upsertServiceMetrics,
+		arg.ServiceID,
+		arg.ServiceName,
+		arg.ProjectID,
+		arg.Timestamp,
+		arg.RequestsTotal,
+		arg.RequestsSuccess,
+		arg.RequestsErrors,
+		arg.RequestsAvgLatency,
+		arg.RequestsP95Latency,
+		arg.RequestsP99Latency,
+		arg.RequestsThroughput,
+		arg.ErrorsTotal,
+		arg.ErrorsRate,
+		arg.PerformanceResponseTime,
+		arg.PerformanceThroughput,
+		arg.PerformanceConcurrency,
+		arg.PerformanceSaturation,
+		arg.PerformanceUtilization,
+		arg.ResourceCpuUsage,
+		arg.ResourceMemoryUsage,
+		arg.ResourceStorageUsage,
+		arg.ResourceNetworkUsage,
+		arg.ResourceScore,
+	)
+	return err
+}

app/backend/internal/database/sqlcdb/models.go

@@ -138,9 +138,20 @@ type DatabaseService struct {
 type Deployment struct {
 	ID            uuid.UUID      `json:"id"`
 	ServiceID     uuid.UUID      `json:"service_id"`
+	Version       string         `json:"version"`
+	CommitHash    sql.NullString `json:"commit_hash"`
+	ImageDigest   sql.NullString `json:"image_digest"`
 	Status        sql.NullString `json:"status"`
+	BuildLog      sql.NullString `json:"build_log"`
+	DeploymentLog sql.NullString `json:"deployment_log"`
+	StartedAt     sql.NullTime   `json:"started_at"`
+	CompletedAt   sql.NullTime   `json:"completed_at"`
 	CreatedAt     sql.NullTime   `json:"created_at"`
 	UpdatedAt     sql.NullTime   `json:"updated_at"`
+	ImageName     sql.NullString `json:"image_name"`
+	ImageTag      sql.NullString `json:"image_tag"`
+	RuntimeLog    sql.NullString `json:"runtime_log"`
+	Error         sql.NullString `json:"error"`
 }
 
 type Environment struct {
@@ -161,6 +172,31 @@ type EnvironmentVariable struct {
 	UpdatedAt sql.NullTime `json:"updated_at"`
 }
 
+type InstanceMetric struct {
+	ServiceID             string         `json:"service_id"`
+	Timestamp             time.Time      `json:"timestamp"`
+	InstanceID            string         `json:"instance_id"`
+	NodeID                sql.NullString `json:"node_id"`
+	Status                sql.NullString `json:"status"`
+	Cpu                   sql.NullString `json:"cpu"`
+	Memory                sql.NullInt64  `json:"memory"`
+	NetworkBytesIn        sql.NullInt64  `json:"network_bytes_in"`
+	NetworkBytesOut       sql.NullInt64  `json:"network_bytes_out"`
+	NetworkPacketsIn      sql.NullInt64  `json:"network_packets_in"`
+	NetworkPacketsOut     sql.NullInt64  `json:"network_packets_out"`
+	NetworkConnectionsIn  sql.NullInt32  `json:"network_connections_in"`
+	NetworkConnectionsOut sql.NullInt32  `json:"network_connections_out"`
+	NetworkErrorsIn       sql.NullInt64  `json:"network_errors_in"`
+	NetworkErrorsOut      sql.NullInt64  `json:"network_errors_out"`
+	StartTime             sql.NullTime   `json:"start_time"`
+	LastSeen              sql.NullTime   `json:"last_seen"`
+	HealthStatus          sql.NullString `json:"health_status"`
+	HealthLastCheck       sql.NullTime   `json:"health_last_check"`
+	HealthCheckCount      sql.NullInt32  `json:"health_check_count"`
+	HealthFailureCount    sql.NullInt32  `json:"health_failure_count"`
+	CreatedAt             sql.NullTime   `json:"created_at"`
+}
+
 type NodeAgent struct {
 	ID            string                `json:"id"`
 	Name          string                `json:"name"`
@@ -181,6 +217,38 @@ type NodeAgent struct {
 	DefaultDomain string                `json:"default_domain"`
 }
 
+type NodeMetric struct {
+	NodeID                string         `json:"node_id"`
+	Timestamp             time.Time      `json:"timestamp"`
+	CpuUsage              sql.NullString `json:"cpu_usage"`
+	CpuCores              sql.NullString `json:"cpu_cores"`
+	LoadAvg1              sql.NullString `json:"load_avg_1"`
+	LoadAvg5              sql.NullString `json:"load_avg_5"`
+	LoadAvg15             sql.NullString `json:"load_avg_15"`
+	MemoryTotal           sql.NullInt64  `json:"memory_total"`
+	MemoryUsed            sql.NullInt64  `json:"memory_used"`
+	MemoryAvailable       sql.NullInt64  `json:"memory_available"`
+	MemoryUsagePercent    sql.NullString `json:"memory_usage_percent"`
+	StorageTotal          sql.NullInt64  `json:"storage_total"`
+	StorageUsed           sql.NullInt64  `json:"storage_used"`
+	StorageAvailable      sql.NullInt64  `json:"storage_available"`
+	StorageUsagePercent   sql.NullString `json:"storage_usage_percent"`
+	NetworkBytesIn        sql.NullInt64  `json:"network_bytes_in"`
+	NetworkBytesOut       sql.NullInt64  `json:"network_bytes_out"`
+	NetworkPacketsIn      sql.NullInt64  `json:"network_packets_in"`
+	NetworkPacketsOut     sql.NullInt64  `json:"network_packets_out"`
+	NetworkConnectionsIn  sql.NullInt32  `json:"network_connections_in"`
+	NetworkConnectionsOut sql.NullInt32  `json:"network_connections_out"`
+	NetworkErrorsIn       sql.NullInt64  `json:"network_errors_in"`
+	NetworkErrorsOut      sql.NullInt64  `json:"network_errors_out"`
+	Uptime                sql.NullInt64  `json:"uptime"`
+	Processes             sql.NullInt32  `json:"processes"`
+	Os                    sql.NullString `json:"os"`
+	Kernel                sql.NullString `json:"kernel"`
+	Architecture          sql.NullString `json:"architecture"`
+	CreatedAt             sql.NullTime   `json:"created_at"`
+}
+
 type Notification struct {
 	ID           uuid.UUID      `json:"id"`
 	UserID       uuid.UUID      `json:"user_id"`
@@ -217,6 +285,21 @@ type OutboundWebhook struct {
 	UpdatedAt sql.NullTime          `json:"updated_at"`
 }
 
+type PreviewEnvironment struct {
+	ID               uuid.UUID      `json:"id"`
+	ProjectID        uuid.UUID      `json:"project_id"`
+	ServiceID        uuid.UUID      `json:"service_id"`
+	BranchName       string         `json:"branch_name"`
+	PrNumber         sql.NullInt32  `json:"pr_number"`
+	Environment      string         `json:"environment"`
+	Status           string         `json:"status"`
+	Url              sql.NullString `json:"url"`
+	ExpiresAt        time.Time      `json:"expires_at"`
+	CreatedAt        sql.NullTime   `json:"created_at"`
+	UpdatedAt        sql.NullTime   `json:"updated_at"`
+	PreviewServiceID uuid.NullUUID  `json:"preview_service_id"`
+}
+
 type Project struct {
 	ID          uuid.UUID      `json:"id"`
 	Name        string         `json:"name"`
@@ -305,6 +388,33 @@ type ServiceDomain struct {
 	CreatedAt     time.Time    `json:"created_at"`
 }
 
+type ServiceMetric struct {
+	ServiceID               string         `json:"service_id"`
+	ServiceName             string         `json:"service_name"`
+	ProjectID               string         `json:"project_id"`
+	Timestamp               time.Time      `json:"timestamp"`
+	RequestsTotal           sql.NullInt64  `json:"requests_total"`
+	RequestsSuccess         sql.NullInt64  `json:"requests_success"`
+	RequestsErrors          sql.NullInt64  `json:"requests_errors"`
+	RequestsAvgLatency      sql.NullString `json:"requests_avg_latency"`
+	RequestsP95Latency      sql.NullString `json:"requests_p95_latency"`
+	RequestsP99Latency      sql.NullString `json:"requests_p99_latency"`
+	RequestsThroughput      sql.NullString `json:"requests_throughput"`
+	ErrorsTotal             sql.NullInt64  `json:"errors_total"`
+	ErrorsRate              sql.NullString `json:"errors_rate"`
+	PerformanceResponseTime sql.NullString `json:"performance_response_time"`
+	PerformanceThroughput   sql.NullString `json:"performance_throughput"`
+	PerformanceConcurrency  sql.NullInt64  `json:"performance_concurrency"`
+	PerformanceSaturation   sql.NullString `json:"performance_saturation"`
+	PerformanceUtilization  sql.NullString `json:"performance_utilization"`
+	ResourceCpuUsage        sql.NullString `json:"resource_cpu_usage"`
+	ResourceMemoryUsage     sql.NullInt64  `json:"resource_memory_usage"`
+	ResourceStorageUsage    sql.NullInt64  `json:"resource_storage_usage"`
+	ResourceNetworkUsage    sql.NullInt64  `json:"resource_network_usage"`
+	ResourceScore           sql.NullString `json:"resource_score"`
+	CreatedAt               sql.NullTime   `json:"created_at"`
+}
+
 type ServiceTemplate struct {
 	ID          string                `json:"id"`
 	Name        string                `json:"name"`

app/backend/internal/database/sqlcdb/preview_environments.sql.go

@@ -0,0 +1,635 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: preview_environments.sql
+
+package sqlcdb
+
+import (
+	"context"
+	"database/sql"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+const countActivePreviewsForBranch = `-- name: CountActivePreviewsForBranch :one
+SELECT COUNT(*) FROM preview_environments
+WHERE service_id = $1 AND branch_name = $2 AND status NOT IN ('expired', 'stopped')
+`
+
+type CountActivePreviewsForBranchParams struct {
+	ServiceID  uuid.UUID `json:"service_id"`
+	BranchName string    `json:"branch_name"`
+}
+
+func (q *Queries) CountActivePreviewsForBranch(ctx context.Context, arg CountActivePreviewsForBranchParams) (int64, error) {
+	row := q.db.QueryRowContext(ctx, countActivePreviewsForBranch, arg.ServiceID, arg.BranchName)
+	var count int64
+	err := row.Scan(&count)
+	return count, err
+}
+
+const createPreviewDomain = `-- name: CreatePreviewDomain :exec
+INSERT INTO service_domains (service_id, domain, is_default, cert_type) VALUES ($1, $2, true, 'tls')
+`
+
+type CreatePreviewDomainParams struct {
+	ServiceID uuid.UUID `json:"service_id"`
+	Domain    string    `json:"domain"`
+}
+
+func (q *Queries) CreatePreviewDomain(ctx context.Context, arg CreatePreviewDomainParams) error {
+	_, err := q.db.ExecContext(ctx, createPreviewDomain, arg.ServiceID, arg.Domain)
+	return err
+}
+
+const createPreviewEnvironment = `-- name: CreatePreviewEnvironment :exec
+INSERT INTO preview_environments
+    (id, project_id, service_id, preview_service_id, branch_name, pr_number, environment,
+     status, url, expires_at, created_at, updated_at)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
+`
+
+type CreatePreviewEnvironmentParams struct {
+	ID               uuid.UUID      `json:"id"`
+	ProjectID        uuid.UUID      `json:"project_id"`
+	ServiceID        uuid.UUID      `json:"service_id"`
+	PreviewServiceID uuid.NullUUID  `json:"preview_service_id"`
+	BranchName       string         `json:"branch_name"`
+	PrNumber         sql.NullInt32  `json:"pr_number"`
+	Environment      string         `json:"environment"`
+	Status           string         `json:"status"`
+	Url              sql.NullString `json:"url"`
+	ExpiresAt        time.Time      `json:"expires_at"`
+	CreatedAt        sql.NullTime   `json:"created_at"`
+	UpdatedAt        sql.NullTime   `json:"updated_at"`
+}
+
+func (q *Queries) CreatePreviewEnvironment(ctx context.Context, arg CreatePreviewEnvironmentParams) error {
+	_, err := q.db.ExecContext(ctx, createPreviewEnvironment,
+		arg.ID,
+		arg.ProjectID,
+		arg.ServiceID,
+		arg.PreviewServiceID,
+		arg.BranchName,
+		arg.PrNumber,
+		arg.Environment,
+		arg.Status,
+		arg.Url,
+		arg.ExpiresAt,
+		arg.CreatedAt,
+		arg.UpdatedAt,
+	)
+	return err
+}
+
+const deleteAllServiceDomains = `-- name: DeleteAllServiceDomains :exec
+DELETE FROM service_domains WHERE service_id = $1
+`
+
+func (q *Queries) DeleteAllServiceDomains(ctx context.Context, serviceID uuid.UUID) error {
+	_, err := q.db.ExecContext(ctx, deleteAllServiceDomains, serviceID)
+	return err
+}
+
+const deletePreviewEnvironment = `-- name: DeletePreviewEnvironment :exec
+DELETE FROM preview_environments WHERE id = $1
+`
+
+func (q *Queries) DeletePreviewEnvironment(ctx context.Context, id uuid.UUID) error {
+	_, err := q.db.ExecContext(ctx, deletePreviewEnvironment, id)
+	return err
+}
+
+const getPreviewEnvironment = `-- name: GetPreviewEnvironment :one
+SELECT pe.id, pe.project_id, pe.service_id, pe.preview_service_id, pe.branch_name, pe.pr_number,
+       pe.environment, pe.status, pe.url, pe.expires_at, pe.created_at, pe.updated_at,
+       s.id AS svc_id, s.name AS service_name, s.type AS service_type
+FROM preview_environments pe
+LEFT JOIN services s ON pe.service_id = s.id
+JOIN projects p ON pe.project_id = p.id
+WHERE pe.id = $1 AND (p.is_approved OR p.owner_id = $2 OR $3::bool
+    OR EXISTS (SELECT 1 FROM project_members pm WHERE pm.project_id = p.id AND pm.user_id = $2))
+`
+
+type GetPreviewEnvironmentParams struct {
+	ID      uuid.UUID `json:"id"`
+	OwnerID uuid.UUID `json:"owner_id"`
+	Column3 bool      `json:"column_3"`
+}
+
+type GetPreviewEnvironmentRow struct {
+	ID               uuid.UUID      `json:"id"`
+	ProjectID        uuid.UUID      `json:"project_id"`
+	ServiceID        uuid.UUID      `json:"service_id"`
+	PreviewServiceID uuid.NullUUID  `json:"preview_service_id"`
+	BranchName       string         `json:"branch_name"`
+	PrNumber         sql.NullInt32  `json:"pr_number"`
+	Environment      string         `json:"environment"`
+	Status           string         `json:"status"`
+	Url              sql.NullString `json:"url"`
+	ExpiresAt        time.Time      `json:"expires_at"`
+	CreatedAt        sql.NullTime   `json:"created_at"`
+	UpdatedAt        sql.NullTime   `json:"updated_at"`
+	SvcID            uuid.NullUUID  `json:"svc_id"`
+	ServiceName      sql.NullString `json:"service_name"`
+	ServiceType      sql.NullString `json:"service_type"`
+}
+
+func (q *Queries) GetPreviewEnvironment(ctx context.Context, arg GetPreviewEnvironmentParams) (GetPreviewEnvironmentRow, error) {
+	row := q.db.QueryRowContext(ctx, getPreviewEnvironment, arg.ID, arg.OwnerID, arg.Column3)
+	var i GetPreviewEnvironmentRow
+	err := row.Scan(
+		&i.ID,
+		&i.ProjectID,
+		&i.ServiceID,
+		&i.PreviewServiceID,
+		&i.BranchName,
+		&i.PrNumber,
+		&i.Environment,
+		&i.Status,
+		&i.Url,
+		&i.ExpiresAt,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+		&i.SvcID,
+		&i.ServiceName,
+		&i.ServiceType,
+	)
+	return i, err
+}
+
+const getPreviewEnvironmentForPromote = `-- name: GetPreviewEnvironmentForPromote :one
+SELECT pe.id, pe.project_id, pe.service_id, pe.preview_service_id, pe.branch_name, pe.environment, pe.status
+FROM preview_environments pe
+JOIN projects p ON pe.project_id = p.id
+WHERE pe.id = $1 AND (p.owner_id = $2 OR $3::bool)
+`
+
+type GetPreviewEnvironmentForPromoteParams struct {
+	ID      uuid.UUID `json:"id"`
+	OwnerID uuid.UUID `json:"owner_id"`
+	Column3 bool      `json:"column_3"`
+}
+
+type GetPreviewEnvironmentForPromoteRow struct {
+	ID               uuid.UUID     `json:"id"`
+	ProjectID        uuid.UUID     `json:"project_id"`
+	ServiceID        uuid.UUID     `json:"service_id"`
+	PreviewServiceID uuid.NullUUID `json:"preview_service_id"`
+	BranchName       string        `json:"branch_name"`
+	Environment      string        `json:"environment"`
+	Status           string        `json:"status"`
+}
+
+func (q *Queries) GetPreviewEnvironmentForPromote(ctx context.Context, arg GetPreviewEnvironmentForPromoteParams) (GetPreviewEnvironmentForPromoteRow, error) {
+	row := q.db.QueryRowContext(ctx, getPreviewEnvironmentForPromote, arg.ID, arg.OwnerID, arg.Column3)
+	var i GetPreviewEnvironmentForPromoteRow
+	err := row.Scan(
+		&i.ID,
+		&i.ProjectID,
+		&i.ServiceID,
+		&i.PreviewServiceID,
+		&i.BranchName,
+		&i.Environment,
+		&i.Status,
+	)
+	return i, err
+}
+
+const getPreviewEnvironmentForWrite = `-- name: GetPreviewEnvironmentForWrite :one
+SELECT pe.id, pe.project_id, pe.service_id, pe.branch_name, pe.pr_number,
+       pe.environment, pe.status, pe.url, pe.expires_at, pe.created_at, pe.updated_at
+FROM preview_environments pe
+JOIN projects p ON pe.project_id = p.id
+WHERE pe.id = $1 AND (p.owner_id = $2 OR $3::bool)
+`
+
+type GetPreviewEnvironmentForWriteParams struct {
+	ID      uuid.UUID `json:"id"`
+	OwnerID uuid.UUID `json:"owner_id"`
+	Column3 bool      `json:"column_3"`
+}
+
+type GetPreviewEnvironmentForWriteRow struct {
+	ID          uuid.UUID      `json:"id"`
+	ProjectID   uuid.UUID      `json:"project_id"`
+	ServiceID   uuid.UUID      `json:"service_id"`
+	BranchName  string         `json:"branch_name"`
+	PrNumber    sql.NullInt32  `json:"pr_number"`
+	Environment string         `json:"environment"`
+	Status      string         `json:"status"`
+	Url         sql.NullString `json:"url"`
+	ExpiresAt   time.Time      `json:"expires_at"`
+	CreatedAt   sql.NullTime   `json:"created_at"`
+	UpdatedAt   sql.NullTime   `json:"updated_at"`
+}
+
+func (q *Queries) GetPreviewEnvironmentForWrite(ctx context.Context, arg GetPreviewEnvironmentForWriteParams) (GetPreviewEnvironmentForWriteRow, error) {
+	row := q.db.QueryRowContext(ctx, getPreviewEnvironmentForWrite, arg.ID, arg.OwnerID, arg.Column3)
+	var i GetPreviewEnvironmentForWriteRow
+	err := row.Scan(
+		&i.ID,
+		&i.ProjectID,
+		&i.ServiceID,
+		&i.BranchName,
+		&i.PrNumber,
+		&i.Environment,
+		&i.Status,
+		&i.Url,
+		&i.ExpiresAt,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+	)
+	return i, err
+}
+
+const getPreviewEnvironmentOwner = `-- name: GetPreviewEnvironmentOwner :one
+SELECT p.owner_id
+FROM preview_environments pe
+JOIN projects p ON pe.project_id = p.id
+WHERE pe.id = $1
+`
+
+func (q *Queries) GetPreviewEnvironmentOwner(ctx context.Context, id uuid.UUID) (uuid.UUID, error) {
+	row := q.db.QueryRowContext(ctx, getPreviewEnvironmentOwner, id)
+	var owner_id uuid.UUID
+	err := row.Scan(&owner_id)
+	return owner_id, err
+}
+
+const getPreviewServiceID = `-- name: GetPreviewServiceID :one
+SELECT preview_service_id FROM preview_environments WHERE id = $1
+`
+
+func (q *Queries) GetPreviewServiceID(ctx context.Context, id uuid.UUID) (uuid.NullUUID, error) {
+	row := q.db.QueryRowContext(ctx, getPreviewServiceID, id)
+	var preview_service_id uuid.NullUUID
+	err := row.Scan(&preview_service_id)
+	return preview_service_id, err
+}
+
+const getProjectBrief = `-- name: GetProjectBrief :one
+SELECT id, name, owner_id FROM projects WHERE id = $1
+`
+
+type GetProjectBriefRow struct {
+	ID      uuid.UUID `json:"id"`
+	Name    string    `json:"name"`
+	OwnerID uuid.UUID `json:"owner_id"`
+}
+
+func (q *Queries) GetProjectBrief(ctx context.Context, id uuid.UUID) (GetProjectBriefRow, error) {
+	row := q.db.QueryRowContext(ctx, getProjectBrief, id)
+	var i GetProjectBriefRow
+	err := row.Scan(&i.ID, &i.Name, &i.OwnerID)
+	return i, err
+}
+
+const getServiceForDeploy = `-- name: GetServiceForDeploy :one
+SELECT s.id, s.project_id, s.name, s.type, s.status, s.image, s.command,
+       s.environment, s.git_repo, s.git_branch, s.build_path, s.cpu, s.memory,
+       COALESCE(s.replicas, 1) AS replicas, COALESCE(s.port, 0) AS port,
+       COALESCE(s.domain, '') AS domain, COALESCE(s.healthcheck_path, '') AS healthcheck_path,
+       COALESCE(s.restart_policy, 'unless-stopped') AS restart_policy,
+       COALESCE(s.builder, 'auto') AS builder, COALESCE(s.cpu_reserve, '') AS cpu_reserve,
+       COALESCE(s.memory_reserve, '') AS memory_reserve, COALESCE(s.static_build_cmd, '') AS static_build_cmd,
+       COALESCE(s.static_dir, '') AS static_dir,
+       s.created_at, s.updated_at
+FROM services s
+WHERE s.id = $1
+`
+
+type GetServiceForDeployRow struct {
+	ID              uuid.UUID      `json:"id"`
+	ProjectID       uuid.UUID      `json:"project_id"`
+	Name            string         `json:"name"`
+	Type            sql.NullString `json:"type"`
+	Status          sql.NullString `json:"status"`
+	Image           sql.NullString `json:"image"`
+	Command         sql.NullString `json:"command"`
+	Environment     sql.NullString `json:"environment"`
+	GitRepo         sql.NullString `json:"git_repo"`
+	GitBranch       sql.NullString `json:"git_branch"`
+	BuildPath       sql.NullString `json:"build_path"`
+	Cpu             sql.NullString `json:"cpu"`
+	Memory          sql.NullString `json:"memory"`
+	Replicas        int32          `json:"replicas"`
+	Port            int32          `json:"port"`
+	Domain          string         `json:"domain"`
+	HealthcheckPath string         `json:"healthcheck_path"`
+	RestartPolicy   string         `json:"restart_policy"`
+	Builder         string         `json:"builder"`
+	CpuReserve      string         `json:"cpu_reserve"`
+	MemoryReserve   string         `json:"memory_reserve"`
+	StaticBuildCmd  string         `json:"static_build_cmd"`
+	StaticDir       string         `json:"static_dir"`
+	CreatedAt       sql.NullTime   `json:"created_at"`
+	UpdatedAt       sql.NullTime   `json:"updated_at"`
+}
+
+func (q *Queries) GetServiceForDeploy(ctx context.Context, id uuid.UUID) (GetServiceForDeployRow, error) {
+	row := q.db.QueryRowContext(ctx, getServiceForDeploy, id)
+	var i GetServiceForDeployRow
+	err := row.Scan(
+		&i.ID,
+		&i.ProjectID,
+		&i.Name,
+		&i.Type,
+		&i.Status,
+		&i.Image,
+		&i.Command,
+		&i.Environment,
+		&i.GitRepo,
+		&i.GitBranch,
+		&i.BuildPath,
+		&i.Cpu,
+		&i.Memory,
+		&i.Replicas,
+		&i.Port,
+		&i.Domain,
+		&i.HealthcheckPath,
+		&i.RestartPolicy,
+		&i.Builder,
+		&i.CpuReserve,
+		&i.MemoryReserve,
+		&i.StaticBuildCmd,
+		&i.StaticDir,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+	)
+	return i, err
+}
+
+const getServiceTypeBrief = `-- name: GetServiceTypeBrief :one
+SELECT id, name, COALESCE(type, service_type, '') AS service_type FROM services WHERE id = $1 AND project_id = $2
+`
+
+type GetServiceTypeBriefParams struct {
+	ID        uuid.UUID `json:"id"`
+	ProjectID uuid.UUID `json:"project_id"`
+}
+
+type GetServiceTypeBriefRow struct {
+	ID          uuid.UUID `json:"id"`
+	Name        string    `json:"name"`
+	ServiceType string    `json:"service_type"`
+}
+
+func (q *Queries) GetServiceTypeBrief(ctx context.Context, arg GetServiceTypeBriefParams) (GetServiceTypeBriefRow, error) {
+	row := q.db.QueryRowContext(ctx, getServiceTypeBrief, arg.ID, arg.ProjectID)
+	var i GetServiceTypeBriefRow
+	err := row.Scan(&i.ID, &i.Name, &i.ServiceType)
+	return i, err
+}
+
+const insertPendingDeployment = `-- name: InsertPendingDeployment :exec
+INSERT INTO deployments (id, service_id, version, commit_hash, status, created_at, updated_at)
+VALUES ($1, $2, $3, $4, 'pending', NOW(), NOW())
+`
+
+type InsertPendingDeploymentParams struct {
+	ID         uuid.UUID      `json:"id"`
+	ServiceID  uuid.UUID      `json:"service_id"`
+	Version    string         `json:"version"`
+	CommitHash sql.NullString `json:"commit_hash"`
+}
+
+func (q *Queries) InsertPendingDeployment(ctx context.Context, arg InsertPendingDeploymentParams) error {
+	_, err := q.db.ExecContext(ctx, insertPendingDeployment,
+		arg.ID,
+		arg.ServiceID,
+		arg.Version,
+		arg.CommitHash,
+	)
+	return err
+}
+
+const listExpiredPreviewsForUser = `-- name: ListExpiredPreviewsForUser :many
+SELECT pe.id, pe.project_id, pe.service_id, pe.preview_service_id, pe.branch_name, pe.environment
+FROM preview_environments pe
+JOIN projects p ON pe.project_id = p.id
+WHERE (p.owner_id = $1 OR $2::bool) AND pe.expires_at < NOW() AND pe.status != 'expired'
+`
+
+type ListExpiredPreviewsForUserParams struct {
+	OwnerID uuid.UUID `json:"owner_id"`
+	Column2 bool      `json:"column_2"`
+}
+
+type ListExpiredPreviewsForUserRow struct {
+	ID               uuid.UUID     `json:"id"`
+	ProjectID        uuid.UUID     `json:"project_id"`
+	ServiceID        uuid.UUID     `json:"service_id"`
+	PreviewServiceID uuid.NullUUID `json:"preview_service_id"`
+	BranchName       string        `json:"branch_name"`
+	Environment      string        `json:"environment"`
+}
+
+func (q *Queries) ListExpiredPreviewsForUser(ctx context.Context, arg ListExpiredPreviewsForUserParams) ([]ListExpiredPreviewsForUserRow, error) {
+	rows, err := q.db.QueryContext(ctx, listExpiredPreviewsForUser, arg.OwnerID, arg.Column2)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []ListExpiredPreviewsForUserRow{}
+	for rows.Next() {
+		var i ListExpiredPreviewsForUserRow
+		if err := rows.Scan(
+			&i.ID,
+			&i.ProjectID,
+			&i.ServiceID,
+			&i.PreviewServiceID,
+			&i.BranchName,
+			&i.Environment,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listPreviewEnvironmentsForProject = `-- name: ListPreviewEnvironmentsForProject :many
+SELECT pe.id, pe.project_id, pe.service_id, pe.preview_service_id, pe.branch_name, pe.pr_number,
+       pe.environment, pe.status, pe.url, pe.expires_at, pe.created_at, pe.updated_at,
+       s.id AS svc_id, s.name AS service_name, s.type AS service_type
+FROM preview_environments pe
+LEFT JOIN services s ON pe.service_id = s.id
+WHERE pe.project_id = $1
+ORDER BY pe.created_at DESC
+`
+
+type ListPreviewEnvironmentsForProjectRow struct {
+	ID               uuid.UUID      `json:"id"`
+	ProjectID        uuid.UUID      `json:"project_id"`
+	ServiceID        uuid.UUID      `json:"service_id"`
+	PreviewServiceID uuid.NullUUID  `json:"preview_service_id"`
+	BranchName       string         `json:"branch_name"`
+	PrNumber         sql.NullInt32  `json:"pr_number"`
+	Environment      string         `json:"environment"`
+	Status           string         `json:"status"`
+	Url              sql.NullString `json:"url"`
+	ExpiresAt        time.Time      `json:"expires_at"`
+	CreatedAt        sql.NullTime   `json:"created_at"`
+	UpdatedAt        sql.NullTime   `json:"updated_at"`
+	SvcID            uuid.NullUUID  `json:"svc_id"`
+	ServiceName      sql.NullString `json:"service_name"`
+	ServiceType      sql.NullString `json:"service_type"`
+}
+
+func (q *Queries) ListPreviewEnvironmentsForProject(ctx context.Context, projectID uuid.UUID) ([]ListPreviewEnvironmentsForProjectRow, error) {
+	rows, err := q.db.QueryContext(ctx, listPreviewEnvironmentsForProject, projectID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []ListPreviewEnvironmentsForProjectRow{}
+	for rows.Next() {
+		var i ListPreviewEnvironmentsForProjectRow
+		if err := rows.Scan(
+			&i.ID,
+			&i.ProjectID,
+			&i.ServiceID,
+			&i.PreviewServiceID,
+			&i.BranchName,
+			&i.PrNumber,
+			&i.Environment,
+			&i.Status,
+			&i.Url,
+			&i.ExpiresAt,
+			&i.CreatedAt,
+			&i.UpdatedAt,
+			&i.SvcID,
+			&i.ServiceName,
+			&i.ServiceType,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listSweepablePreviews = `-- name: ListSweepablePreviews :many
+SELECT id, preview_service_id FROM preview_environments
+WHERE expires_at < NOW() AND status NOT IN ('expired', 'stopped')
+`
+
+type ListSweepablePreviewsRow struct {
+	ID               uuid.UUID     `json:"id"`
+	PreviewServiceID uuid.NullUUID `json:"preview_service_id"`
+}
+
+func (q *Queries) ListSweepablePreviews(ctx context.Context) ([]ListSweepablePreviewsRow, error) {
+	rows, err := q.db.QueryContext(ctx, listSweepablePreviews)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []ListSweepablePreviewsRow{}
+	for rows.Next() {
+		var i ListSweepablePreviewsRow
+		if err := rows.Scan(&i.ID, &i.PreviewServiceID); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const markPreviewEnvironmentStatus = `-- name: MarkPreviewEnvironmentStatus :exec
+UPDATE preview_environments SET status = $1, updated_at = NOW() WHERE id = $2
+`
+
+type MarkPreviewEnvironmentStatusParams struct {
+	Status string    `json:"status"`
+	ID     uuid.UUID `json:"id"`
+}
+
+func (q *Queries) MarkPreviewEnvironmentStatus(ctx context.Context, arg MarkPreviewEnvironmentStatusParams) error {
+	_, err := q.db.ExecContext(ctx, markPreviewEnvironmentStatus, arg.Status, arg.ID)
+	return err
+}
+
+const syncPreviewStatuses = `-- name: SyncPreviewStatuses :exec
+UPDATE preview_environments pe
+SET status = derived.st, updated_at = NOW()
+FROM (
+    SELECT pe2.id,
+        CASE
+            WHEN s.status IN ('running', 'deployed') THEN 'running'
+            WHEN s.status IN ('failed', 'error') THEN 'failed'
+            WHEN s.status IN ('building', 'deploying', 'queued', 'pending', 'cloning') THEN 'building'
+            ELSE pe2.status
+        END AS st
+    FROM preview_environments pe2
+    JOIN services s ON pe2.preview_service_id = s.id
+) derived
+WHERE pe.id = derived.id
+  AND pe.status IN ('building', 'running', 'failed')
+  AND pe.status <> derived.st
+`
+
+func (q *Queries) SyncPreviewStatuses(ctx context.Context) error {
+	_, err := q.db.ExecContext(ctx, syncPreviewStatuses)
+	return err
+}
+
+const updatePreviewEnvironment = `-- name: UpdatePreviewEnvironment :exec
+UPDATE preview_environments
+SET status = $1, url = $2, expires_at = $3, updated_at = $4
+WHERE id = $5
+`
+
+type UpdatePreviewEnvironmentParams struct {
+	Status    string         `json:"status"`
+	Url       sql.NullString `json:"url"`
+	ExpiresAt time.Time      `json:"expires_at"`
+	UpdatedAt sql.NullTime   `json:"updated_at"`
+	ID        uuid.UUID      `json:"id"`
+}
+
+func (q *Queries) UpdatePreviewEnvironment(ctx context.Context, arg UpdatePreviewEnvironmentParams) error {
+	_, err := q.db.ExecContext(ctx, updatePreviewEnvironment,
+		arg.Status,
+		arg.Url,
+		arg.ExpiresAt,
+		arg.UpdatedAt,
+		arg.ID,
+	)
+	return err
+}
+
+const updateServicePreviewBranch = `-- name: UpdateServicePreviewBranch :exec
+UPDATE services SET git_branch = $1, domain = '', updated_at = NOW() WHERE id = $2
+`
+
+type UpdateServicePreviewBranchParams struct {
+	GitBranch sql.NullString `json:"git_branch"`
+	ID        uuid.UUID      `json:"id"`
+}
+
+func (q *Queries) UpdateServicePreviewBranch(ctx context.Context, arg UpdateServicePreviewBranchParams) error {
+	_, err := q.db.ExecContext(ctx, updateServicePreviewBranch, arg.GitBranch, arg.ID)
+	return err
+}

app/backend/internal/database/sqlcdb/querier.go

@@ -13,12 +13,22 @@ import (
 )
 
 type Querier interface {
+	// Portable bucket bucketing (no TimescaleDB): floor epoch seconds into
+	// bucket-sized buckets, then back to timestamptz.
+	AggregateNodeMetrics(ctx context.Context, arg AggregateNodeMetricsParams) ([]AggregateNodeMetricsRow, error)
+	ClearServiceDomainDefault(ctx context.Context, serviceID uuid.UUID) error
 	ClearServiceNodePins(ctx context.Context, nodeID sql.NullString) (int64, error)
+	CloneServiceDomains(ctx context.Context, arg CloneServiceDomainsParams) error
+	CloneServiceRow(ctx context.Context, arg CloneServiceRowParams) error
+	CloneServiceVariables(ctx context.Context, arg CloneServiceVariablesParams) error
 	CompleteCommand(ctx context.Context, arg CompleteCommandParams) (AgentCommand, error)
+	CountActivePreviewsForBranch(ctx context.Context, arg CountActivePreviewsForBranchParams) (int64, error)
 	CountDatabaseServicesByUserAndName(ctx context.Context, arg CountDatabaseServicesByUserAndNameParams) (int64, error)
 	CountDatabasesUsingBackupTarget(ctx context.Context, targetID sql.NullString) (int64, error)
 	CountEnvironmentServices(ctx context.Context, environmentID uuid.UUID) (int64, error)
 	CountProjectsByUser(ctx context.Context, arg CountProjectsByUserParams) (int64, error)
+	CountServiceDomains(ctx context.Context, serviceID uuid.UUID) (int64, error)
+	CountServicesByName(ctx context.Context, arg CountServicesByNameParams) (int64, error)
 	CountServicesByProjectAndName(ctx context.Context, arg CountServicesByProjectAndNameParams) (int64, error)
 	CountUnreadNotificationsByUser(ctx context.Context, userID uuid.UUID) (int64, error)
 	CreateAgent(ctx context.Context, arg CreateAgentParams) (NodeAgent, error)
@@ -32,7 +42,10 @@ type Querier interface {
 	CreateExternalDatabaseService(ctx context.Context, arg CreateExternalDatabaseServiceParams) error
 	CreateNotification(ctx context.Context, arg CreateNotificationParams) error
 	CreateOutboundWebhook(ctx context.Context, arg CreateOutboundWebhookParams) error
+	CreatePreviewDomain(ctx context.Context, arg CreatePreviewDomainParams) error
+	CreatePreviewEnvironment(ctx context.Context, arg CreatePreviewEnvironmentParams) error
 	CreateProject(ctx context.Context, arg CreateProjectParams) (Project, error)
+	CreateServiceDomain(ctx context.Context, arg CreateServiceDomainParams) (CreateServiceDomainRow, error)
 	CreateServiceFromTemplate(ctx context.Context, arg CreateServiceFromTemplateParams) error
 	CreateUserInvite(ctx context.Context, arg CreateUserInviteParams) (UserInvite, error)
 	CreateUserTemplate(ctx context.Context, arg CreateUserTemplateParams) error
@@ -40,15 +53,19 @@ type Querier interface {
 	CreateWebhookDelivery(ctx context.Context, arg CreateWebhookDeliveryParams) error
 	DatabaseServiceExistsByIDAndUser(ctx context.Context, arg DatabaseServiceExistsByIDAndUserParams) (bool, error)
 	DeleteAgent(ctx context.Context, id string) error
+	DeleteAllServiceDomains(ctx context.Context, serviceID uuid.UUID) error
 	DeleteBackupTargetByIDAndUser(ctx context.Context, arg DeleteBackupTargetByIDAndUserParams) error
 	DeleteBanner(ctx context.Context, id uuid.UUID) error
 	DeleteDatabaseServiceByID(ctx context.Context, id string) error
 	DeleteDatabaseServiceByIDAndUser(ctx context.Context, arg DeleteDatabaseServiceByIDAndUserParams) error
 	DeleteNotificationChannel(ctx context.Context, arg DeleteNotificationChannelParams) (int64, error)
 	DeleteOutboundWebhookByIDAndUser(ctx context.Context, arg DeleteOutboundWebhookByIDAndUserParams) error
+	DeletePreviewEnvironment(ctx context.Context, id uuid.UUID) error
 	DeleteProjectByID(ctx context.Context, projectID uuid.UUID) (int64, error)
 	DeleteProjectEnvironment(ctx context.Context, arg DeleteProjectEnvironmentParams) error
+	DeleteServiceByID(ctx context.Context, id uuid.UUID) error
 	DeleteServiceContainersOnAgent(ctx context.Context, arg DeleteServiceContainersOnAgentParams) error
+	DeleteServiceDomain(ctx context.Context, arg DeleteServiceDomainParams) (int64, error)
 	DeleteUserInvite(ctx context.Context, id uuid.UUID) error
 	DeleteUserTemplate(ctx context.Context, arg DeleteUserTemplateParams) (int64, error)
 	GetActiveAgentAuthTokenByHash(ctx context.Context, tokenHash string) (AgentAuthToken, error)
@@ -67,16 +84,31 @@ type Querier interface {
 	GetLastAgentCommandByType(ctx context.Context, arg GetLastAgentCommandByTypeParams) (AgentCommand, error)
 	GetOutboundWebhookByID(ctx context.Context, id uuid.UUID) (OutboundWebhook, error)
 	GetOutboundWebhookByIDAndUser(ctx context.Context, arg GetOutboundWebhookByIDAndUserParams) (OutboundWebhook, error)
+	GetPreviewEnvironment(ctx context.Context, arg GetPreviewEnvironmentParams) (GetPreviewEnvironmentRow, error)
+	GetPreviewEnvironmentForPromote(ctx context.Context, arg GetPreviewEnvironmentForPromoteParams) (GetPreviewEnvironmentForPromoteRow, error)
+	GetPreviewEnvironmentForWrite(ctx context.Context, arg GetPreviewEnvironmentForWriteParams) (GetPreviewEnvironmentForWriteRow, error)
+	GetPreviewEnvironmentOwner(ctx context.Context, id uuid.UUID) (uuid.UUID, error)
+	GetPreviewServiceID(ctx context.Context, id uuid.UUID) (uuid.NullUUID, error)
+	GetProjectBrief(ctx context.Context, id uuid.UUID) (GetProjectBriefRow, error)
 	GetProjectByIDForUser(ctx context.Context, arg GetProjectByIDForUserParams) (Project, error)
 	GetProjectEnvironmentByName(ctx context.Context, arg GetProjectEnvironmentByNameParams) (Environment, error)
+	GetProjectOwner(ctx context.Context, id uuid.UUID) (uuid.UUID, error)
 	GetProjectOwnerByID(ctx context.Context, projectID uuid.UUID) (uuid.UUID, error)
 	GetProjectOwnerID(ctx context.Context, id uuid.UUID) (uuid.UUID, error)
 	GetProjectRoleForUser(ctx context.Context, arg GetProjectRoleForUserParams) (string, error)
+	GetServiceAccess(ctx context.Context, id uuid.UUID) (GetServiceAccessRow, error)
+	GetServiceDomainDefault(ctx context.Context, serviceID uuid.UUID) (string, error)
+	GetServiceDomainFirst(ctx context.Context, serviceID uuid.UUID) (string, error)
+	GetServiceEnvironment(ctx context.Context, id uuid.UUID) (string, error)
+	GetServiceForDeploy(ctx context.Context, id uuid.UUID) (GetServiceForDeployRow, error)
+	GetServicePlacementBrief(ctx context.Context, id uuid.UUID) (GetServicePlacementBriefRow, error)
 	GetServiceTemplateByID(ctx context.Context, id string) (ServiceTemplate, error)
+	GetServiceTypeBrief(ctx context.Context, arg GetServiceTypeBriefParams) (GetServiceTypeBriefRow, error)
 	GetUserInviteByTokenHash(ctx context.Context, tokenHash string) (UserInvite, error)
 	GetUserTokenByHash(ctx context.Context, tokenHash string) (UserToken, error)
 	InsertAgentHeartbeat(ctx context.Context, arg InsertAgentHeartbeatParams) error
 	InsertNotificationChannel(ctx context.Context, arg InsertNotificationChannelParams) (NotificationChannel, error)
+	InsertPendingDeployment(ctx context.Context, arg InsertPendingDeploymentParams) error
 	InsertProjectEnvironment(ctx context.Context, arg InsertProjectEnvironmentParams) error
 	ListActiveBanners(ctx context.Context) ([]Banner, error)
 	ListAgentAuthTokens(ctx context.Context) ([]AgentAuthToken, error)
@@ -93,11 +125,15 @@ type Querier interface {
 	ListDatabaseServicesByUser(ctx context.Context, userID string) ([]DatabaseService, error)
 	ListDueDatabaseBackups(ctx context.Context) ([]ListDueDatabaseBackupsRow, error)
 	ListEnabledOutboundWebhooks(ctx context.Context) ([]OutboundWebhook, error)
+	ListExpiredPreviewsForUser(ctx context.Context, arg ListExpiredPreviewsForUserParams) ([]ListExpiredPreviewsForUserRow, error)
+	ListInstanceMetrics(ctx context.Context, arg ListInstanceMetricsParams) ([]ListInstanceMetricsRow, error)
+	ListNodeMetrics(ctx context.Context, arg ListNodeMetricsParams) ([]ListNodeMetricsRow, error)
 	ListNotificationChannelsByUser(ctx context.Context, userID uuid.UUID) ([]NotificationChannel, error)
 	ListNotificationsByUser(ctx context.Context, arg ListNotificationsByUserParams) ([]Notification, error)
 	ListOutboundWebhooksByUser(ctx context.Context, userID uuid.UUID) ([]OutboundWebhook, error)
 	ListPendingCommands(ctx context.Context, nodeAgentID string) ([]AgentCommand, error)
 	ListPendingProjects(ctx context.Context) ([]Project, error)
+	ListPreviewEnvironmentsForProject(ctx context.Context, projectID uuid.UUID) ([]ListPreviewEnvironmentsForProjectRow, error)
 	ListProjectEnvironments(ctx context.Context, projectID uuid.UUID) ([]ListProjectEnvironmentsRow, error)
 	// Visibility model: a project is readable when it is approved for public
 	// display, when the caller owns or is a member of it, or when the caller is a
@@ -112,14 +148,19 @@ type Querier interface {
 	// Distinct agents holding inventory rows for a service.
 	ListServiceAgents(ctx context.Context, serviceID string) ([]string, error)
 	ListServiceContainers(ctx context.Context, serviceID string) ([]ListServiceContainersRow, error)
+	ListServiceDomains(ctx context.Context, serviceID uuid.UUID) ([]ServiceDomain, error)
+	ListServiceMetrics(ctx context.Context, arg ListServiceMetricsParams) ([]ListServiceMetricsRow, error)
 	ListServiceTemplatesByCategoryForUser(ctx context.Context, arg ListServiceTemplatesByCategoryForUserParams) ([]ServiceTemplate, error)
 	ListServiceTemplatesForUser(ctx context.Context, ownerID uuid.NullUUID) ([]ServiceTemplate, error)
+	ListSweepablePreviews(ctx context.Context) ([]ListSweepablePreviewsRow, error)
 	ListUserInvites(ctx context.Context) ([]UserInvite, error)
 	ListUserTokens(ctx context.Context, userID uuid.UUID) ([]UserToken, error)
 	ListWebhookDeliveriesByWebhook(ctx context.Context, webhookID uuid.UUID) ([]WebhookDelivery, error)
 	MarkAllNotificationsReadByUser(ctx context.Context, arg MarkAllNotificationsReadByUserParams) error
 	MarkNotificationReadByIDAndUser(ctx context.Context, arg MarkNotificationReadByIDAndUserParams) error
+	MarkPreviewEnvironmentStatus(ctx context.Context, arg MarkPreviewEnvironmentStatusParams) error
 	MarkUserInviteUsed(ctx context.Context, arg MarkUserInviteUsedParams) error
+	MoveServiceProject(ctx context.Context, arg MoveServiceProjectParams) (int64, error)
 	// Resource-aware: lowest memory utilisation first, then cpu, then container
 	// count. Agents without telemetry sort last (NULL → worst score).
 	PickLeastLoadedAgent(ctx context.Context) (string, error)
@@ -129,6 +170,7 @@ type Querier interface {
 	RevokeAgentAuthToken(ctx context.Context, id uuid.UUID) (AgentAuthToken, error)
 	RevokeUserToken(ctx context.Context, arg RevokeUserTokenParams) (int64, error)
 	ScrubCommandPayload(ctx context.Context, arg ScrubCommandPayloadParams) error
+	ServiceWriteAccess(ctx context.Context, arg ServiceWriteAccessParams) (bool, error)
 	SetAgentDefaultDomain(ctx context.Context, arg SetAgentDefaultDomainParams) error
 	SetAgentSchedulable(ctx context.Context, arg SetAgentSchedulableParams) error
 	SetAgentTags(ctx context.Context, arg SetAgentTagsParams) error
@@ -142,7 +184,11 @@ type Querier interface {
 	SetDatabaseServiceStatusByID(ctx context.Context, arg SetDatabaseServiceStatusByIDParams) error
 	SetDatabaseServiceStatusByIDAndUser(ctx context.Context, arg SetDatabaseServiceStatusByIDAndUserParams) error
 	SetProjectApproved(ctx context.Context, arg SetProjectApprovedParams) (int64, error)
+	SetServiceDomainDefault(ctx context.Context, arg SetServiceDomainDefaultParams) (int64, error)
+	SetServiceLegacyDomain(ctx context.Context, arg SetServiceLegacyDomainParams) error
+	SyncPreviewStatuses(ctx context.Context) error
 	TouchAgentAuthToken(ctx context.Context, tokenHash string) error
+	TouchServiceDomainChecked(ctx context.Context, id uuid.UUID) error
 	TouchUserToken(ctx context.Context, id uuid.UUID) error
 	UpdateAgent(ctx context.Context, arg UpdateAgentParams) (NodeAgent, error)
 	UpdateAgentHeartbeat(ctx context.Context, arg UpdateAgentHeartbeatParams) error
@@ -160,11 +206,16 @@ type Querier interface {
 	UpdateDatabaseServiceNameByIDAndUser(ctx context.Context, arg UpdateDatabaseServiceNameByIDAndUserParams) error
 	UpdateDatabaseServicePlanByIDAndUser(ctx context.Context, arg UpdateDatabaseServicePlanByIDAndUserParams) error
 	UpdateOutboundWebhook(ctx context.Context, arg UpdateOutboundWebhookParams) error
+	UpdatePreviewEnvironment(ctx context.Context, arg UpdatePreviewEnvironmentParams) error
 	UpdateProjectByID(ctx context.Context, arg UpdateProjectByIDParams) (int64, error)
+	UpdateServicePreviewBranch(ctx context.Context, arg UpdateServicePreviewBranchParams) error
 	UpdateUserTemplate(ctx context.Context, arg UpdateUserTemplateParams) (int64, error)
 	UpdateWebhookDeliveryResult(ctx context.Context, arg UpdateWebhookDeliveryResultParams) error
 	UpsertEnvironmentVariable(ctx context.Context, arg UpsertEnvironmentVariableParams) error
+	UpsertInstanceMetrics(ctx context.Context, arg UpsertInstanceMetricsParams) error
+	UpsertNodeMetrics(ctx context.Context, arg UpsertNodeMetricsParams) error
 	UpsertServiceContainer(ctx context.Context, arg UpsertServiceContainerParams) error
+	UpsertServiceMetrics(ctx context.Context, arg UpsertServiceMetricsParams) error
 	UpsertServiceTemplate(ctx context.Context, arg UpsertServiceTemplateParams) error
 }
 

app/backend/internal/database/sqlcdb/service_ops.sql.go

@@ -0,0 +1,158 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: service_ops.sql
+
+package sqlcdb
+
+import (
+	"context"
+	"database/sql"
+
+	"github.com/google/uuid"
+)
+
+const cloneServiceDomains = `-- name: CloneServiceDomains :exec
+INSERT INTO service_domains (service_id, domain, is_default, cert_type)
+SELECT $1, domain, is_default, cert_type FROM service_domains sd WHERE sd.service_id = $2
+`
+
+type CloneServiceDomainsParams struct {
+	ServiceID   uuid.UUID `json:"service_id"`
+	ServiceID_2 uuid.UUID `json:"service_id_2"`
+}
+
+func (q *Queries) CloneServiceDomains(ctx context.Context, arg CloneServiceDomainsParams) error {
+	_, err := q.db.ExecContext(ctx, cloneServiceDomains, arg.ServiceID, arg.ServiceID_2)
+	return err
+}
+
+const cloneServiceRow = `-- name: CloneServiceRow :exec
+INSERT INTO services
+    (id, project_id, name, environment_id, service_type, source_type, source_url, image_name,
+     build_command, start_command, type, status, image, command, environment,
+     git_repo, git_branch, build_path, cpu, memory, replicas, port, domain,
+     healthcheck_path, restart_policy, volumes, maintenance_mode, basic_auth_users,
+     builder, cpu_reserve, memory_reserve, static_build_cmd, static_dir,
+     traefik_labels, created_at, updated_at)
+SELECT $1, $2, $3, $4, service_type, source_type, source_url, image_name,
+     build_command, start_command, type, 'stopped', image, command, $5,
+     git_repo, git_branch, build_path, cpu, memory, replicas, port, domain,
+     healthcheck_path, restart_policy, volumes, $6, $7,
+     builder, cpu_reserve, memory_reserve, static_build_cmd, static_dir,
+     traefik_labels, $8, $8
+FROM services s WHERE s.id = $9
+`
+
+type CloneServiceRowParams struct {
+	ID              uuid.UUID      `json:"id"`
+	ProjectID       uuid.UUID      `json:"project_id"`
+	Name            string         `json:"name"`
+	EnvironmentID   uuid.UUID      `json:"environment_id"`
+	Environment     sql.NullString `json:"environment"`
+	MaintenanceMode bool           `json:"maintenance_mode"`
+	BasicAuthUsers  string         `json:"basic_auth_users"`
+	CreatedAt       sql.NullTime   `json:"created_at"`
+	ID_2            uuid.UUID      `json:"id_2"`
+}
+
+func (q *Queries) CloneServiceRow(ctx context.Context, arg CloneServiceRowParams) error {
+	_, err := q.db.ExecContext(ctx, cloneServiceRow,
+		arg.ID,
+		arg.ProjectID,
+		arg.Name,
+		arg.EnvironmentID,
+		arg.Environment,
+		arg.MaintenanceMode,
+		arg.BasicAuthUsers,
+		arg.CreatedAt,
+		arg.ID_2,
+	)
+	return err
+}
+
+const cloneServiceVariables = `-- name: CloneServiceVariables :exec
+INSERT INTO environment_variables (id, service_id, key, value, is_secret)
+SELECT gen_random_uuid(), $1, key, value, is_secret FROM environment_variables ev WHERE ev.service_id = $2
+`
+
+type CloneServiceVariablesParams struct {
+	ServiceID   uuid.UUID `json:"service_id"`
+	ServiceID_2 uuid.UUID `json:"service_id_2"`
+}
+
+func (q *Queries) CloneServiceVariables(ctx context.Context, arg CloneServiceVariablesParams) error {
+	_, err := q.db.ExecContext(ctx, cloneServiceVariables, arg.ServiceID, arg.ServiceID_2)
+	return err
+}
+
+const countServicesByName = `-- name: CountServicesByName :one
+SELECT COUNT(*) FROM services WHERE project_id = $1 AND name = $2
+`
+
+type CountServicesByNameParams struct {
+	ProjectID uuid.UUID `json:"project_id"`
+	Name      string    `json:"name"`
+}
+
+func (q *Queries) CountServicesByName(ctx context.Context, arg CountServicesByNameParams) (int64, error) {
+	row := q.db.QueryRowContext(ctx, countServicesByName, arg.ProjectID, arg.Name)
+	var count int64
+	err := row.Scan(&count)
+	return count, err
+}
+
+const deleteServiceByID = `-- name: DeleteServiceByID :exec
+DELETE FROM services WHERE id = $1
+`
+
+func (q *Queries) DeleteServiceByID(ctx context.Context, id uuid.UUID) error {
+	_, err := q.db.ExecContext(ctx, deleteServiceByID, id)
+	return err
+}
+
+const getProjectOwner = `-- name: GetProjectOwner :one
+SELECT owner_id FROM projects WHERE id = $1
+`
+
+func (q *Queries) GetProjectOwner(ctx context.Context, id uuid.UUID) (uuid.UUID, error) {
+	row := q.db.QueryRowContext(ctx, getProjectOwner, id)
+	var owner_id uuid.UUID
+	err := row.Scan(&owner_id)
+	return owner_id, err
+}
+
+const getServiceEnvironment = `-- name: GetServiceEnvironment :one
+SELECT COALESCE(environment, '') FROM services WHERE id = $1
+`
+
+func (q *Queries) GetServiceEnvironment(ctx context.Context, id uuid.UUID) (string, error) {
+	row := q.db.QueryRowContext(ctx, getServiceEnvironment, id)
+	var environment string
+	err := row.Scan(&environment)
+	return environment, err
+}
+
+const moveServiceProject = `-- name: MoveServiceProject :execrows
+UPDATE services SET project_id = $1, environment_id = $2, updated_at = $3 WHERE id = $4
+`
+
+type MoveServiceProjectParams struct {
+	ProjectID     uuid.UUID    `json:"project_id"`
+	EnvironmentID uuid.UUID    `json:"environment_id"`
+	UpdatedAt     sql.NullTime `json:"updated_at"`
+	ID            uuid.UUID    `json:"id"`
+}
+
+func (q *Queries) MoveServiceProject(ctx context.Context, arg MoveServiceProjectParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, moveServiceProject,
+		arg.ProjectID,
+		arg.EnvironmentID,
+		arg.UpdatedAt,
+		arg.ID,
+	)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}

app/backend/internal/metrics/storage.go

@@ -4,293 +4,286 @@ import (
 	"context"
 	"database/sql"
 	"fmt"
+	"strconv"
 	"sync"
 	"time"
 
+	"containr/internal/database/sqlcdb"
+
 	_ "github.com/lib/pq"
 )
 
 // PostgreSQLMetricsStorage implements MetricsStorage using PostgreSQL
+// through sqlc-generated queries (sqlc/queries/metrics.sql).
+//
+// Per-container node metrics are deliberately not persisted: the
+// container_metrics table belongs to the container_instances model and
+// has no place for the node/container samples collected here. Node and
+// service/instance rows map cleanly, so those are stored.
 type PostgreSQLMetricsStorage struct {
-	db *sql.DB
+	q *sqlcdb.Queries
 }
 
 // NewPostgreSQLMetricsStorage creates a new PostgreSQL metrics storage
 func NewPostgreSQLMetricsStorage(db *sql.DB) *PostgreSQLMetricsStorage {
-	return &PostgreSQLMetricsStorage{db: db}
+	return &PostgreSQLMetricsStorage{q: sqlcdb.New(db)}
 }
 
+func numStr(v float64) sql.NullString {
+	return sql.NullString{String: strconv.FormatFloat(v, 'f', -1, 64), Valid: true}
+}
+
+func int64N(v int64) sql.NullInt64 {
+	return sql.NullInt64{Int64: v, Valid: true}
+}
+
+func int32N(v int64) sql.NullInt32 {
+	return sql.NullInt32{Int32: int32(v), Valid: true}
+}
+
+func strN(v string) sql.NullString {
+	return sql.NullString{String: v, Valid: v != ""}
+}
+
+func timeN(t time.Time) sql.NullTime {
+	return sql.NullTime{Time: t, Valid: !t.IsZero()}
+}
+
+func f64v(n sql.NullString) float64 {
+	f, _ := strconv.ParseFloat(n.String, 64)
+	return f
+}
+
+func i64v(n sql.NullInt64) int64 { return n.Int64 }
+
+func i32v(n sql.NullInt32) int64 { return int64(n.Int32) }
+
 // StoreNodeMetrics stores node metrics in the database
 func (s *PostgreSQLMetricsStorage) StoreNodeMetrics(ctx context.Context, metrics *NodeMetrics) error {
-	query := `
-		INSERT INTO node_metrics (
-			node_id, timestamp, cpu_usage, cpu_cores, load_avg_1, load_avg_5, load_avg_15,
-			memory_total, memory_used, memory_available, memory_usage_percent,
-			storage_total, storage_used, storage_available, storage_usage_percent,
-			network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
-			network_connections_in, network_connections_out, network_errors_in, network_errors_out,
-			uptime, processes, os, kernel, architecture
-		) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21, $22, $23, $24, $25, $26, $27, $28)
-		ON CONFLICT (node_id, timestamp) DO UPDATE SET
-			cpu_usage = EXCLUDED.cpu_usage,
-			cpu_cores = EXCLUDED.cpu_cores,
-			load_avg_1 = EXCLUDED.load_avg_1,
-			load_avg_5 = EXCLUDED.load_avg_5,
-			load_avg_15 = EXCLUDED.load_avg_15,
-			memory_total = EXCLUDED.memory_total,
-			memory_used = EXCLUDED.memory_used,
-			memory_available = EXCLUDED.memory_available,
-			memory_usage_percent = EXCLUDED.memory_usage_percent,
-			storage_total = EXCLUDED.storage_total,
-			storage_used = EXCLUDED.storage_used,
-			storage_available = EXCLUDED.storage_available,
-			storage_usage_percent = EXCLUDED.storage_usage_percent,
-			network_bytes_in = EXCLUDED.network_bytes_in,
-			network_bytes_out = EXCLUDED.network_bytes_out,
-			network_packets_in = EXCLUDED.network_packets_in,
-			network_packets_out = EXCLUDED.network_packets_out,
-			network_connections_in = EXCLUDED.network_connections_in,
-			network_connections_out = EXCLUDED.network_connections_out,
-			network_errors_in = EXCLUDED.network_errors_in,
-			network_errors_out = EXCLUDED.network_errors_out,
-			uptime = EXCLUDED.uptime,
-			processes = EXCLUDED.processes,
-			os = EXCLUDED.os,
-			kernel = EXCLUDED.kernel,
-			architecture = EXCLUDED.architecture
-	`
-
-	_, err := s.db.ExecContext(ctx, query,
-		metrics.NodeID, metrics.Timestamp, metrics.CPU.UsagePercent, metrics.CPU.UsageCores,
-		metrics.CPU.LoadAverage1, metrics.CPU.LoadAverage5, metrics.CPU.LoadAverage15,
-		metrics.Memory.Total, metrics.Memory.Used, metrics.Memory.Available, metrics.Memory.UsagePercent,
-		metrics.Storage.Total, metrics.Storage.Used, metrics.Storage.Available, metrics.Storage.UsagePercent,
-		metrics.Network.BytesIn, metrics.Network.BytesOut, metrics.Network.PacketsIn, metrics.Network.PacketsOut,
-		metrics.Network.ConnectionsIn, metrics.Network.ConnectionsOut, metrics.Network.ErrorsIn, metrics.Network.ErrorsOut,
-		metrics.System.Uptime, metrics.System.Processes, metrics.System.OS, metrics.System.Kernel, metrics.System.Architecture,
-	)
-
+	err := s.q.UpsertNodeMetrics(ctx, sqlcdb.UpsertNodeMetricsParams{
+		NodeID:                metrics.NodeID,
+		Timestamp:             metrics.Timestamp,
+		CpuUsage:              numStr(metrics.CPU.UsagePercent),
+		CpuCores:              numStr(metrics.CPU.UsageCores),
+		LoadAvg1:              numStr(metrics.CPU.LoadAverage1),
+		LoadAvg5:              numStr(metrics.CPU.LoadAverage5),
+		LoadAvg15:             numStr(metrics.CPU.LoadAverage15),
+		MemoryTotal:           int64N(metrics.Memory.Total),
+		MemoryUsed:            int64N(metrics.Memory.Used),
+		MemoryAvailable:       int64N(metrics.Memory.Available),
+		MemoryUsagePercent:    numStr(metrics.Memory.UsagePercent),
+		StorageTotal:          int64N(metrics.Storage.Total),
+		StorageUsed:           int64N(metrics.Storage.Used),
+		StorageAvailable:      int64N(metrics.Storage.Available),
+		StorageUsagePercent:   numStr(metrics.Storage.UsagePercent),
+		NetworkBytesIn:        int64N(metrics.Network.BytesIn),
+		NetworkBytesOut:       int64N(metrics.Network.BytesOut),
+		NetworkPacketsIn:      int64N(metrics.Network.PacketsIn),
+		NetworkPacketsOut:     int64N(metrics.Network.PacketsOut),
+		NetworkConnectionsIn:  int32N(metrics.Network.ConnectionsIn),
+		NetworkConnectionsOut: int32N(metrics.Network.ConnectionsOut),
+		NetworkErrorsIn:       int64N(metrics.Network.ErrorsIn),
+		NetworkErrorsOut:      int64N(metrics.Network.ErrorsOut),
+		// INTERVAL param — Postgres casts the bigint as seconds.
+		Uptime:       int64N(int64(metrics.System.Uptime.Seconds())),
+		Processes:    sql.NullInt32{Int32: int32(metrics.System.Processes), Valid: true},
+		Os:           strN(metrics.System.OS),
+		Kernel:       strN(metrics.System.Kernel),
+		Architecture: strN(metrics.System.Architecture),
+	})
 	if err != nil {
 		return fmt.Errorf("failed to store node metrics: %w", err)
 	}
-
-	// Store container metrics
-	for _, container := range metrics.Containers {
-		if err := s.storeContainerMetrics(ctx, metrics.NodeID, metrics.Timestamp, container); err != nil {
-			return fmt.Errorf("failed to store container metrics: %w", err)
-		}
-	}
-
 	return nil
 }
 
 // StoreServiceMetrics stores service metrics in the database
 func (s *PostgreSQLMetricsStorage) StoreServiceMetrics(ctx context.Context, metrics *ServiceMetrics) error {
-	query := `
-		INSERT INTO service_metrics (
-			service_id, service_name, project_id, timestamp,
-			requests_total, requests_success, requests_errors, requests_avg_latency,
-			requests_p95_latency, requests_p99_latency, requests_throughput,
-			errors_total, errors_rate, performance_response_time, performance_throughput,
-			performance_concurrency, performance_saturation, performance_utilization,
-			resource_cpu_usage, resource_memory_usage, resource_storage_usage,
-			resource_network_usage, resource_score
-		) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21, $22, $23)
-		ON CONFLICT (service_id, timestamp) DO UPDATE SET
-			requests_total = EXCLUDED.requests_total,
-			requests_success = EXCLUDED.requests_success,
-			requests_errors = EXCLUDED.requests_errors,
-			requests_avg_latency = EXCLUDED.requests_avg_latency,
-			requests_p95_latency = EXCLUDED.requests_p95_latency,
-			requests_p99_latency = EXCLUDED.requests_p99_latency,
-			requests_throughput = EXCLUDED.requests_throughput,
-			errors_total = EXCLUDED.errors_total,
-			errors_rate = EXCLUDED.errors_rate,
-			performance_response_time = EXCLUDED.performance_response_time,
-			performance_throughput = EXCLUDED.performance_throughput,
-			performance_concurrency = EXCLUDED.performance_concurrency,
-			performance_saturation = EXCLUDED.performance_saturation,
-			performance_utilization = EXCLUDED.performance_utilization,
-			resource_cpu_usage = EXCLUDED.resource_cpu_usage,
-			resource_memory_usage = EXCLUDED.resource_memory_usage,
-			resource_storage_usage = EXCLUDED.resource_storage_usage,
-			resource_network_usage = EXCLUDED.resource_network_usage,
-			resource_score = EXCLUDED.resource_score
-	`
-
-	_, err := s.db.ExecContext(ctx, query,
-		metrics.ServiceID, metrics.ServiceName, metrics.ProjectID, metrics.Timestamp,
-		metrics.Requests.Total, metrics.Requests.Success, metrics.Requests.Errors,
-		metrics.Requests.AvgLatency, metrics.Requests.P95Latency, metrics.Requests.P99Latency,
-		metrics.Requests.Throughput, metrics.Errors.Total, metrics.Errors.Rate,
-		metrics.Performance.ResponseTime, metrics.Performance.Throughput,
-		metrics.Performance.Concurrency, metrics.Performance.Saturation, metrics.Performance.Utilization,
-		metrics.Resources.CPUUsage, metrics.Resources.MemoryUsage, metrics.Resources.StorageUsage,
-		metrics.Resources.NetworkUsage, metrics.Resources.ResourceScore,
-	)
-
+	err := s.q.UpsertServiceMetrics(ctx, sqlcdb.UpsertServiceMetricsParams{
+		ServiceID:               metrics.ServiceID,
+		ServiceName:             metrics.ServiceName,
+		ProjectID:               metrics.ProjectID,
+		Timestamp:               metrics.Timestamp,
+		RequestsTotal:           int64N(metrics.Requests.Total),
+		RequestsSuccess:         int64N(metrics.Requests.Success),
+		RequestsErrors:          int64N(metrics.Requests.Errors),
+		RequestsAvgLatency:      numStr(metrics.Requests.AvgLatency),
+		RequestsP95Latency:      numStr(metrics.Requests.P95Latency),
+		RequestsP99Latency:      numStr(metrics.Requests.P99Latency),
+		RequestsThroughput:      numStr(metrics.Requests.Throughput),
+		ErrorsTotal:             int64N(metrics.Errors.Total),
+		ErrorsRate:              numStr(metrics.Errors.Rate),
+		PerformanceResponseTime: numStr(metrics.Performance.ResponseTime),
+		PerformanceThroughput:   numStr(metrics.Performance.Throughput),
+		PerformanceConcurrency:  int64N(metrics.Performance.Concurrency),
+		PerformanceSaturation:   numStr(metrics.Performance.Saturation),
+		PerformanceUtilization:  numStr(metrics.Performance.Utilization),
+		ResourceCpuUsage:        numStr(metrics.Resources.CPUUsage),
+		ResourceMemoryUsage:     int64N(metrics.Resources.MemoryUsage),
+		ResourceStorageUsage:    int64N(metrics.Resources.StorageUsage),
+		ResourceNetworkUsage:    int64N(metrics.Resources.NetworkUsage),
+		ResourceScore:           numStr(metrics.Resources.ResourceScore),
+	})
 	if err != nil {
 		return fmt.Errorf("failed to store service metrics: %w", err)
 	}
 
-	// Store instance metrics
+	// The service row must land first — instance_metrics references
+	// service_metrics(service_id, timestamp).
 	for _, instance := range metrics.Instances {
 		if err := s.storeInstanceMetrics(ctx, metrics.ServiceID, metrics.Timestamp, instance); err != nil {
 			return fmt.Errorf("failed to store instance metrics: %w", err)
 		}
 	}
-
 	return nil
 }
 
 // GetNodeMetrics retrieves node metrics from the database
 func (s *PostgreSQLMetricsStorage) GetNodeMetrics(ctx context.Context, nodeID string, from, to time.Time) ([]*NodeMetrics, error) {
-	query := `
-		SELECT node_id, timestamp, cpu_usage, cpu_cores, load_avg_1, load_avg_5, load_avg_15,
-			   memory_total, memory_used, memory_available, memory_usage_percent,
-			   storage_total, storage_used, storage_available, storage_usage_percent,
-			   network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
-			   network_connections_in, network_connections_out, network_errors_in, network_errors_out,
-			   uptime, processes, os, kernel, architecture
-		FROM node_metrics
-		WHERE node_id = $1 AND timestamp BETWEEN $2 AND $3
-		ORDER BY timestamp ASC
-	`
-
-	rows, err := s.db.QueryContext(ctx, query, nodeID, from, to)
+	rows, err := s.q.ListNodeMetrics(ctx, sqlcdb.ListNodeMetricsParams{
+		NodeID:      nodeID,
+		Timestamp:   from,
+		Timestamp_2: to,
+	})
 	if err != nil {
 		return nil, fmt.Errorf("failed to query node metrics: %w", err)
 	}
-	defer rows.Close()
 
 	var metrics []*NodeMetrics
-	for rows.Next() {
-		var m NodeMetrics
-		err := rows.Scan(
-			&m.NodeID, &m.Timestamp, &m.CPU.UsagePercent, &m.CPU.UsageCores,
-			&m.CPU.LoadAverage1, &m.CPU.LoadAverage5, &m.CPU.LoadAverage15,
-			&m.Memory.Total, &m.Memory.Used, &m.Memory.Available, &m.Memory.UsagePercent,
-			&m.Storage.Total, &m.Storage.Used, &m.Storage.Available, &m.Storage.UsagePercent,
-			&m.Network.BytesIn, &m.Network.BytesOut, &m.Network.PacketsIn, &m.Network.PacketsOut,
-			&m.Network.ConnectionsIn, &m.Network.ConnectionsOut, &m.Network.ErrorsIn, &m.Network.ErrorsOut,
-			&m.System.Uptime, &m.System.Processes, &m.System.OS, &m.System.Kernel, &m.System.Architecture,
-		)
-		if err != nil {
-			return nil, fmt.Errorf("failed to scan node metrics: %w", err)
+	for _, r := range rows {
+		metrics = append(metrics, &NodeMetrics{
+			NodeID:    r.NodeID,
+			Timestamp: r.Timestamp,
+			CPU: CPUMetrics{
+				UsagePercent:  f64v(r.CpuUsage),
+				UsageCores:    f64v(r.CpuCores),
+				LoadAverage1:  f64v(r.LoadAvg1),
+				LoadAverage5:  f64v(r.LoadAvg5),
+				LoadAverage15: f64v(r.LoadAvg15),
+			},
+			Memory: MemoryMetrics{
+				Total:        i64v(r.MemoryTotal),
+				Used:         i64v(r.MemoryUsed),
+				Available:    i64v(r.MemoryAvailable),
+				UsagePercent: f64v(r.MemoryUsagePercent),
+			},
+			Storage: StorageMetrics{
+				Total:        i64v(r.StorageTotal),
+				Used:         i64v(r.StorageUsed),
+				Available:    i64v(r.StorageAvailable),
+				UsagePercent: f64v(r.StorageUsagePercent),
+			},
+			Network: NetworkMetrics{
+				BytesIn:        i64v(r.NetworkBytesIn),
+				BytesOut:       i64v(r.NetworkBytesOut),
+				PacketsIn:      i64v(r.NetworkPacketsIn),
+				PacketsOut:     i64v(r.NetworkPacketsOut),
+				ConnectionsIn:  i32v(r.NetworkConnectionsIn),
+				ConnectionsOut: i32v(r.NetworkConnectionsOut),
+				ErrorsIn:       i64v(r.NetworkErrorsIn),
+				ErrorsOut:      i64v(r.NetworkErrorsOut),
+			},
+			System: SystemMetrics{
+				Uptime:       time.Duration(r.UptimeSeconds) * time.Second,
+				Processes:    int(r.Processes.Int32),
+				OS:           r.Os.String,
+				Kernel:       r.Kernel.String,
+				Architecture: r.Architecture.String,
+			},
+		})
 	}
-
-		// Get container metrics for this timestamp
-		containers, err := s.getContainerMetrics(ctx, nodeID, m.Timestamp)
-		if err != nil {
-			return nil, fmt.Errorf("failed to get container metrics: %w", err)
-		}
-		m.Containers = containers
-
-		metrics = append(metrics, &m)
-	}
-
 	return metrics, nil
 }
 
 // GetServiceMetrics retrieves service metrics from the database
 func (s *PostgreSQLMetricsStorage) GetServiceMetrics(ctx context.Context, serviceID string, from, to time.Time) ([]*ServiceMetrics, error) {
-	query := `
-		SELECT service_id, service_name, project_id, timestamp,
-			   requests_total, requests_success, requests_errors, requests_avg_latency,
-			   requests_p95_latency, requests_p99_latency, requests_throughput,
-			   errors_total, errors_rate, performance_response_time, performance_throughput,
-			   performance_concurrency, performance_saturation, performance_utilization,
-			   resource_cpu_usage, resource_memory_usage, resource_storage_usage,
-			   resource_network_usage, resource_score
-		FROM service_metrics
-		WHERE service_id = $1 AND timestamp BETWEEN $2 AND $3
-		ORDER BY timestamp ASC
-	`
-
-	rows, err := s.db.QueryContext(ctx, query, serviceID, from, to)
+	rows, err := s.q.ListServiceMetrics(ctx, sqlcdb.ListServiceMetricsParams{
+		ServiceID:   serviceID,
+		Timestamp:   from,
+		Timestamp_2: to,
+	})
 	if err != nil {
 		return nil, fmt.Errorf("failed to query service metrics: %w", err)
 	}
-	defer rows.Close()
 
 	var metrics []*ServiceMetrics
-	for rows.Next() {
-		var m ServiceMetrics
-		err := rows.Scan(
-			&m.ServiceID, &m.ServiceName, &m.ProjectID, &m.Timestamp,
-			&m.Requests.Total, &m.Requests.Success, &m.Requests.Errors,
-			&m.Requests.AvgLatency, &m.Requests.P95Latency, &m.Requests.P99Latency,
-			&m.Requests.Throughput, &m.Errors.Total, &m.Errors.Rate,
-			&m.Performance.ResponseTime, &m.Performance.Throughput,
-			&m.Performance.Concurrency, &m.Performance.Saturation, &m.Performance.Utilization,
-			&m.Resources.CPUUsage, &m.Resources.MemoryUsage, &m.Resources.StorageUsage,
-			&m.Resources.NetworkUsage, &m.Resources.ResourceScore,
-		)
-		if err != nil {
-			return nil, fmt.Errorf("failed to scan service metrics: %w", err)
+	for _, r := range rows {
+		m := &ServiceMetrics{
+			ServiceID:   r.ServiceID,
+			ServiceName: r.ServiceName,
+			ProjectID:   r.ProjectID,
+			Timestamp:   r.Timestamp,
+			Requests: RequestMetrics{
+				Total:      i64v(r.RequestsTotal),
+				Success:    i64v(r.RequestsSuccess),
+				Errors:     i64v(r.RequestsErrors),
+				AvgLatency: f64v(r.RequestsAvgLatency),
+				P95Latency: f64v(r.RequestsP95Latency),
+				P99Latency: f64v(r.RequestsP99Latency),
+				Throughput: f64v(r.RequestsThroughput),
+			},
+			Errors: ErrorMetrics{
+				Total: i64v(r.ErrorsTotal),
+				Rate:  f64v(r.ErrorsRate),
+			},
+			Performance: PerformanceMetrics{
+				ResponseTime: f64v(r.PerformanceResponseTime),
+				Throughput:   f64v(r.PerformanceThroughput),
+				Concurrency:  i64v(r.PerformanceConcurrency),
+				Saturation:   f64v(r.PerformanceSaturation),
+				Utilization:  f64v(r.PerformanceUtilization),
+			},
+			Resources: ResourceMetrics{
+				CPUUsage:      f64v(r.ResourceCpuUsage),
+				MemoryUsage:   i64v(r.ResourceMemoryUsage),
+				StorageUsage:  i64v(r.ResourceStorageUsage),
+				NetworkUsage:  i64v(r.ResourceNetworkUsage),
+				ResourceScore: f64v(r.ResourceScore),
+			},
 		}
 
-		// Get instance metrics for this timestamp
-		instances, err := s.getInstanceMetrics(ctx, serviceID, m.Timestamp)
+		instances, err := s.getInstanceMetrics(ctx, serviceID, r.Timestamp)
 		if err != nil {
 			return nil, fmt.Errorf("failed to get instance metrics: %w", err)
 		}
 		m.Instances = instances
-
-		metrics = append(metrics, &m)
+		metrics = append(metrics, m)
 	}
-
 	return metrics, nil
 }
 
-// GetAggregatedMetrics retrieves aggregated metrics based on a query
+// GetAggregatedMetrics retrieves aggregated metrics based on a query.
+// Bucketing uses date_bin (PostgreSQL 14+) — no TimescaleDB needed.
 func (s *PostgreSQLMetricsStorage) GetAggregatedMetrics(ctx context.Context, query MetricsQuery) (*AggregatedMetrics, error) {
-	// This is a simplified implementation
-	// In a real system, you'd build dynamic SQL based on the query
-
 	var timeSeries []TimeSeriesPoint
 	var summary map[string]MetricSummary
 
 	switch query.Type {
 	case "node":
-		// Aggregate node metrics
-		nodeQuery := `
-			SELECT 
-				time_bucket($1, timestamp) AS bucket,
-				AVG(cpu_usage) as avg_cpu,
-				AVG(memory_usage_percent) as avg_memory,
-				AVG(storage_usage_percent) as avg_storage
-			FROM node_metrics
-			WHERE node_id = $2 AND timestamp BETWEEN $3 AND $4
-			GROUP BY bucket
-			ORDER BY bucket ASC
-		`
-
-		rows, err := s.db.QueryContext(ctx, nodeQuery, query.Interval, query.ID, query.From, query.To)
+		seconds := int64(query.Interval.Seconds())
+		if seconds <= 0 {
+			seconds = 300
+		}
+		rows, err := s.q.AggregateNodeMetrics(ctx, sqlcdb.AggregateNodeMetricsParams{
+			Column1:     seconds,
+			NodeID:      query.ID,
+			Timestamp:   query.From,
+			Timestamp_2: query.To,
+		})
 		if err != nil {
 			return nil, fmt.Errorf("failed to query aggregated node metrics: %w", err)
 		}
-		defer rows.Close()
-
-		for rows.Next() {
-			var bucket time.Time
-			var avgCPU, avgMemory, avgStorage float64
-			if err := rows.Scan(&bucket, &avgCPU, &avgMemory, &avgStorage); err != nil {
-				return nil, fmt.Errorf("failed to scan aggregated metrics: %w", err)
-			}
-
-			point := TimeSeriesPoint{
+		for _, r := range rows {
+			bucket, _ := r.Bucket.(time.Time)
+			timeSeries = append(timeSeries, TimeSeriesPoint{
 				Timestamp: bucket,
 				Values: map[string]float64{
-					"cpu_usage":     avgCPU,
-					"memory_usage":  avgMemory,
-					"storage_usage": avgStorage,
+					"cpu_usage":     r.AvgCpu,
+					"memory_usage":  r.AvgMemory,
+					"storage_usage": r.AvgStorage,
 				},
+			})
 		}
-			timeSeries = append(timeSeries, point)
-		}
-
-		// Calculate summary statistics
 		summary = map[string]MetricSummary{
 			"cpu_usage":     calculateSummary(timeSeries, "cpu_usage"),
 			"memory_usage":  calculateSummary(timeSeries, "memory_usage"),
@@ -305,137 +298,69 @@ func (s *PostgreSQLMetricsStorage) GetAggregatedMetrics(ctx context.Context, que
 	}, nil
 }
 
-// Helper methods
-
-func (s *PostgreSQLMetricsStorage) storeContainerMetrics(ctx context.Context, nodeID string, timestamp time.Time, container ContainerMetrics) error {
-	query := `
-		INSERT INTO container_metrics (
-			node_id, timestamp, container_id, name, state, cpu, memory,
-			network_bytes_in, network_bytes_out, network_packets_in, network_packets_out, start_time
-		) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
-		ON CONFLICT (node_id, timestamp, container_id) DO UPDATE SET
-			name = EXCLUDED.name,
-			state = EXCLUDED.state,
-			cpu = EXCLUDED.cpu,
-			memory = EXCLUDED.memory,
-			network_bytes_in = EXCLUDED.network_bytes_in,
-			network_bytes_out = EXCLUDED.network_bytes_out,
-			network_packets_in = EXCLUDED.network_packets_in,
-			network_packets_out = EXCLUDED.network_packets_out,
-			start_time = EXCLUDED.start_time
-	`
-
-	_, err := s.db.ExecContext(ctx, query,
-		nodeID, timestamp, container.ContainerID, container.Name, container.State,
-		container.CPU, container.Memory, container.Network.BytesIn, container.Network.BytesOut,
-		container.Network.PacketsIn, container.Network.PacketsOut, container.StartTime,
-	)
-
-	return err
-}
-
 func (s *PostgreSQLMetricsStorage) storeInstanceMetrics(ctx context.Context, serviceID string, timestamp time.Time, instance InstanceMetrics) error {
-	query := `
-		INSERT INTO instance_metrics (
-			service_id, timestamp, instance_id, node_id, status, cpu, memory,
-			network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
-			network_connections_in, network_connections_out, network_errors_in, network_errors_out,
-			start_time, last_seen, health_status, health_last_check, health_check_count, health_failure_count
-		) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21)
-		ON CONFLICT (service_id, timestamp, instance_id) DO UPDATE SET
-			node_id = EXCLUDED.node_id,
-			status = EXCLUDED.status,
-			cpu = EXCLUDED.cpu,
-			memory = EXCLUDED.memory,
-			network_bytes_in = EXCLUDED.network_bytes_in,
-			network_bytes_out = EXCLUDED.network_bytes_out,
-			network_packets_in = EXCLUDED.network_packets_in,
-			network_packets_out = EXCLUDED.network_packets_out,
-			network_connections_in = EXCLUDED.network_connections_in,
-			network_connections_out = EXCLUDED.network_connections_out,
-			network_errors_in = EXCLUDED.network_errors_in,
-			network_errors_out = EXCLUDED.network_errors_out,
-			start_time = EXCLUDED.start_time,
-			last_seen = EXCLUDED.last_seen,
-			health_status = EXCLUDED.health_status,
-			health_last_check = EXCLUDED.health_last_check,
-			health_check_count = EXCLUDED.health_check_count,
-			health_failure_count = EXCLUDED.health_failure_count
-	`
-
-	_, err := s.db.ExecContext(ctx, query,
-		serviceID, timestamp, instance.InstanceID, instance.NodeID, instance.Status,
-		instance.CPU, instance.Memory, instance.Network.BytesIn, instance.Network.BytesOut,
-		instance.Network.PacketsIn, instance.Network.PacketsOut, instance.Network.ConnectionsIn,
-		instance.Network.ConnectionsOut, instance.Network.ErrorsIn, instance.Network.ErrorsOut,
-		instance.StartTime, instance.LastSeen, instance.Health.Status, instance.Health.LastCheck,
-		instance.Health.CheckCount, instance.Health.FailureCount,
-	)
-
-	return err
-}
-
-func (s *PostgreSQLMetricsStorage) getContainerMetrics(ctx context.Context, nodeID string, timestamp time.Time) ([]ContainerMetrics, error) {
-	query := `
-		SELECT container_id, name, state, cpu, memory,
-			   network_bytes_in, network_bytes_out, network_packets_in, network_packets_out, start_time
-		FROM container_metrics
-		WHERE node_id = $1 AND timestamp = $2
-	`
-
-	rows, err := s.db.QueryContext(ctx, query, nodeID, timestamp)
-	if err != nil {
-		return nil, err
-	}
-	defer rows.Close()
-
-	var containers []ContainerMetrics
-	for rows.Next() {
-		var c ContainerMetrics
-		err := rows.Scan(
-			&c.ContainerID, &c.Name, &c.State, &c.CPU, &c.Memory,
-			&c.Network.BytesIn, &c.Network.BytesOut, &c.Network.PacketsIn, &c.Network.PacketsOut, &c.StartTime,
-		)
-		if err != nil {
-			return nil, err
-		}
-		containers = append(containers, c)
-	}
-
-	return containers, nil
+	return s.q.UpsertInstanceMetrics(ctx, sqlcdb.UpsertInstanceMetricsParams{
+		ServiceID:             serviceID,
+		Timestamp:             timestamp,
+		InstanceID:            instance.InstanceID,
+		NodeID:                strN(instance.NodeID),
+		Status:                strN(instance.Status),
+		Cpu:                   numStr(instance.CPU),
+		Memory:                int64N(instance.Memory),
+		NetworkBytesIn:        int64N(instance.Network.BytesIn),
+		NetworkBytesOut:       int64N(instance.Network.BytesOut),
+		NetworkPacketsIn:      int64N(instance.Network.PacketsIn),
+		NetworkPacketsOut:     int64N(instance.Network.PacketsOut),
+		NetworkConnectionsIn:  int32N(instance.Network.ConnectionsIn),
+		NetworkConnectionsOut: int32N(instance.Network.ConnectionsOut),
+		NetworkErrorsIn:       int64N(instance.Network.ErrorsIn),
+		NetworkErrorsOut:      int64N(instance.Network.ErrorsOut),
+		StartTime:             timeN(instance.StartTime),
+		LastSeen:              timeN(instance.LastSeen),
+		HealthStatus:          strN(instance.Health.Status),
+		HealthLastCheck:       timeN(instance.Health.LastCheck),
+		HealthCheckCount:      sql.NullInt32{Int32: int32(instance.Health.CheckCount), Valid: true},
+		HealthFailureCount:    sql.NullInt32{Int32: int32(instance.Health.FailureCount), Valid: true},
+	})
 }
 
 func (s *PostgreSQLMetricsStorage) getInstanceMetrics(ctx context.Context, serviceID string, timestamp time.Time) ([]InstanceMetrics, error) {
-	query := `
-		SELECT instance_id, node_id, status, cpu, memory,
-			   network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
-			   network_connections_in, network_connections_out, network_errors_in, network_errors_out,
-			   start_time, last_seen, health_status, health_last_check, health_check_count, health_failure_count
-		FROM instance_metrics
-		WHERE service_id = $1 AND timestamp = $2
-	`
-
-	rows, err := s.db.QueryContext(ctx, query, serviceID, timestamp)
+	rows, err := s.q.ListInstanceMetrics(ctx, sqlcdb.ListInstanceMetricsParams{
+		ServiceID: serviceID,
+		Timestamp: timestamp,
+	})
 	if err != nil {
 		return nil, err
 	}
-	defer rows.Close()
 
 	var instances []InstanceMetrics
-	for rows.Next() {
-		var i InstanceMetrics
-		err := rows.Scan(
-			&i.InstanceID, &i.NodeID, &i.Status, &i.CPU, &i.Memory,
-			&i.Network.BytesIn, &i.Network.BytesOut, &i.Network.PacketsIn, &i.Network.PacketsOut,
-			&i.Network.ConnectionsIn, &i.Network.ConnectionsOut, &i.Network.ErrorsIn, &i.Network.ErrorsOut,
-			&i.StartTime, &i.LastSeen, &i.Health.Status, &i.Health.LastCheck, &i.Health.CheckCount, &i.Health.FailureCount,
-		)
-		if err != nil {
-			return nil, err
+	for _, r := range rows {
+		instances = append(instances, InstanceMetrics{
+			InstanceID: r.InstanceID,
+			NodeID:     r.NodeID.String,
+			Status:     r.Status.String,
+			CPU:        f64v(r.Cpu),
+			Memory:     i64v(r.Memory),
+			Network: NetworkMetrics{
+				BytesIn:        i64v(r.NetworkBytesIn),
+				BytesOut:       i64v(r.NetworkBytesOut),
+				PacketsIn:      i64v(r.NetworkPacketsIn),
+				PacketsOut:     i64v(r.NetworkPacketsOut),
+				ConnectionsIn:  i32v(r.NetworkConnectionsIn),
+				ConnectionsOut: i32v(r.NetworkConnectionsOut),
+				ErrorsIn:       i64v(r.NetworkErrorsIn),
+				ErrorsOut:      i64v(r.NetworkErrorsOut),
+			},
+			StartTime: r.StartTime.Time,
+			LastSeen:  r.LastSeen.Time,
+			Health: HealthMetrics{
+				Status:       r.HealthStatus.String,
+				LastCheck:    r.HealthLastCheck.Time,
+				CheckCount:   int(r.HealthCheckCount.Int32),
+				FailureCount: int(r.HealthFailureCount.Int32),
+			},
+		})
 	}
-		instances = append(instances, i)
-	}
-
 	return instances, nil
 }
 
@@ -544,7 +469,9 @@ func (s *InMemoryMetricsStorage) GetServiceMetrics(ctx context.Context, serviceI
 }
 
 func (s *InMemoryMetricsStorage) GetAggregatedMetrics(ctx context.Context, query MetricsQuery) (*AggregatedMetrics, error) {
-	// Simplified implementation
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
 	return &AggregatedMetrics{
 		Query:      query,
 		TimeSeries: []TimeSeriesPoint{},

app/backend/internal/metrics/storage_test.go

@@ -0,0 +1,130 @@
+package metrics
+
+import (
+	"context"
+	"database/sql"
+	"os"
+	"testing"
+	"time"
+)
+
+// Live round-trip against a real Postgres — set METRICS_TEST_DSN (or
+// DATABASE_URL) to enable. Skipped by default so unit runs stay hermetic.
+func testDSN(t *testing.T) *sql.DB {
+	t.Helper()
+	dsn := os.Getenv("METRICS_TEST_DSN")
+	if dsn == "" {
+		dsn = os.Getenv("DATABASE_URL")
+	}
+	if dsn == "" {
+		t.Skip("METRICS_TEST_DSN not set")
+	}
+	db, err := sql.Open("postgres", dsn)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	if err := db.PingContext(context.Background()); err != nil {
+		t.Fatalf("ping: %v", err)
+	}
+	t.Cleanup(func() { db.Close() })
+	return db
+}
+
+func TestPostgresStorageRoundTrip(t *testing.T) {
+	db := testDSN(t)
+	s := NewPostgreSQLMetricsStorage(db)
+	ctx := context.Background()
+
+	ts := time.Now().UTC().Truncate(time.Second)
+	nodeID := "test-node-" + ts.Format("150405")
+	svcID := "test-svc-" + ts.Format("150405")
+
+	// Clean slate + teardown
+	db.ExecContext(ctx, `DELETE FROM instance_metrics WHERE service_id = $1`, svcID)
+	db.ExecContext(ctx, `DELETE FROM service_metrics WHERE service_id = $1`, svcID)
+	db.ExecContext(ctx, `DELETE FROM node_metrics WHERE node_id = $1`, nodeID)
+	t.Cleanup(func() {
+		db.ExecContext(ctx, `DELETE FROM instance_metrics WHERE service_id = $1`, svcID)
+		db.ExecContext(ctx, `DELETE FROM service_metrics WHERE service_id = $1`, svcID)
+		db.ExecContext(ctx, `DELETE FROM node_metrics WHERE node_id = $1`, nodeID)
+	})
+
+	node := &NodeMetrics{
+		NodeID:    nodeID,
+		Timestamp: ts,
+		CPU:       CPUMetrics{UsagePercent: 42.5, UsageCores: 1.7, LoadAverage1: 0.5, LoadAverage5: 0.4, LoadAverage15: 0.3},
+		Memory:    MemoryMetrics{Total: 16 << 30, Used: 8 << 30, Available: 8 << 30, UsagePercent: 50.0},
+		Storage:   StorageMetrics{Total: 100 << 30, Used: 40 << 30, Available: 60 << 30, UsagePercent: 40.0},
+		Network:   NetworkMetrics{BytesIn: 1000, BytesOut: 2000, PacketsIn: 10, PacketsOut: 20, ConnectionsIn: 3, ConnectionsOut: 4, ErrorsIn: 0, ErrorsOut: 1},
+		System:    SystemMetrics{Uptime: 3600 * time.Second, Processes: 120, OS: "linux", Kernel: "6.8", Architecture: "amd64"},
+	}
+	if err := s.StoreNodeMetrics(ctx, node); err != nil {
+		t.Fatalf("store node: %v", err)
+	}
+	// Upsert idempotent on the same key.
+	if err := s.StoreNodeMetrics(ctx, node); err != nil {
+		t.Fatalf("store node (repeat): %v", err)
+	}
+
+	svc := &ServiceMetrics{
+		ServiceID:   svcID,
+		ServiceName: "svc",
+		ProjectID:   "proj",
+		Timestamp:   ts,
+		Requests:    RequestMetrics{Total: 100, Success: 95, Errors: 5, AvgLatency: 12.5, P95Latency: 80, P99Latency: 120, Throughput: 3.3},
+		Errors:      ErrorMetrics{Total: 5, Rate: 0.05},
+		Performance: PerformanceMetrics{ResponseTime: 12.5, Throughput: 3.3, Concurrency: 2, Saturation: 0.4, Utilization: 0.55},
+		Resources:   ResourceMetrics{CPUUsage: 42.5, MemoryUsage: 512 << 20, StorageUsage: 1 << 30, NetworkUsage: 3000, ResourceScore: 0.7},
+		Instances: []InstanceMetrics{{
+			InstanceID: "inst-1",
+			NodeID:     nodeID,
+			Status:     "running",
+			CPU:        42.5,
+			Memory:     512 << 20,
+			Network:    NetworkMetrics{BytesIn: 1000, BytesOut: 2000},
+			StartTime:  ts.Add(-time.Hour),
+			LastSeen:   ts,
+			Health:     HealthMetrics{Status: "healthy", LastCheck: ts, CheckCount: 10, FailureCount: 0},
+		}},
+	}
+	if err := s.StoreServiceMetrics(ctx, svc); err != nil {
+		t.Fatalf("store service: %v", err)
+	}
+
+	from, to := ts.Add(-time.Minute), ts.Add(time.Minute)
+	gotNodes, err := s.GetNodeMetrics(ctx, nodeID, from, to)
+	if err != nil {
+		t.Fatalf("get nodes: %v", err)
+	}
+	if len(gotNodes) != 1 {
+		t.Fatalf("want 1 node row, got %d", len(gotNodes))
+	}
+	if got := gotNodes[0]; got.CPU.UsagePercent != 42.5 || got.System.Processes != 120 || got.System.Uptime != time.Hour {
+		t.Errorf("node round-trip mismatch: %+v", got)
+	}
+
+	gotSvcs, err := s.GetServiceMetrics(ctx, svcID, from, to)
+	if err != nil {
+		t.Fatalf("get services: %v", err)
+	}
+	if len(gotSvcs) != 1 {
+		t.Fatalf("want 1 service row, got %d", len(gotSvcs))
+	}
+	if gotSvcs[0].Requests.P99Latency != 120 {
+		t.Errorf("p99 mismatch: %v", gotSvcs[0].Requests.P99Latency)
+	}
+	if len(gotSvcs[0].Instances) != 1 || gotSvcs[0].Instances[0].Health.Status != "healthy" {
+		t.Errorf("instance join mismatch: %+v", gotSvcs[0].Instances)
+	}
+
+	agg, err := s.GetAggregatedMetrics(ctx, MetricsQuery{Type: "node", ID: nodeID, From: from, To: to, Interval: 5 * time.Minute})
+	if err != nil {
+		t.Fatalf("aggregate: %v", err)
+	}
+	if len(agg.TimeSeries) != 1 || agg.TimeSeries[0].Values["cpu_usage"] != 42.5 {
+		t.Errorf("aggregate mismatch: %+v", agg.TimeSeries)
+	}
+	if agg.Summary["cpu_usage"].Avg != 42.5 {
+		t.Errorf("summary mismatch: %+v", agg.Summary)
+	}
+}

app/backend/sqlc/queries/domains.sql

@@ -0,0 +1,46 @@
+-- name: ListServiceDomains :many
+SELECT id, service_id, domain, is_default, cert_type, cert_status, last_checked_at, created_at
+FROM service_domains
+WHERE service_id = $1
+ORDER BY is_default DESC, created_at ASC;
+
+-- name: CountServiceDomains :one
+SELECT COUNT(*) FROM service_domains WHERE service_id = $1;
+
+-- name: ClearServiceDomainDefault :exec
+UPDATE service_domains SET is_default = false WHERE service_id = $1;
+
+-- name: CreateServiceDomain :one
+INSERT INTO service_domains (service_id, domain, is_default)
+VALUES ($1, $2, $3)
+RETURNING id, service_id, domain, is_default, cert_type, cert_status, created_at;
+
+-- name: DeleteServiceDomain :execrows
+DELETE FROM service_domains WHERE id = $1 AND service_id = $2;
+
+-- name: SetServiceDomainDefault :execrows
+UPDATE service_domains SET is_default = (id = $1) WHERE service_id = $2;
+
+-- name: TouchServiceDomainChecked :exec
+UPDATE service_domains SET last_checked_at = NOW() WHERE id = $1;
+
+-- name: GetServiceDomainDefault :one
+SELECT domain FROM service_domains WHERE service_id = $1 AND is_default;
+
+-- name: GetServiceDomainFirst :one
+SELECT domain FROM service_domains WHERE service_id = $1 ORDER BY created_at ASC LIMIT 1;
+
+-- name: SetServiceLegacyDomain :exec
+UPDATE services SET domain = $1 WHERE id = $2;
+
+-- name: GetServicePlacementBrief :one
+SELECT name, node_id, COALESCE(spread, false) AS spread FROM services WHERE id = $1;
+
+-- name: GetServiceAccess :one
+SELECT maintenance_mode, basic_auth_users FROM services WHERE id = $1;
+
+-- name: ServiceWriteAccess :one
+SELECT EXISTS(
+    SELECT 1 FROM services s JOIN projects p ON s.project_id = p.id
+    WHERE s.id = $1 AND (p.owner_id = $2 OR $3::bool)
+) AS allowed;

app/backend/sqlc/queries/metrics.sql

@@ -0,0 +1,147 @@
+-- name: UpsertNodeMetrics :exec
+INSERT INTO node_metrics (
+    node_id, timestamp, cpu_usage, cpu_cores, load_avg_1, load_avg_5, load_avg_15,
+    memory_total, memory_used, memory_available, memory_usage_percent,
+    storage_total, storage_used, storage_available, storage_usage_percent,
+    network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
+    network_connections_in, network_connections_out, network_errors_in, network_errors_out,
+    uptime, processes, os, kernel, architecture
+) VALUES (
+    $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15,
+    $16, $17, $18, $19, $20, $21, $22, $23, $24, $25, $26, $27, $28
+)
+ON CONFLICT (node_id, timestamp) DO UPDATE SET
+    cpu_usage = EXCLUDED.cpu_usage,
+    cpu_cores = EXCLUDED.cpu_cores,
+    load_avg_1 = EXCLUDED.load_avg_1,
+    load_avg_5 = EXCLUDED.load_avg_5,
+    load_avg_15 = EXCLUDED.load_avg_15,
+    memory_total = EXCLUDED.memory_total,
+    memory_used = EXCLUDED.memory_used,
+    memory_available = EXCLUDED.memory_available,
+    memory_usage_percent = EXCLUDED.memory_usage_percent,
+    storage_total = EXCLUDED.storage_total,
+    storage_used = EXCLUDED.storage_used,
+    storage_available = EXCLUDED.storage_available,
+    storage_usage_percent = EXCLUDED.storage_usage_percent,
+    network_bytes_in = EXCLUDED.network_bytes_in,
+    network_bytes_out = EXCLUDED.network_bytes_out,
+    network_packets_in = EXCLUDED.network_packets_in,
+    network_packets_out = EXCLUDED.network_packets_out,
+    network_connections_in = EXCLUDED.network_connections_in,
+    network_connections_out = EXCLUDED.network_connections_out,
+    network_errors_in = EXCLUDED.network_errors_in,
+    network_errors_out = EXCLUDED.network_errors_out,
+    uptime = EXCLUDED.uptime,
+    processes = EXCLUDED.processes,
+    os = EXCLUDED.os,
+    kernel = EXCLUDED.kernel,
+    architecture = EXCLUDED.architecture;
+
+-- name: UpsertServiceMetrics :exec
+INSERT INTO service_metrics (
+    service_id, service_name, project_id, timestamp,
+    requests_total, requests_success, requests_errors, requests_avg_latency,
+    requests_p95_latency, requests_p99_latency, requests_throughput,
+    errors_total, errors_rate, performance_response_time, performance_throughput,
+    performance_concurrency, performance_saturation, performance_utilization,
+    resource_cpu_usage, resource_memory_usage, resource_storage_usage,
+    resource_network_usage, resource_score
+) VALUES (
+    $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15,
+    $16, $17, $18, $19, $20, $21, $22, $23
+)
+ON CONFLICT (service_id, timestamp) DO UPDATE SET
+    requests_total = EXCLUDED.requests_total,
+    requests_success = EXCLUDED.requests_success,
+    requests_errors = EXCLUDED.requests_errors,
+    requests_avg_latency = EXCLUDED.requests_avg_latency,
+    requests_p95_latency = EXCLUDED.requests_p95_latency,
+    requests_p99_latency = EXCLUDED.requests_p99_latency,
+    requests_throughput = EXCLUDED.requests_throughput,
+    errors_total = EXCLUDED.errors_total,
+    errors_rate = EXCLUDED.errors_rate,
+    performance_response_time = EXCLUDED.performance_response_time,
+    performance_throughput = EXCLUDED.performance_throughput,
+    performance_concurrency = EXCLUDED.performance_concurrency,
+    performance_saturation = EXCLUDED.performance_saturation,
+    performance_utilization = EXCLUDED.performance_utilization,
+    resource_cpu_usage = EXCLUDED.resource_cpu_usage,
+    resource_memory_usage = EXCLUDED.resource_memory_usage,
+    resource_storage_usage = EXCLUDED.resource_storage_usage,
+    resource_network_usage = EXCLUDED.resource_network_usage,
+    resource_score = EXCLUDED.resource_score;
+
+-- name: UpsertInstanceMetrics :exec
+INSERT INTO instance_metrics (
+    service_id, timestamp, instance_id, node_id, status, cpu, memory,
+    network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
+    network_connections_in, network_connections_out, network_errors_in, network_errors_out,
+    start_time, last_seen, health_status, health_last_check, health_check_count, health_failure_count
+) VALUES (
+    $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15,
+    $16, $17, $18, $19, $20, $21
+)
+ON CONFLICT (service_id, timestamp, instance_id) DO UPDATE SET
+    node_id = EXCLUDED.node_id,
+    status = EXCLUDED.status,
+    cpu = EXCLUDED.cpu,
+    memory = EXCLUDED.memory,
+    network_bytes_in = EXCLUDED.network_bytes_in,
+    network_bytes_out = EXCLUDED.network_bytes_out,
+    network_packets_in = EXCLUDED.network_packets_in,
+    network_packets_out = EXCLUDED.network_packets_out,
+    network_connections_in = EXCLUDED.network_connections_in,
+    network_connections_out = EXCLUDED.network_connections_out,
+    network_errors_in = EXCLUDED.network_errors_in,
+    network_errors_out = EXCLUDED.network_errors_out,
+    start_time = EXCLUDED.start_time,
+    last_seen = EXCLUDED.last_seen,
+    health_status = EXCLUDED.health_status,
+    health_last_check = EXCLUDED.health_last_check,
+    health_check_count = EXCLUDED.health_check_count,
+    health_failure_count = EXCLUDED.health_failure_count;
+
+-- name: ListNodeMetrics :many
+SELECT node_id, timestamp, cpu_usage, cpu_cores, load_avg_1, load_avg_5, load_avg_15,
+       memory_total, memory_used, memory_available, memory_usage_percent,
+       storage_total, storage_used, storage_available, storage_usage_percent,
+       network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
+       network_connections_in, network_connections_out, network_errors_in, network_errors_out,
+       coalesce(extract(epoch from uptime), 0)::bigint AS uptime_seconds,
+       processes, os, kernel, architecture
+FROM node_metrics
+WHERE node_id = $1 AND timestamp BETWEEN $2 AND $3
+ORDER BY timestamp ASC;
+
+-- name: ListServiceMetrics :many
+SELECT service_id, service_name, project_id, timestamp,
+       requests_total, requests_success, requests_errors, requests_avg_latency,
+       requests_p95_latency, requests_p99_latency, requests_throughput,
+       errors_total, errors_rate, performance_response_time, performance_throughput,
+       performance_concurrency, performance_saturation, performance_utilization,
+       resource_cpu_usage, resource_memory_usage, resource_storage_usage,
+       resource_network_usage, resource_score
+FROM service_metrics
+WHERE service_id = $1 AND timestamp BETWEEN $2 AND $3
+ORDER BY timestamp ASC;
+
+-- name: ListInstanceMetrics :many
+SELECT instance_id, node_id, status, cpu, memory,
+       network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
+       network_connections_in, network_connections_out, network_errors_in, network_errors_out,
+       start_time, last_seen, health_status, health_last_check, health_check_count, health_failure_count
+FROM instance_metrics
+WHERE service_id = $1 AND timestamp = $2;
+
+-- name: AggregateNodeMetrics :many
+-- Portable bucket bucketing (no TimescaleDB): floor epoch seconds into
+-- bucket-sized buckets, then back to timestamptz.
+SELECT date_bin($1::interval, timestamp, '2000-01-01'::timestamptz) AS bucket,
+       AVG(cpu_usage)::float8 AS avg_cpu,
+       AVG(memory_usage_percent)::float8 AS avg_memory,
+       AVG(storage_usage_percent)::float8 AS avg_storage
+FROM node_metrics
+WHERE node_id = $2 AND timestamp BETWEEN $3 AND $4
+GROUP BY bucket
+ORDER BY bucket ASC;

app/backend/sqlc/queries/preview_environments.sql

@@ -0,0 +1,121 @@
+-- name: ListPreviewEnvironmentsForProject :many
+SELECT pe.id, pe.project_id, pe.service_id, pe.preview_service_id, pe.branch_name, pe.pr_number,
+       pe.environment, pe.status, pe.url, pe.expires_at, pe.created_at, pe.updated_at,
+       s.id AS svc_id, s.name AS service_name, s.type AS service_type
+FROM preview_environments pe
+LEFT JOIN services s ON pe.service_id = s.id
+WHERE pe.project_id = $1
+ORDER BY pe.created_at DESC;
+
+-- name: GetPreviewEnvironment :one
+SELECT pe.id, pe.project_id, pe.service_id, pe.preview_service_id, pe.branch_name, pe.pr_number,
+       pe.environment, pe.status, pe.url, pe.expires_at, pe.created_at, pe.updated_at,
+       s.id AS svc_id, s.name AS service_name, s.type AS service_type
+FROM preview_environments pe
+LEFT JOIN services s ON pe.service_id = s.id
+JOIN projects p ON pe.project_id = p.id
+WHERE pe.id = $1 AND (p.is_approved OR p.owner_id = $2 OR $3::bool
+    OR EXISTS (SELECT 1 FROM project_members pm WHERE pm.project_id = p.id AND pm.user_id = $2));
+
+-- name: GetPreviewEnvironmentForWrite :one
+SELECT pe.id, pe.project_id, pe.service_id, pe.branch_name, pe.pr_number,
+       pe.environment, pe.status, pe.url, pe.expires_at, pe.created_at, pe.updated_at
+FROM preview_environments pe
+JOIN projects p ON pe.project_id = p.id
+WHERE pe.id = $1 AND (p.owner_id = $2 OR $3::bool);
+
+-- name: GetPreviewEnvironmentForPromote :one
+SELECT pe.id, pe.project_id, pe.service_id, pe.preview_service_id, pe.branch_name, pe.environment, pe.status
+FROM preview_environments pe
+JOIN projects p ON pe.project_id = p.id
+WHERE pe.id = $1 AND (p.owner_id = $2 OR $3::bool);
+
+-- name: GetPreviewEnvironmentOwner :one
+SELECT p.owner_id
+FROM preview_environments pe
+JOIN projects p ON pe.project_id = p.id
+WHERE pe.id = $1;
+
+-- name: GetPreviewServiceID :one
+SELECT preview_service_id FROM preview_environments WHERE id = $1;
+
+-- name: UpdatePreviewEnvironment :exec
+UPDATE preview_environments
+SET status = $1, url = $2, expires_at = $3, updated_at = $4
+WHERE id = $5;
+
+-- name: MarkPreviewEnvironmentStatus :exec
+UPDATE preview_environments SET status = $1, updated_at = NOW() WHERE id = $2;
+
+-- name: DeletePreviewEnvironment :exec
+DELETE FROM preview_environments WHERE id = $1;
+
+-- name: CountActivePreviewsForBranch :one
+SELECT COUNT(*) FROM preview_environments
+WHERE service_id = $1 AND branch_name = $2 AND status NOT IN ('expired', 'stopped');
+
+-- name: CreatePreviewEnvironment :exec
+INSERT INTO preview_environments
+    (id, project_id, service_id, preview_service_id, branch_name, pr_number, environment,
+     status, url, expires_at, created_at, updated_at)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12);
+
+-- name: UpdateServicePreviewBranch :exec
+UPDATE services SET git_branch = $1, domain = '', updated_at = NOW() WHERE id = $2;
+
+-- name: DeleteAllServiceDomains :exec
+DELETE FROM service_domains WHERE service_id = $1;
+
+-- name: CreatePreviewDomain :exec
+INSERT INTO service_domains (service_id, domain, is_default, cert_type) VALUES ($1, $2, true, 'tls');
+
+-- name: InsertPendingDeployment :exec
+INSERT INTO deployments (id, service_id, version, commit_hash, status, created_at, updated_at)
+VALUES ($1, $2, $3, $4, 'pending', NOW(), NOW());
+
+-- name: ListExpiredPreviewsForUser :many
+SELECT pe.id, pe.project_id, pe.service_id, pe.preview_service_id, pe.branch_name, pe.environment
+FROM preview_environments pe
+JOIN projects p ON pe.project_id = p.id
+WHERE (p.owner_id = $1 OR $2::bool) AND pe.expires_at < NOW() AND pe.status != 'expired';
+
+-- name: ListSweepablePreviews :many
+SELECT id, preview_service_id FROM preview_environments
+WHERE expires_at < NOW() AND status NOT IN ('expired', 'stopped');
+
+-- name: SyncPreviewStatuses :exec
+UPDATE preview_environments pe
+SET status = derived.st, updated_at = NOW()
+FROM (
+    SELECT pe2.id,
+        CASE
+            WHEN s.status IN ('running', 'deployed') THEN 'running'
+            WHEN s.status IN ('failed', 'error') THEN 'failed'
+            WHEN s.status IN ('building', 'deploying', 'queued', 'pending', 'cloning') THEN 'building'
+            ELSE pe2.status
+        END AS st
+    FROM preview_environments pe2
+    JOIN services s ON pe2.preview_service_id = s.id
+) derived
+WHERE pe.id = derived.id
+  AND pe.status IN ('building', 'running', 'failed')
+  AND pe.status <> derived.st;
+
+-- name: GetProjectBrief :one
+SELECT id, name, owner_id FROM projects WHERE id = $1;
+
+-- name: GetServiceTypeBrief :one
+SELECT id, name, COALESCE(type, service_type, '') AS service_type FROM services WHERE id = $1 AND project_id = $2;
+
+-- name: GetServiceForDeploy :one
+SELECT s.id, s.project_id, s.name, s.type, s.status, s.image, s.command,
+       s.environment, s.git_repo, s.git_branch, s.build_path, s.cpu, s.memory,
+       COALESCE(s.replicas, 1) AS replicas, COALESCE(s.port, 0) AS port,
+       COALESCE(s.domain, '') AS domain, COALESCE(s.healthcheck_path, '') AS healthcheck_path,
+       COALESCE(s.restart_policy, 'unless-stopped') AS restart_policy,
+       COALESCE(s.builder, 'auto') AS builder, COALESCE(s.cpu_reserve, '') AS cpu_reserve,
+       COALESCE(s.memory_reserve, '') AS memory_reserve, COALESCE(s.static_build_cmd, '') AS static_build_cmd,
+       COALESCE(s.static_dir, '') AS static_dir,
+       s.created_at, s.updated_at
+FROM services s
+WHERE s.id = $1;

app/backend/sqlc/queries/service_ops.sql

@@ -0,0 +1,38 @@
+-- name: CountServicesByName :one
+SELECT COUNT(*) FROM services WHERE project_id = $1 AND name = $2;
+
+-- name: GetServiceEnvironment :one
+SELECT COALESCE(environment, '') FROM services WHERE id = $1;
+
+-- name: CloneServiceRow :exec
+INSERT INTO services
+    (id, project_id, name, environment_id, service_type, source_type, source_url, image_name,
+     build_command, start_command, type, status, image, command, environment,
+     git_repo, git_branch, build_path, cpu, memory, replicas, port, domain,
+     healthcheck_path, restart_policy, volumes, maintenance_mode, basic_auth_users,
+     builder, cpu_reserve, memory_reserve, static_build_cmd, static_dir,
+     traefik_labels, created_at, updated_at)
+SELECT $1, $2, $3, $4, service_type, source_type, source_url, image_name,
+     build_command, start_command, type, 'stopped', image, command, $5,
+     git_repo, git_branch, build_path, cpu, memory, replicas, port, domain,
+     healthcheck_path, restart_policy, volumes, $6, $7,
+     builder, cpu_reserve, memory_reserve, static_build_cmd, static_dir,
+     traefik_labels, $8, $8
+FROM services s WHERE s.id = $9;
+
+-- name: CloneServiceDomains :exec
+INSERT INTO service_domains (service_id, domain, is_default, cert_type)
+SELECT $1, domain, is_default, cert_type FROM service_domains sd WHERE sd.service_id = $2;
+
+-- name: CloneServiceVariables :exec
+INSERT INTO environment_variables (id, service_id, key, value, is_secret)
+SELECT gen_random_uuid(), $1, key, value, is_secret FROM environment_variables ev WHERE ev.service_id = $2;
+
+-- name: DeleteServiceByID :exec
+DELETE FROM services WHERE id = $1;
+
+-- name: MoveServiceProject :execrows
+UPDATE services SET project_id = $1, environment_id = $2, updated_at = $3 WHERE id = $4;
+
+-- name: GetProjectOwner :one
+SELECT owner_id FROM projects WHERE id = $1;

app/backend/sqlc/schema.sql

@@ -98,11 +98,37 @@ CREATE TABLE service_domains (
 );
 
 CREATE TABLE deployments (
-    id UUID PRIMARY KEY,
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     service_id UUID NOT NULL REFERENCES services(id) ON DELETE CASCADE,
-    status VARCHAR(50),
+    version VARCHAR(255) NOT NULL,
+    commit_hash VARCHAR(255),
+    image_digest VARCHAR(255),
+    status VARCHAR(50) DEFAULT 'created',
+    build_log TEXT,
+    deployment_log TEXT,
+    started_at TIMESTAMPTZ,
+    completed_at TIMESTAMPTZ,
     created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    image_name VARCHAR(255),
+    image_tag VARCHAR(255),
+    runtime_log TEXT,
+    error TEXT
+);
+
+CREATE TABLE preview_environments (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    project_id UUID NOT NULL,
+    service_id UUID NOT NULL,
+    branch_name VARCHAR(255) NOT NULL,
+    pr_number INTEGER,
+    environment VARCHAR(255) NOT NULL,
+    status VARCHAR(50) NOT NULL DEFAULT 'building',
+    url TEXT,
+    expires_at TIMESTAMPTZ NOT NULL,
+    created_at TIMESTAMPTZ DEFAULT now(),
+    updated_at TIMESTAMPTZ DEFAULT now(),
+    preview_service_id UUID
 );
 
 CREATE TABLE environment_variables (
@@ -346,3 +372,90 @@ CREATE TABLE notification_channels (
     created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
 );
+
+CREATE TABLE node_metrics (
+    node_id VARCHAR(255) NOT NULL,
+    timestamp TIMESTAMP WITH TIME ZONE NOT NULL,
+    cpu_usage NUMERIC(5,2),
+    cpu_cores NUMERIC(10,2),
+    load_avg_1 NUMERIC(5,2),
+    load_avg_5 NUMERIC(5,2),
+    load_avg_15 NUMERIC(5,2),
+    memory_total BIGINT,
+    memory_used BIGINT,
+    memory_available BIGINT,
+    memory_usage_percent NUMERIC(5,2),
+    storage_total BIGINT,
+    storage_used BIGINT,
+    storage_available BIGINT,
+    storage_usage_percent NUMERIC(5,2),
+    network_bytes_in BIGINT,
+    network_bytes_out BIGINT,
+    network_packets_in BIGINT,
+    network_packets_out BIGINT,
+    network_connections_in INTEGER,
+    network_connections_out INTEGER,
+    network_errors_in BIGINT,
+    network_errors_out BIGINT,
+    uptime INTERVAL,
+    processes INTEGER,
+    os VARCHAR(50),
+    kernel VARCHAR(50),
+    architecture VARCHAR(20),
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    PRIMARY KEY (node_id, timestamp)
+);
+
+CREATE TABLE service_metrics (
+    service_id VARCHAR(255) NOT NULL,
+    service_name VARCHAR(255) NOT NULL,
+    project_id VARCHAR(255) NOT NULL,
+    timestamp TIMESTAMP WITH TIME ZONE NOT NULL,
+    requests_total BIGINT DEFAULT 0,
+    requests_success BIGINT DEFAULT 0,
+    requests_errors BIGINT DEFAULT 0,
+    requests_avg_latency NUMERIC(10,3),
+    requests_p95_latency NUMERIC(10,3),
+    requests_p99_latency NUMERIC(10,3),
+    requests_throughput NUMERIC(10,3),
+    errors_total BIGINT DEFAULT 0,
+    errors_rate NUMERIC(5,4),
+    performance_response_time NUMERIC(10,3),
+    performance_throughput NUMERIC(10,3),
+    performance_concurrency BIGINT,
+    performance_saturation NUMERIC(5,2),
+    performance_utilization NUMERIC(5,2),
+    resource_cpu_usage NUMERIC(5,2),
+    resource_memory_usage BIGINT,
+    resource_storage_usage BIGINT,
+    resource_network_usage BIGINT,
+    resource_score NUMERIC(5,2),
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    PRIMARY KEY (service_id, timestamp)
+);
+
+CREATE TABLE instance_metrics (
+    service_id VARCHAR(255) NOT NULL,
+    timestamp TIMESTAMP WITH TIME ZONE NOT NULL,
+    instance_id VARCHAR(255) NOT NULL,
+    node_id VARCHAR(255),
+    status VARCHAR(50),
+    cpu NUMERIC(5,2),
+    memory BIGINT,
+    network_bytes_in BIGINT,
+    network_bytes_out BIGINT,
+    network_packets_in BIGINT,
+    network_packets_out BIGINT,
+    network_connections_in INTEGER,
+    network_connections_out INTEGER,
+    network_errors_in BIGINT,
+    network_errors_out BIGINT,
+    start_time TIMESTAMP WITH TIME ZONE,
+    last_seen TIMESTAMP WITH TIME ZONE,
+    health_status VARCHAR(20),
+    health_last_check TIMESTAMP WITH TIME ZONE,
+    health_check_count INTEGER DEFAULT 0,
+    health_failure_count INTEGER DEFAULT 0,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    PRIMARY KEY (service_id, timestamp, instance_id)
+);

app/frontend/package-lock.json

@@ -31,7 +31,9 @@
         "@tabler/icons-react": "^3.37.1",
         "@tailwindcss/postcss": "^4.1.18",
         "@tailwindcss/typography": "^0.5.19",
+        "@tanstack/query-sync-storage-persister": "^5.104.1",
         "@tanstack/react-query": "^5.66.0",
+        "@tanstack/react-query-persist-client": "^5.104.1",
         "@types/dompurify": "^3.0.5",
         "@xterm/addon-fit": "^0.11.0",
         "@xterm/xterm": "^6.0.0",
@@ -3441,22 +3443,49 @@
       }
     },
     "node_modules/@tanstack/query-core": {
-      "version": "5.90.20",
-      "resolved": "https://registry.npmjs.org/@tanstack/query-core/-/query-core-5.90.20.tgz",
-      "integrity": "sha512-OMD2HLpNouXEfZJWcKeVKUgQ5n+n3A2JFmBaScpNDUqSrQSjiveC7dKMe53uJUg1nDG16ttFPz2xfilz6i2uVg==",
+      "version": "5.104.1",
+      "resolved": "https://registry.npmjs.org/@tanstack/query-core/-/query-core-5.104.1.tgz",
+      "integrity": "sha512-TiRghcrGkUTE+M4JBxvpPSpBhxvIzQairw+cksrHYGr+2uwC77yW1SY9nYxnYRYOppvucf8rEg6b5byoz4rTpw==",
       "license": "MIT",
       "funding": {
         "type": "github",
         "url": "https://github.com/sponsors/tannerlinsley"
       }
     },
-    "node_modules/@tanstack/react-query": {
-      "version": "5.90.21",
-      "resolved": "https://registry.npmjs.org/@tanstack/react-query/-/react-query-5.90.21.tgz",
-      "integrity": "sha512-0Lu6y5t+tvlTJMTO7oh5NSpJfpg/5D41LlThfepTixPYkJ0sE2Jj0m0f6yYqujBwIXlId87e234+MxG3D3g7kg==",
+    "node_modules/@tanstack/query-persist-client-core": {
+      "version": "5.104.1",
+      "resolved": "https://registry.npmjs.org/@tanstack/query-persist-client-core/-/query-persist-client-core-5.104.1.tgz",
+      "integrity": "sha512-ONiadXqe56iNrw6RESqKILpTIVG9ZMI/DageTQnrBDt/nZ6WiP4G13iIiMwJEsiO12gQ3Gychx8tcFIPw4k25g==",
       "license": "MIT",
       "dependencies": {
-        "@tanstack/query-core": "5.90.20"
+        "@tanstack/query-core": "5.104.1"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      }
+    },
+    "node_modules/@tanstack/query-sync-storage-persister": {
+      "version": "5.104.1",
+      "resolved": "https://registry.npmjs.org/@tanstack/query-sync-storage-persister/-/query-sync-storage-persister-5.104.1.tgz",
+      "integrity": "sha512-eDsBMNds48+sjXILn0dQKu+uYwfh9tGIB+Rb0cKRdoxD22HHBMzJes5DJOhJVLUhBQbxtoFq+Hpha/Vohh14NQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@tanstack/query-core": "5.104.1",
+        "@tanstack/query-persist-client-core": "5.104.1"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      }
+    },
+    "node_modules/@tanstack/react-query": {
+      "version": "5.104.1",
+      "resolved": "https://registry.npmjs.org/@tanstack/react-query/-/react-query-5.104.1.tgz",
+      "integrity": "sha512-Zz70EgjahNI7aCz8BZxM3vUGU44ycxEAzMuCUjLeA7SVhhOkg3ZgPjPJPvHjs6Rmky/dtmnu1WzjGHNHmhCoZQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@tanstack/query-core": "5.104.1"
       },
       "funding": {
         "type": "github",
@@ -3466,6 +3495,23 @@
         "react": "^18 || ^19"
       }
     },
+    "node_modules/@tanstack/react-query-persist-client": {
+      "version": "5.104.1",
+      "resolved": "https://registry.npmjs.org/@tanstack/react-query-persist-client/-/react-query-persist-client-5.104.1.tgz",
+      "integrity": "sha512-kU3YaqjkwEUzUUfPF0JVg56d6gJKWHaFVqOlQztwc4C2IT0P5sv/23orrSoQqjxKaUe6Ejw5IIQtA/G12uNmow==",
+      "license": "MIT",
+      "dependencies": {
+        "@tanstack/query-persist-client-core": "5.104.1"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      },
+      "peerDependencies": {
+        "@tanstack/react-query": "^5.104.1",
+        "react": "^18 || ^19"
+      }
+    },
     "node_modules/@testing-library/dom": {
       "version": "10.4.1",
       "resolved": "https://registry.npmjs.org/@testing-library/dom/-/dom-10.4.1.tgz",

app/frontend/package.json

@@ -42,7 +42,9 @@
     "@tabler/icons-react": "^3.37.1",
     "@tailwindcss/postcss": "^4.1.18",
     "@tailwindcss/typography": "^0.5.19",
+    "@tanstack/query-sync-storage-persister": "^5.104.1",
     "@tanstack/react-query": "^5.66.0",
+    "@tanstack/react-query-persist-client": "^5.104.1",
     "@types/dompurify": "^3.0.5",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",

app/frontend/src/app/App.tsx

@@ -28,6 +28,7 @@ import {
 } from '@/features/secondary/pages';
 import { NodeDetailPage } from '@/features/nodes/NodeDetailPage';
 import { AcceptInvitePage, SignInPage, SignUpPage } from '@/features/auth/pages';
+import { SetupWizardPage } from '@/features/setup/SetupWizardPage';
 import { useAuthSession } from '@/lib/use-auth-session';
 import { useDemoMode } from '@/lib/demo-mode';
 import { getCurrentUserProfile } from '@/lib/api-client';
@@ -138,6 +139,7 @@ export default function App() {
         <Route path="/auth/sign-in" element={<SignInPage />} />
         <Route path="/auth/sign-up" element={<SignUpPage />} />
         <Route path="/auth/accept-invite" element={<AcceptInvitePage />} />
+        <Route path="/setup" element={<SetupWizardPage />} />
 
         {/* Public browsing — approved projects, templates, docs. */}
         {/* Project workspace renders outside the shell — fullscreen canvas, no nav chrome */}

app/frontend/src/app/layout/PlatformShell.tsx

@@ -1,4 +1,4 @@
-import { NavLink, Outlet, useLocation, useNavigate } from 'react-router-dom';
+import { NavLink, Navigate, Outlet, useLocation, useNavigate } from 'react-router-dom';
 import { useEffect, useState } from 'react';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import * as DropdownMenu from '@radix-ui/react-dropdown-menu';
@@ -30,10 +30,13 @@ import {
   User,
   Users,
   Webhook,
+  WifiOff,
 } from 'lucide-react';
 import {
   getCurrentUserProfile,
   getUpgradeStatus,
+  pingServer,
+  getSetupStatus,
   listNotifications,
   markAllNotificationsRead,
   markNotificationRead,
@@ -105,6 +108,42 @@ function getInitialSidebar(): boolean {
   return readStorage('containr.sidebar.expanded') !== '0';
 }
 
+// ConnectivityBanner pings /health every 15s and listens for browser
+// online/offline events — when the instance is unreachable it shows a
+// slim bar so the persisted last-known data doesn't masquerade as live.
+function ConnectivityBanner() {
+  const [offline, setOffline] = useState(() => !navigator.onLine);
+  useEffect(() => {
+    const up = () => setOffline(false);
+    const down = () => setOffline(true);
+    window.addEventListener('online', up);
+    window.addEventListener('offline', down);
+    return () => {
+      window.removeEventListener('online', up);
+      window.removeEventListener('offline', down);
+    };
+  }, []);
+  const ping = useQuery({
+    queryKey: ['connectivity'],
+    queryFn: pingServer,
+    refetchInterval: 15_000,
+    retry: 0,
+    networkMode: 'always',
+    staleTime: 0,
+  });
+  if (!offline && !ping.isError) {
+    return null;
+  }
+  return (
+    <div className="flex items-center justify-center gap-2 border-b border-[var(--warning,var(--border-subtle))] bg-[var(--surface-muted)] px-4 py-1.5 text-xs text-[var(--text-secondary)]">
+      <WifiOff size={13} className="text-[var(--warning,#f59e0b)]" />
+      {offline
+        ? 'No network connection — showing last-known data.'
+        : 'Cannot reach this Containr instance — showing last-known data. Retrying…'}
+    </div>
+  );
+}
+
 export function PlatformShell() {
   const location = useLocation();
   const navigate = useNavigate();
@@ -147,6 +186,13 @@ export function PlatformShell() {
     enabled: !isDemoMode && signedIn,
     refetchInterval: 30_000,
   });
+  // Fresh installs get routed through the setup wizard until the flag lands.
+  const setupQuery = useQuery({
+    queryKey: ['setup-status'],
+    queryFn: getSetupStatus,
+    enabled: !isDemoMode && signedIn,
+    staleTime: 60_000,
+  });
   const markReadMutation = useMutation({
     mutationFn: (id: string) => markNotificationRead(id),
     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['shell-notifications'] }),
@@ -209,6 +255,10 @@ export function PlatformShell() {
     </div>
   );
 
+  if (!isDemoMode && signedIn && setupQuery.data?.needs_setup) {
+    return <Navigate to="/setup" replace />;
+  }
+
   return (
     <div className="app-shell min-h-screen">
       <div className="ambient-glow" />
@@ -557,6 +607,7 @@ export function PlatformShell() {
             </nav>
           </header>
 
+          <ConnectivityBanner />
           <main className="flex-1 overflow-y-auto">
             <Outlet />
           </main>

app/frontend/src/features/secondary/pages.tsx

@@ -1253,7 +1253,11 @@ export function GitHubAppCallbackPage() {
     mutationFn: (appCode: string) => convertGitHubAppCode(appCode),
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ['github-app-status'] });
-      navigate('/settings', { replace: true });
+      // The setup wizard stashes a return marker before submitting the
+      // manifest form — resume there instead of the settings page.
+      const inSetup = sessionStorage.getItem('containr.setup_return') === '1';
+      sessionStorage.removeItem('containr.setup_return');
+      navigate(inSetup ? '/setup' : '/settings', { replace: true });
     },
   });
   const firedRef = useRef(false);

app/frontend/src/features/setup/SetupWizardPage.test.tsx

@@ -0,0 +1,92 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { MemoryRouter } from 'react-router-dom';
+import { SetupWizardPage } from './SetupWizardPage';
+import type { SetupStatus } from '@/lib/api-client';
+
+const mockStatus = vi.fn<() => Promise<SetupStatus>>();
+const mockSession = vi.fn();
+
+vi.mock('@/lib/api-client', async (importOriginal) => {
+  const mod = await importOriginal<typeof import('@/lib/api-client')>();
+  return {
+    ...mod,
+    getSetupStatus: () => mockStatus(),
+    completeSetup: vi.fn().mockResolvedValue(undefined),
+  };
+});
+
+vi.mock('@/lib/use-auth-session', () => ({
+  useAuthSession: () => mockSession(),
+}));
+
+function renderWizard() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <MemoryRouter initialEntries={['/setup']}>
+        <SetupWizardPage />
+      </MemoryRouter>
+    </QueryClientProvider>,
+  );
+}
+
+const base: SetupStatus = {
+  has_users: false,
+  setup_completed: false,
+  needs_setup: true,
+  has_github_app: false,
+  has_tunnel: false,
+  signup_enabled: false,
+};
+
+describe('SetupWizardPage', () => {
+  beforeEach(() => {
+    mockSession.mockReturnValue({ data: null });
+  });
+
+  it('prompts for the admin account on a fresh install', async () => {
+    mockStatus.mockResolvedValue({ ...base });
+    renderWizard();
+    expect(await screen.findByText(/welcome to containr/i)).toBeInTheDocument();
+    expect(screen.getByText(/create admin account/i)).toBeInTheDocument();
+  });
+
+  it('offers sign-in when users exist but nobody is signed in', async () => {
+    mockStatus.mockResolvedValue({ ...base, has_users: true });
+    renderWizard();
+    expect(await screen.findByText(/sign in to continue setup/i)).toBeInTheDocument();
+  });
+
+  it('shows the git provider step for a signed-in admin without GitHub App', async () => {
+    mockStatus.mockResolvedValue({ ...base, has_users: true });
+    mockSession.mockReturnValue({ data: { user: { id: 'u1' } } });
+    renderWizard();
+    expect(await screen.findByText(/connect a git provider/i)).toBeInTheDocument();
+    expect(screen.getByText(/set up github app/i)).toBeInTheDocument();
+  });
+
+  it('shows the tunnel step when git is already wired', async () => {
+    mockStatus.mockResolvedValue({ ...base, has_users: true, has_github_app: true });
+    mockSession.mockReturnValue({ data: { user: { id: 'u1' } } });
+    renderWizard();
+    expect(
+      await screen.findByRole('heading', { name: /public access/i }),
+    ).toBeInTheDocument();
+  });
+
+  it('lands on the finish step when everything is configured', async () => {
+    mockStatus.mockResolvedValue({
+      ...base,
+      has_users: true,
+      has_github_app: true,
+      has_tunnel: true,
+    });
+    mockSession.mockReturnValue({ data: { user: { id: 'u1' } } });
+    renderWizard();
+    expect(await screen.findByText(/enter containr/i)).toBeInTheDocument();
+  });
+});

app/frontend/src/features/setup/SetupWizardPage.tsx

@@ -0,0 +1,279 @@
+import { useMemo, useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { Link, Navigate, useNavigate } from 'react-router-dom';
+import { Check, ChevronRight, Github, Loader2, Rocket, ShieldCheck } from 'lucide-react';
+import { useAuthSession } from '@/lib/use-auth-session';
+import {
+  completeSetup,
+  createGitHubAppManifest,
+  getSetupStatus,
+  updatePlatformSettings,
+} from '@/lib/api-client';
+
+// Marker the GitHub App callback reads so the wizard flow resumes here
+// instead of the settings page.
+const SETUP_RETURN_KEY = 'containr.setup_return';
+
+type Step = 'account' | 'github' | 'tunnel' | 'done';
+
+export function SetupWizardPage() {
+  const navigate = useNavigate();
+  const queryClient = useQueryClient();
+  const sessionQuery = useAuthSession();
+  const statusQuery = useQuery({ queryKey: ['setup-status'], queryFn: getSetupStatus });
+  const [override, setOverride] = useState<Step | null>(null);
+
+  const status = statusQuery.data;
+  const signedIn = Boolean(sessionQuery.data);
+
+  const step: Step = useMemo(() => {
+    if (override) return override;
+    if (!status) return 'account';
+    if (!status.has_users || !signedIn) return 'account';
+    if (!status.has_github_app) return 'github';
+    if (!status.has_tunnel) return 'tunnel';
+    return 'done';
+  }, [override, status, signedIn]);
+
+  const completeMutation = useMutation({
+    mutationFn: completeSetup,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['setup-status'] });
+      navigate('/projects', { replace: true });
+    },
+  });
+
+  if (statusQuery.isLoading) {
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-[var(--bg-primary)]">
+        <Loader2 size={22} className="animate-spin text-[var(--accent-primary)]" />
+      </div>
+    );
+  }
+
+  // Wizard is optional once the instance is already configured.
+  if (status && !status.needs_setup && !override) {
+    return <Navigate to="/projects" replace />;
+  }
+
+  const steps: { key: Step; label: string }[] = [
+    { key: 'account', label: 'Admin account' },
+    { key: 'github', label: 'Git provider' },
+    { key: 'tunnel', label: 'Public access' },
+    { key: 'done', label: 'Done' },
+  ];
+  const activeIdx = steps.findIndex((s) => s.key === step);
+
+  return (
+    <div className="min-h-screen bg-[var(--bg-primary)] flex flex-col items-center px-5 py-16">
+      <div className="w-full max-w-lg">
+        <div className="flex items-center gap-2 mb-8">
+          {steps.map((s, i) => (
+            <div key={s.key} className="flex items-center gap-2">
+              <div
+                className={`w-6 h-6 rounded-full flex items-center justify-center text-[11px] font-semibold border ${
+                  i < activeIdx
+                    ? 'bg-[var(--accent-primary)] border-[var(--accent-primary)] text-[var(--accent-on)]'
+                    : i === activeIdx
+                      ? 'border-[var(--accent-primary)] text-[var(--accent-primary)]'
+                      : 'border-[var(--border-subtle)] text-[var(--text-muted)]'
+                }`}
+              >
+                {i < activeIdx ? <Check size={12} /> : i + 1}
+              </div>
+              <span
+                className={`text-xs ${i === activeIdx ? 'text-[var(--text-primary)] font-medium' : 'text-[var(--text-muted)]'}`}
+              >
+                {s.label}
+              </span>
+              {i < steps.length - 1 ? <div className="w-6 h-px bg-[var(--border-subtle)]" /> : null}
+            </div>
+          ))}
+        </div>
+
+        {step === 'account' ? (
+          <section className="panel p-6">
+            <h1 className="text-xl font-bold text-[var(--text-primary)]">Welcome to Containr</h1>
+            <p className="mt-2 text-sm text-[var(--text-secondary)]">
+              First boot detected. Create the admin account — registration closes to the public
+              right after, so this account owns the instance.
+            </p>
+            {status?.has_users && !signedIn ? (
+              <div className="mt-4">
+                <p className="text-sm text-[var(--text-secondary)]">
+                  An account already exists — sign in to continue setup.
+                </p>
+                <Link
+                  to="/auth/sign-in?redirect=/setup"
+                  className="mt-4 inline-flex items-center gap-2 h-9 px-4 rounded-[var(--radius-md)] text-sm font-medium text-[var(--accent-on)]"
+                  style={{ background: 'var(--accent-primary)' }}
+                >
+                  Sign in <ChevronRight size={14} />
+                </Link>
+              </div>
+            ) : !status?.has_users ? (
+              <Link
+                to="/auth/sign-up?redirect=/setup"
+                className="mt-4 inline-flex items-center gap-2 h-9 px-4 rounded-[var(--radius-md)] text-sm font-medium text-[var(--accent-on)]"
+                style={{ background: 'var(--accent-primary)' }}
+              >
+                Create admin account <ChevronRight size={14} />
+              </Link>
+            ) : null}
+          </section>
+        ) : null}
+
+        {step === 'github' ? <GitHubStep onNext={() => setOverride('tunnel')} /> : null}
+        {step === 'tunnel' ? <TunnelStep onNext={() => setOverride('done')} /> : null}
+
+        {step === 'done' ? (
+          <section className="panel p-6 text-center">
+            <Rocket size={28} className="mx-auto text-[var(--accent-primary)]" />
+            <h1 className="mt-4 text-xl font-bold text-[var(--text-primary)]">All set</h1>
+            <p className="mt-2 text-sm text-[var(--text-secondary)]">
+              Deploy your first service from a git repo, an image, or a template — the dashboard is
+              ready.
+            </p>
+            {completeMutation.isError ? (
+              <p className="mt-3 text-xs text-[var(--error)]">
+                {completeMutation.error instanceof Error
+                  ? completeMutation.error.message
+                  : 'Failed to save setup state'}
+              </p>
+            ) : null}
+            <button
+              type="button"
+              onClick={() => completeMutation.mutate()}
+              disabled={completeMutation.isPending}
+              className="mt-5 inline-flex items-center gap-2 h-10 px-6 rounded-[var(--radius-md)] text-sm font-semibold text-[var(--accent-on)] disabled:opacity-50"
+              style={{ background: 'var(--accent-primary)' }}
+            >
+              {completeMutation.isPending ? (
+                <Loader2 size={14} className="animate-spin" />
+              ) : (
+                <ShieldCheck size={15} />
+              )}
+              Enter Containr
+            </button>
+          </section>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+function GitHubStep({ onNext }: { onNext: () => void }) {
+  const queryClient = useQueryClient();
+  const provisionMutation = useMutation({
+    mutationFn: async () => {
+      const { url, manifest } = await createGitHubAppManifest({
+        base_url: window.location.origin,
+      });
+      sessionStorage.setItem(SETUP_RETURN_KEY, '1');
+      const form = document.createElement('form');
+      form.method = 'POST';
+      form.action = url;
+      const input = document.createElement('input');
+      input.type = 'hidden';
+      input.name = 'manifest';
+      input.value = manifest;
+      form.appendChild(input);
+      document.body.appendChild(form);
+      form.submit();
+    },
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['setup-status'] }),
+  });
+
+  return (
+    <section className="panel p-6">
+      <div className="flex items-center gap-3 mb-3">
+        <Github size={20} className="text-[var(--text-primary)]" />
+        <h1 className="text-xl font-bold text-[var(--text-primary)]">Connect a git provider</h1>
+      </div>
+      <p className="text-sm text-[var(--text-secondary)]">
+        Provision the instance GitHub App — repo push events then trigger deployments and preview
+        environments automatically. Self-hosted GitLab/Gitea can be added later in Settings.
+      </p>
+      {provisionMutation.isError ? (
+        <p className="mt-3 text-xs text-[var(--error)]">
+          {provisionMutation.error instanceof Error
+            ? provisionMutation.error.message
+            : 'Could not start GitHub App provisioning'}
+        </p>
+      ) : null}
+      <div className="mt-5 flex items-center gap-3">
+        <button
+          type="button"
+          onClick={() => provisionMutation.mutate()}
+          disabled={provisionMutation.isPending}
+          className="inline-flex items-center gap-2 h-9 px-4 rounded-[var(--radius-md)] text-sm font-medium text-[var(--accent-on)] disabled:opacity-50"
+          style={{ background: 'var(--accent-primary)' }}
+        >
+          {provisionMutation.isPending ? <Loader2 size={14} className="animate-spin" /> : null}
+          Set up GitHub App
+        </button>
+        <button
+          type="button"
+          onClick={onNext}
+          className="h-9 px-4 rounded-[var(--radius-md)] border border-[var(--border-subtle)] text-sm text-[var(--text-secondary)] hover:text-[var(--text-primary)] transition-colors"
+        >
+          Skip for now
+        </button>
+      </div>
+    </section>
+  );
+}
+
+function TunnelStep({ onNext }: { onNext: () => void }) {
+  const queryClient = useQueryClient();
+  const [token, setToken] = useState('');
+  const saveMutation = useMutation({
+    mutationFn: () =>
+      updatePlatformSettings({ cloudflareTunnelToken: token.trim() || undefined }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['setup-status'] });
+      onNext();
+    },
+  });
+
+  return (
+    <section className="panel p-6">
+      <h1 className="text-xl font-bold text-[var(--text-primary)]">Public access (optional)</h1>
+      <p className="mt-2 text-sm text-[var(--text-secondary)]">
+        Paste a Cloudflare Tunnel token to expose this instance on the internet. Without one,
+        Containr stays reachable on this network — you can add it later in Settings.
+      </p>
+      <input
+        type="password"
+        value={token}
+        onChange={(e) => setToken(e.target.value)}
+        placeholder="eyJhIjo… tunnel token"
+        className="mt-4 w-full h-10 px-3 rounded-[var(--radius-md)] border border-[var(--border-subtle)] bg-[var(--surface-muted)] text-sm text-[var(--text-primary)] placeholder:text-[var(--text-muted)] focus:border-[var(--accent-primary)] transition-colors"
+      />
+      {saveMutation.isError ? (
+        <p className="mt-3 text-xs text-[var(--error)]">
+          {saveMutation.error instanceof Error ? saveMutation.error.message : 'Failed to save token'}
+        </p>
+      ) : null}
+      <div className="mt-5 flex items-center gap-3">
+        <button
+          type="button"
+          onClick={() => (token.trim() ? saveMutation.mutate() : onNext())}
+          disabled={saveMutation.isPending}
+          className="inline-flex items-center gap-2 h-9 px-4 rounded-[var(--radius-md)] text-sm font-medium text-[var(--accent-on)] disabled:opacity-50"
+          style={{ background: 'var(--accent-primary)' }}
+        >
+          {saveMutation.isPending ? <Loader2 size={14} className="animate-spin" /> : null}
+          {token.trim() ? 'Save tunnel token' : 'Continue'}
+        </button>
+        <button
+          type="button"
+          onClick={onNext}
+          className="h-9 px-4 rounded-[var(--radius-md)] border border-[var(--border-subtle)] text-sm text-[var(--text-secondary)] hover:text-[var(--text-primary)] transition-colors"
+        >
+          Skip
+        </button>
+      </div>
+    </section>
+  );
+}

app/frontend/src/features/templates/builder/TemplateBuilder.tsx

@@ -0,0 +1,467 @@
+import { useCallback, useMemo, useState } from 'react';
+import {
+  Background,
+  BackgroundVariant,
+  Handle,
+  MarkerType,
+  Position,
+  ReactFlow,
+  ReactFlowProvider,
+  useReactFlow,
+  type Connection,
+  type Edge,
+  type EdgeChange,
+  type Node,
+  type NodeChange,
+  type NodeProps,
+} from '@xyflow/react';
+import '@xyflow/react/dist/style.css';
+import { Database, GitBranch, Package, Timer, Trash2, X } from 'lucide-react';
+import {
+  canvasFromConfig,
+  configFromCanvas,
+  newServiceKey,
+  validateGraph,
+  type BuilderNode,
+  type BuilderService,
+  type BuilderServiceType,
+} from './builder-model';
+
+type ServiceBuilderNode = Node<{ svc: BuilderService }, 'tplService'>;
+
+const TYPE_META: Record<BuilderServiceType, { label: string; icon: typeof Package; cls: string }> = {
+  web: { label: 'Web', icon: Package, cls: 'text-[var(--accent-primary)]' },
+  worker: { label: 'Worker', icon: GitBranch, cls: 'text-[var(--info,#5eb3f6)]' },
+  cron: { label: 'Cron', icon: Timer, cls: 'text-[var(--warning)]' },
+  database: { label: 'Database', icon: Database, cls: 'text-[var(--success,#7bd88a)]' },
+};
+
+const DATABASE_ENGINES = ['postgresql', 'mysql', 'mariadb', 'mongodb', 'redis', 'dragonfly', 'clickhouse'];
+
+function ServiceBuilderNodeView({ data, selected }: NodeProps<ServiceBuilderNode>) {
+  const meta = TYPE_META[data.svc.type] ?? TYPE_META.web;
+  const Icon = meta.icon;
+  return (
+    <div
+      className={`relative w-[210px] rounded-[var(--radius-md)] border bg-[var(--bg-elevated)] px-3 py-2.5 shadow-sm transition-colors ${
+        selected ? 'border-[var(--accent-primary)]' : 'border-[var(--border-subtle)]'
+      }`}
+    >
+      <Handle type="target" position={Position.Left} className="!h-2.5 !w-2.5 !border-[var(--border-default)] !bg-[var(--bg-base)]" />
+      <Handle type="source" position={Position.Right} className="!h-2.5 !w-2.5 !border-[var(--border-default)] !bg-[var(--bg-base)]" />
+      <div className="flex items-center gap-2">
+        <Icon size={14} className={meta.cls} />
+        <span className="truncate text-[12.5px] font-semibold text-[var(--text-primary)]">
+          {data.svc.name || data.svc.key}
+        </span>
+      </div>
+      <div className="mt-1 flex items-center justify-between gap-2">
+        <span className="text-[10.5px] uppercase tracking-wide text-[var(--text-tertiary)]">{meta.label}</span>
+        <span className="mono max-w-[120px] truncate text-[10.5px] text-[var(--text-secondary)]">
+          {data.svc.runtime || data.svc.repo || '—'}
+        </span>
+      </div>
+    </div>
+  );
+}
+
+const nodeTypes = { tplService: ServiceBuilderNodeView };
+
+// Edges run dependency → dependent: connecting A → B means "B depends_on A".
+export function TemplateBuilder(props: {
+  config: Record<string, unknown>;
+  onApply: (config: Record<string, unknown>) => void;
+  onCancel: () => void;
+}) {
+  return (
+    <ReactFlowProvider>
+      <BuilderInner {...props} />
+    </ReactFlowProvider>
+  );
+}
+
+function BuilderInner({
+  config,
+  onApply,
+  onCancel,
+}: {
+  config: Record<string, unknown>;
+  onApply: (config: Record<string, unknown>) => void;
+  onCancel: () => void;
+}) {
+  const { screenToFlowPosition } = useReactFlow();
+  const initial = useMemo(() => canvasFromConfig(config), [config]);
+  const [services, setServices] = useState<Map<string, BuilderService>>(
+    () => new Map(initial.map((n) => [n.key, { ...n.service }])),
+  );
+  const [positions, setPositions] = useState<Record<string, { x: number; y: number }>>(
+    () => Object.fromEntries(initial.map((n) => [n.key, n.position])),
+  );
+  const [selectedKey, setSelectedKey] = useState<string | null>(null);
+
+  const flowNodes: ServiceBuilderNode[] = useMemo(
+    () =>
+      [...services.values()].map((svc) => ({
+        id: svc.key,
+        type: 'tplService' as const,
+        position: positions[svc.key] ?? { x: 0, y: 0 },
+        data: { svc },
+        selected: svc.key === selectedKey,
+      })),
+    [services, positions, selectedKey],
+  );
+
+  const flowEdges: Edge[] = useMemo(
+    () =>
+      [...services.values()].flatMap((svc) =>
+        (svc.depends_on ?? [])
+          .filter((dep) => services.has(dep))
+          .map((dep) => ({
+            id: `${dep}->${svc.key}`,
+            source: dep,
+            target: svc.key,
+            markerEnd: { type: MarkerType.ArrowClosed, width: 14, height: 14, color: 'rgba(180,227,74,0.55)' },
+            style: { stroke: 'rgba(180,227,74,0.42)', strokeWidth: 1.6 },
+            className: 'edge-premium',
+          })),
+      ),
+    [services],
+  );
+
+  const builderNodes: BuilderNode[] = useMemo(
+    () =>
+      [...services.values()].map((svc) => ({
+        key: svc.key,
+        service: svc,
+        position: positions[svc.key] ?? { x: 0, y: 0 },
+      })),
+    [services, positions],
+  );
+  const errors = useMemo(() => validateGraph(builderNodes), [builderNodes]);
+
+  const patchService = useCallback((key: string, patch: Partial<BuilderService>) => {
+    setServices((prev) => {
+      const svc = prev.get(key);
+      if (!svc) return prev;
+      const next = new Map(prev);
+      next.set(key, { ...svc, ...patch });
+      return next;
+    });
+  }, []);
+
+  const addService = useCallback((type: BuilderServiceType, position?: { x: number; y: number }) => {
+    setServices((prev) => {
+      const key = newServiceKey(type, new Set(prev.keys()));
+      const next = new Map(prev);
+      next.set(key, {
+        key,
+        type,
+        runtime: type === 'database' ? 'postgresql' : undefined,
+      });
+      setPositions((pos) => ({ ...pos, [key]: position ?? { x: 80, y: 40 + (next.size - 1) * 150 } }));
+      setSelectedKey(key);
+      return next;
+    });
+  }, []);
+
+  const removeService = useCallback((key: string) => {
+    setServices((prev) => {
+      const next = new Map(prev);
+      next.delete(key);
+      for (const svc of next.values()) {
+        svc.depends_on = svc.depends_on?.filter((d) => d !== key);
+      }
+      return next;
+    });
+    setPositions((prev) => {
+      const next = { ...prev };
+      delete next[key];
+      return next;
+    });
+    setSelectedKey((cur) => (cur === key ? null : cur));
+  }, []);
+
+  const onConnect = useCallback(
+    (conn: Connection) => {
+      if (!conn.source || !conn.target || conn.source === conn.target) return;
+      const target = services.get(conn.target);
+      if (!target) return;
+      patchService(conn.target, {
+        depends_on: [...new Set([...(target.depends_on ?? []), conn.source])],
+      });
+    },
+    [patchService, services],
+  );
+
+  const onNodesChange = useCallback(
+    (changes: NodeChange<ServiceBuilderNode>[]) => {
+      for (const ch of changes) {
+        if (ch.type === 'position' && ch.position) {
+          setPositions((prev) => ({ ...prev, [ch.id]: ch.position! }));
+        } else if (ch.type === 'remove') {
+          removeService(ch.id);
+        } else if (ch.type === 'select') {
+          if (ch.selected) setSelectedKey(ch.id);
+        }
+      }
+    },
+    [removeService],
+  );
+
+  const onEdgesChange = useCallback(
+    (changes: EdgeChange<Edge>[]) => {
+      for (const ch of changes) {
+        if (ch.type !== 'remove') continue;
+        const edge = flowEdges.find((e) => e.id === ch.id);
+        if (!edge) continue;
+        const svc = services.get(edge.target);
+        if (svc) {
+          patchService(edge.target, {
+            depends_on: (svc.depends_on ?? []).filter((d) => d !== edge.source),
+          });
+        }
+      }
+    },
+    [flowEdges, patchService, services],
+  );
+
+  const selected = selectedKey ? services.get(selectedKey) : null;
+
+  return (
+    <div className="flex min-h-0 flex-1">
+      <div className="relative flex-1">
+        <div className="absolute left-3 top-3 z-10 flex gap-1.5">
+          {(['web', 'database', 'cron', 'worker'] as const).map((t) => {
+            const meta = TYPE_META[t];
+            const Icon = meta.icon;
+            return (
+              <button
+                key={t}
+                type="button"
+                onClick={() => addService(t)}
+                className="canvas-pill inline-flex items-center gap-1.5 px-2.5 py-1.5 text-[11px] font-medium text-[var(--text-secondary)] hover:text-[var(--text-primary)]"
+              >
+                <Icon size={12} className={meta.cls} />
+                {meta.label}
+              </button>
+            );
+          })}
+        </div>
+        <ReactFlow
+          nodes={flowNodes}
+          edges={flowEdges}
+          nodeTypes={nodeTypes}
+          onNodesChange={onNodesChange}
+          onEdgesChange={onEdgesChange}
+          onConnect={onConnect}
+          onPaneClick={() => setSelectedKey(null)}
+          onDoubleClick={(e) => {
+            if ((e.target as HTMLElement).closest('.react-flow__node')) return;
+            addService('web', screenToFlowPosition({ x: e.clientX, y: e.clientY }));
+          }}
+          fitView
+          deleteKeyCode={['Backspace', 'Delete']}
+          proOptions={{ hideAttribution: true }}
+        >
+          <Background variant={BackgroundVariant.Dots} gap={22} size={1.2} color="rgba(255,255,255,0.07)" />
+        </ReactFlow>
+        <div className="canvas-pill absolute bottom-3 left-3 z-10 px-3 py-1.5 text-[10.5px] text-[var(--text-tertiary)]">
+          drag = move · connect handles = depends_on · double-click = add web · Del = remove
+        </div>
+      </div>
+
+      <div className="flex w-[290px] shrink-0 flex-col border-l border-[var(--border-subtle)]">
+        {selected ? (
+          <Inspector
+            key={selected.key}
+            svc={selected}
+            onPatch={(patch) => patchService(selected.key, patch)}
+            onRemove={() => removeService(selected.key)}
+          />
+        ) : (
+          <div className="flex flex-1 flex-col items-center justify-center gap-2 px-6 text-center">
+            <Package size={22} className="text-[var(--text-tertiary)]" />
+            <p className="text-xs text-[var(--text-tertiary)]">
+              Select a node to edit it, or add one from the toolbar.
+            </p>
+          </div>
+        )}
+        <div className="border-t border-[var(--border-subtle)] p-3">
+          {errors.length > 0 ? (
+            <div className="mb-2 max-h-[90px] overflow-y-auto rounded-[var(--radius-sm)] bg-[var(--error-soft)] px-3 py-2">
+              {errors.map((e) => (
+                <p key={e} className="text-[11px] text-[var(--error)]">• {e}</p>
+              ))}
+            </div>
+          ) : null}
+          <div className="flex gap-2">
+            <button
+              type="button"
+              onClick={onCancel}
+              className="flex-1 rounded-[var(--radius-md)] px-3 py-2 text-xs font-medium text-[var(--text-secondary)] hover:bg-[var(--surface-muted)]"
+            >
+              Back to JSON
+            </button>
+            <button
+              type="button"
+              disabled={errors.length > 0 || services.size === 0}
+              onClick={() => onApply(configFromCanvas(builderNodes, config))}
+              className="flex-1 rounded-[var(--radius-md)] bg-[var(--accent-primary)] px-3 py-2 text-xs font-semibold text-[var(--accent-on)] disabled:opacity-50"
+            >
+              Apply to JSON
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+const FIELD_CLS =
+  'w-full rounded-[var(--radius-sm)] border border-[var(--border-default)] bg-[var(--bg-void)] px-2.5 py-1.5 text-[12px] text-[var(--text-primary)] outline-none focus:border-[var(--accent-primary)]';
+const LABEL_CLS = 'mb-1 block text-[10.5px] font-medium uppercase tracking-wide text-[var(--text-tertiary)]';
+
+function Inspector({
+  svc,
+  onPatch,
+  onRemove,
+}: {
+  svc: BuilderService;
+  onPatch: (patch: Partial<BuilderService>) => void;
+  onRemove: () => void;
+}) {
+  const envText = Object.entries(svc.environment ?? {})
+    .map(([k, v]) => `${k}=${v}`)
+    .join('\n');
+  const volText = (svc.volumes ?? []).map((v) => `${v.source}:${v.target}${v.read_only ? ':ro' : ''}`).join('\n');
+  return (
+    <div className="flex-1 overflow-y-auto p-4">
+      <div className="mb-3 flex items-center justify-between">
+        <span className="text-[12px] font-semibold text-[var(--text-primary)]">{svc.key}</span>
+        <button
+          type="button"
+          onClick={onRemove}
+          className="flex items-center gap-1 rounded-[var(--radius-sm)] px-2 py-1 text-[11px] text-[var(--error)] hover:bg-[var(--error-soft)]"
+        >
+          <Trash2 size={12} /> Remove
+        </button>
+      </div>
+
+      <label className={LABEL_CLS}>Key</label>
+      <input className={FIELD_CLS} value={svc.key} disabled title="Key is the node id — cannot be renamed" />
+
+      <label className={`${LABEL_CLS} mt-3`}>Display name</label>
+      <input className={FIELD_CLS} value={svc.name ?? ''} onChange={(e) => onPatch({ name: e.target.value || undefined })} placeholder="optional" />
+
+      <label className={`${LABEL_CLS} mt-3`}>Type</label>
+      <select
+        className={FIELD_CLS}
+        value={svc.type}
+        onChange={(e) => onPatch({ type: e.target.value as BuilderServiceType })}
+      >
+        <option value="web">Web</option>
+        <option value="worker">Worker</option>
+        <option value="cron">Cron</option>
+        <option value="database">Database</option>
+      </select>
+
+      {svc.type === 'database' ? (
+        <>
+          <label className={`${LABEL_CLS} mt-3`}>Engine</label>
+          <select className={FIELD_CLS} value={svc.runtime ?? 'postgresql'} onChange={(e) => onPatch({ runtime: e.target.value })}>
+            {DATABASE_ENGINES.map((eng) => (
+              <option key={eng} value={eng}>{eng}</option>
+            ))}
+          </select>
+        </>
+      ) : (
+        <>
+          <label className={`${LABEL_CLS} mt-3`}>Image (runtime)</label>
+          <input className={FIELD_CLS} value={svc.runtime ?? ''} onChange={(e) => onPatch({ runtime: e.target.value || undefined })} placeholder="nginx:latest" />
+          <label className={`${LABEL_CLS} mt-3`}>Git repo</label>
+          <input className={FIELD_CLS} value={svc.repo ?? ''} onChange={(e) => onPatch({ repo: e.target.value || undefined })} placeholder="owner/repo or clone URL" />
+          {svc.repo ? (
+            <>
+              <label className={`${LABEL_CLS} mt-3`}>Branch</label>
+              <input className={FIELD_CLS} value={svc.branch ?? ''} onChange={(e) => onPatch({ branch: e.target.value || undefined })} placeholder="main" />
+              <label className={`${LABEL_CLS} mt-3`}>Build command</label>
+              <input className={FIELD_CLS} value={svc.build_command ?? ''} onChange={(e) => onPatch({ build_command: e.target.value || undefined })} />
+            </>
+          ) : null}
+          <label className={`${LABEL_CLS} mt-3`}>Start command</label>
+          <input className={FIELD_CLS} value={svc.start_command ?? ''} onChange={(e) => onPatch({ start_command: e.target.value || undefined })} />
+        </>
+      )}
+
+      {svc.type === 'web' ? (
+        <>
+          <label className={`${LABEL_CLS} mt-3`}>Port</label>
+          <input
+            className={FIELD_CLS}
+            type="number"
+            value={svc.port ?? ''}
+            onChange={(e) => onPatch({ port: e.target.value ? Number(e.target.value) : undefined })}
+          />
+          <label className={`${LABEL_CLS} mt-3`}>Health check path</label>
+          <input className={FIELD_CLS} value={svc.health_check ?? ''} onChange={(e) => onPatch({ health_check: e.target.value || undefined })} placeholder="/health" />
+        </>
+      ) : null}
+
+      <label className={`${LABEL_CLS} mt-3`}>Environment (KEY=value, one per line)</label>
+      <textarea
+        className={`${FIELD_CLS} mono min-h-[70px] resize-y`}
+        defaultValue={envText}
+        spellCheck={false}
+        onBlur={(e) => {
+          const env: Record<string, string> = {};
+          for (const line of e.target.value.split('\n')) {
+            const idx = line.indexOf('=');
+            if (idx > 0) env[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+          }
+          onPatch({ environment: Object.keys(env).length ? env : undefined });
+        }}
+        placeholder={'DATABASE_URL={{service.db.url}}\nSECRET={{secret}}'}
+      />
+
+      <label className={`${LABEL_CLS} mt-3`}>Volumes (source:target[:ro], one per line)</label>
+      <textarea
+        className={`${FIELD_CLS} mono min-h-[50px] resize-y`}
+        defaultValue={volText}
+        spellCheck={false}
+        onBlur={(e) => {
+          const vols = e.target.value
+            .split('\n')
+            .map((l) => l.trim())
+            .filter(Boolean)
+            .map((l) => {
+              const [source, target, ro] = l.split(':');
+              return { source, target, read_only: ro === 'ro' || undefined };
+            })
+            .filter((v) => v.source && v.target);
+          onPatch({ volumes: vols.length ? vols : undefined });
+        }}
+        placeholder={'data:/var/lib/app\n./config:/etc/app:ro'}
+      />
+
+      {(svc.depends_on ?? []).length > 0 ? (
+        <div className="mt-3">
+          <span className={LABEL_CLS}>Depends on</span>
+          <div className="flex flex-wrap gap-1">
+            {svc.depends_on!.map((dep) => (
+              <span key={dep} className="inline-flex items-center gap-1 rounded-full bg-[var(--surface-muted)] px-2 py-0.5 text-[11px] text-[var(--text-secondary)]">
+                {dep}
+                <button
+                  type="button"
+                  onClick={() => onPatch({ depends_on: (svc.depends_on ?? []).filter((d) => d !== dep) })}
+                  className="text-[var(--text-tertiary)] hover:text-[var(--error)]"
+                >
+                  <X size={10} />
+                </button>
+              </span>
+            ))}
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+}

app/frontend/src/features/templates/builder/builder-model.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, it } from 'vitest';
+import {
+  canvasFromConfig,
+  configFromCanvas,
+  layoutPositions,
+  newServiceKey,
+  validateGraph,
+  type BuilderNode,
+} from './builder-model';
+
+const plausibleConfig = {
+  version: 2,
+  services: [
+    { key: 'db', type: 'database', runtime: 'postgresql', environment: { POSTGRES_DB: 'plausible' } },
+    { key: 'events', type: 'database', runtime: 'clickhouse' },
+    {
+      key: 'web',
+      name: 'plausible',
+      type: 'web',
+      runtime: 'ghcr.io/plausible/community-edition:v2',
+      port: 8000,
+      health_check: '/api/health',
+      depends_on: ['db', 'events'],
+      environment: { DATABASE_URL: '{{service.db.url}}' },
+    },
+  ],
+};
+
+describe('canvasFromConfig', () => {
+  it('parses graph services into nodes with auto-layout', () => {
+    const nodes = canvasFromConfig(plausibleConfig);
+    expect(nodes.map((n) => n.key)).toEqual(['db', 'events', 'web']);
+    // databases are roots (depth 0), web depends on both (depth 1)
+    expect(nodes[0].position.x).toBeLessThan(nodes[2].position.x);
+    expect(nodes[1].position.y).toBeGreaterThan(nodes[0].position.y);
+  });
+
+  it('restores saved canvas positions', () => {
+    const nodes = canvasFromConfig({
+      ...plausibleConfig,
+      canvas: { positions: { db: { x: 500, y: 500 } } },
+    });
+    expect(nodes[0].position).toEqual({ x: 500, y: 500 });
+  });
+
+  it('migrates flat legacy configs to a single node', () => {
+    const nodes = canvasFromConfig({
+      type: 'web',
+      runtime: 'nginx:latest',
+      port: 80,
+      environment: { FOO: 'bar' },
+    });
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0].service).toMatchObject({ key: 'app', type: 'web', runtime: 'nginx:latest', port: 80 });
+  });
+
+  it('drops entries without a key', () => {
+    const nodes = canvasFromConfig({ version: 2, services: [{ type: 'web', runtime: 'x' }, { key: 'ok', type: 'web', runtime: 'y' }] });
+    expect(nodes.map((n) => n.key)).toEqual(['ok']);
+  });
+});
+
+describe('configFromCanvas', () => {
+  it('round-trips a graph config', () => {
+    const nodes = canvasFromConfig(plausibleConfig);
+    const config = configFromCanvas(nodes, plausibleConfig);
+    const services = config.services as Record<string, unknown>[];
+    expect(config.version).toBe(2);
+    expect(services).toHaveLength(3);
+    const web = services.find((s) => s.key === 'web')!;
+    expect(web.depends_on).toEqual(['db', 'events']);
+    expect(web.port).toBe(8000);
+    expect((web.environment as Record<string, string>).DATABASE_URL).toBe('{{service.db.url}}');
+  });
+
+  it('persists node positions under config.canvas', () => {
+    const nodes = canvasFromConfig(plausibleConfig);
+    nodes[0].position = { x: 321, y: 123 };
+    const config = configFromCanvas(nodes, {});
+    expect((config.canvas as { positions: Record<string, { x: number; y: number }> }).positions.db).toEqual({ x: 321, y: 123 });
+    // and parses back to the same spot
+    expect(canvasFromConfig(config)[0].position).toEqual({ x: 321, y: 123 });
+  });
+
+  it('strips flat fields when converting a legacy config', () => {
+    const nodes = canvasFromConfig({ type: 'web', runtime: 'nginx:latest', port: 80 });
+    const config = configFromCanvas(nodes, { type: 'web', runtime: 'nginx:latest', port: 80 });
+    expect(config.type).toBeUndefined();
+    expect(config.runtime).toBeUndefined();
+    expect((config.services as unknown[]).length).toBe(1);
+  });
+});
+
+describe('layoutPositions', () => {
+  it('depths follow the depends_on chain', () => {
+    const pos = layoutPositions([
+      { key: 'a', type: 'database', runtime: 'postgresql' },
+      { key: 'b', type: 'web', runtime: 'img', depends_on: ['a'] },
+      { key: 'c', type: 'web', runtime: 'img', depends_on: ['b'] },
+    ]);
+    expect(pos.a.x).toBeLessThan(pos.b.x);
+    expect(pos.b.x).toBeLessThan(pos.c.x);
+  });
+
+  it('a dependency cycle does not hang', () => {
+    const pos = layoutPositions([
+      { key: 'a', type: 'web', runtime: 'x', depends_on: ['b'] },
+      { key: 'b', type: 'web', runtime: 'x', depends_on: ['a'] },
+    ]);
+    expect(pos.a).toBeDefined();
+    expect(pos.b).toBeDefined();
+  });
+});
+
+describe('validateGraph', () => {
+  const node = (key: string, extra: Partial<BuilderNode['service']> = {}): BuilderNode => ({
+    key,
+    position: { x: 0, y: 0 },
+    service: { key, type: 'web', runtime: 'img:1', ...extra },
+  });
+
+  it('accepts a valid graph', () => {
+    expect(validateGraph([node('db', { type: 'database', runtime: 'postgresql' }), node('web', { depends_on: ['db'] })])).toEqual([]);
+  });
+
+  it('rejects duplicate keys', () => {
+    expect(validateGraph([node('a'), node('a')])).toContain('duplicate key "a"');
+  });
+
+  it('rejects bad keys and self-deps', () => {
+    const errs = validateGraph([node('BAD KEY'), node('x', { depends_on: ['x'] })]);
+    expect(errs.some((e) => e.includes('not a valid key'))).toBe(true);
+    expect(errs).toContain('"x" depends on itself');
+  });
+
+  it('rejects deps on missing services', () => {
+    expect(validateGraph([node('web', { depends_on: ['ghost'] })])).toContain(
+      '"web" depends on unknown service "ghost"',
+    );
+  });
+
+  it('rejects database without engine and web without source', () => {
+    const errs = validateGraph([node('db', { type: 'database', runtime: undefined }), node('web', { runtime: undefined })]);
+    expect(errs).toContain('"db" is a database with no engine selected');
+    expect(errs).toContain('"web" needs an image (runtime) or a git repo');
+  });
+
+  it('reports dependency cycles', () => {
+    const errs = validateGraph([node('a', { depends_on: ['b'] }), node('b', { depends_on: ['a'] })]);
+    expect(errs.some((e) => e.startsWith('dependency cycle'))).toBe(true);
+  });
+});
+
+describe('newServiceKey', () => {
+  it('picks unused keys', () => {
+    expect(newServiceKey('database', new Set())).toBe('db');
+    expect(newServiceKey('database', new Set(['db']))).toBe('db2');
+    expect(newServiceKey('web', new Set(['web', 'web2']))).toBe('web3');
+  });
+});

app/frontend/src/features/templates/builder/builder-model.ts

@@ -0,0 +1,241 @@
+// Pure model for the visual template builder: converts between the
+// template `config` JSON (version 2 service graph, or a legacy flat
+// single-service config) and canvas state (nodes + positions), and
+// validates the graph before save. No React, no DOM — directly testable.
+
+export type BuilderServiceType = 'web' | 'worker' | 'cron' | 'database';
+
+export type BuilderService = {
+  key: string;
+  name?: string;
+  type: BuilderServiceType;
+  runtime?: string;
+  repo?: string;
+  branch?: string;
+  build_command?: string;
+  start_command?: string;
+  port?: number;
+  health_check?: string;
+  builder?: string;
+  environment?: Record<string, string>;
+  volumes?: { type?: string; source: string; target: string; read_only?: boolean }[];
+  depends_on?: string[];
+};
+
+export type BuilderCanvas = {
+  positions: Record<string, { x: number; y: number }>;
+};
+
+export type BuilderNode = {
+  key: string;
+  service: BuilderService;
+  position: { x: number; y: number };
+};
+
+const KEY_RE = /^[a-z][a-z0-9_-]*$/;
+const COL_X = 60;
+const ROW_Y = 200;
+
+function asService(raw: unknown): BuilderService | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const s = raw as Record<string, unknown>;
+  const key = typeof s.key === 'string' ? s.key : '';
+  if (!key) return null;
+  const type = typeof s.type === 'string' ? s.type : 'web';
+  return {
+    key,
+    name: typeof s.name === 'string' ? s.name : undefined,
+    type: (['web', 'worker', 'cron', 'database'] as const).includes(type as BuilderServiceType)
+      ? (type as BuilderServiceType)
+      : 'web',
+    runtime: typeof s.runtime === 'string' ? s.runtime : undefined,
+    repo: typeof s.repo === 'string' ? s.repo : undefined,
+    branch: typeof s.branch === 'string' ? s.branch : undefined,
+    build_command: typeof s.build_command === 'string' ? s.build_command : undefined,
+    start_command: typeof s.start_command === 'string' ? s.start_command : undefined,
+    port: typeof s.port === 'number' ? s.port : undefined,
+    health_check: typeof s.health_check === 'string' ? s.health_check : undefined,
+    builder: typeof s.builder === 'string' ? s.builder : undefined,
+    environment:
+      s.environment && typeof s.environment === 'object' && !Array.isArray(s.environment)
+        ? Object.fromEntries(
+            Object.entries(s.environment as Record<string, unknown>).map(([k, v]) => [k, String(v)]),
+          )
+        : undefined,
+    volumes: Array.isArray(s.volumes)
+      ? (s.volumes
+          .map((v) => {
+            if (!v || typeof v !== 'object') return null;
+            const vol = v as Record<string, unknown>;
+            if (typeof vol.target !== 'string' || !vol.target) return null;
+            return {
+              type: typeof vol.type === 'string' ? vol.type : undefined,
+              source: typeof vol.source === 'string' ? vol.source : '',
+              target: vol.target,
+              read_only: typeof vol.read_only === 'boolean' ? vol.read_only : undefined,
+            };
+          })
+          .filter((v): v is NonNullable<typeof v> => v !== null)
+        )
+      : undefined,
+    depends_on: Array.isArray(s.depends_on)
+      ? s.depends_on.filter((d): d is string => typeof d === 'string')
+      : undefined,
+  };
+}
+
+// Flat legacy configs ({type, runtime, port, …} with no services array)
+// map to a single service node so the builder can edit them without
+// losing fields the round-trip would drop.
+function flatToService(config: Record<string, unknown>): BuilderService | null {
+  const type = typeof config.type === 'string' ? config.type : '';
+  const runtime = typeof config.runtime === 'string' ? config.runtime : '';
+  if (!type && !runtime) return null;
+  const svc = asService({
+    key: 'app',
+    type: type || 'web',
+    runtime,
+    port: config.port,
+    health_check: config.health_check,
+    build_command: config.build_command,
+    start_command: config.start_command,
+    environment: config.environment,
+  });
+  return svc;
+}
+
+// Layered auto-layout: depth = longest depends_on chain; column per
+// depth, row per member. Deterministic so tests can assert positions.
+export function layoutPositions(services: BuilderService[]): Record<string, { x: number; y: number }> {
+  const depth = new Map<string, number>();
+  const visiting = new Set<string>();
+  const byKey = new Map(services.map((s) => [s.key, s]));
+  const depthOf = (key: string): number => {
+    const memo = depth.get(key);
+    if (memo !== undefined) return memo;
+    if (visiting.has(key)) return 0; // cycle guard
+    visiting.add(key);
+    const deps = byKey.get(key)?.depends_on ?? [];
+    let d = 0;
+    for (const dep of deps) {
+      if (byKey.has(dep)) d = Math.max(d, depthOf(dep) + 1);
+    }
+    visiting.delete(key);
+    depth.set(key, d);
+    return d;
+  };
+  const rows = new Map<number, number>();
+  const positions: Record<string, { x: number; y: number }> = {};
+  for (const svc of services) {
+    const d = depthOf(svc.key);
+    const row = rows.get(d) ?? 0;
+    rows.set(d, row + 1);
+    positions[svc.key] = { x: COL_X + d * 300, y: 40 + row * ROW_Y };
+  }
+  return positions;
+}
+
+export function canvasFromConfig(config: Record<string, unknown>): BuilderNode[] {
+  const canvas = (config.canvas ?? {}) as Partial<BuilderCanvas>;
+  const saved = canvas.positions ?? {};
+  const rawServices = Array.isArray(config.services) ? config.services : null;
+  const services = rawServices
+    ? rawServices.map(asService).filter((s): s is BuilderService => s !== null)
+    : [];
+  if (services.length === 0) {
+    const flat = flatToService(config);
+    if (flat) services.push(flat);
+  }
+  const auto = layoutPositions(services);
+  return services.map((service) => ({
+    key: service.key,
+    service,
+    position: saved[service.key] ?? auto[service.key] ?? { x: COL_X, y: 40 },
+  }));
+}
+
+export function configFromCanvas(
+  nodes: BuilderNode[],
+  rest: Record<string, unknown>,
+): Record<string, unknown> {
+  const services = nodes.map((node) => {
+    const svc = node.service;
+    const out: Record<string, unknown> = { key: svc.key, type: svc.type };
+    if (svc.name) out.name = svc.name;
+    if (svc.runtime) out.runtime = svc.runtime;
+    if (svc.repo) out.repo = svc.repo;
+    if (svc.branch) out.branch = svc.branch;
+    if (svc.build_command) out.build_command = svc.build_command;
+    if (svc.builder) out.builder = svc.builder;
+    if (svc.start_command) out.start_command = svc.start_command;
+    if (svc.port) out.port = svc.port;
+    if (svc.health_check) out.health_check = svc.health_check;
+    if (svc.environment && Object.keys(svc.environment).length > 0) out.environment = svc.environment;
+    if (svc.volumes && svc.volumes.length > 0) out.volumes = svc.volumes;
+    if (svc.depends_on && svc.depends_on.length > 0) out.depends_on = svc.depends_on;
+    return out;
+  });
+  const positions: Record<string, { x: number; y: number }> = {};
+  for (const node of nodes) positions[node.key] = node.position;
+  const restConfig = { ...rest };
+  // Flat (v1) fields and stale graph keys are dropped — the graph wins.
+  for (const k of ['type', 'runtime', 'build_command', 'start_command', 'port', 'health_check', 'environment', 'dockerfile', 'nixpacks_config', 'services', 'canvas']) {
+    delete restConfig[k];
+  }
+  return {
+    version: 2,
+    ...restConfig,
+    services,
+    canvas: { positions },
+  };
+}
+
+export function validateGraph(nodes: BuilderNode[]): string[] {
+  const errors: string[] = [];
+  const keys = new Set<string>();
+  for (const node of nodes) {
+    if (!KEY_RE.test(node.service.key)) {
+      errors.push(`"${node.service.key || '(empty)'}" is not a valid key (lowercase, digits, - or _)`);
+    }
+    if (keys.has(node.service.key)) errors.push(`duplicate key "${node.service.key}"`);
+    keys.add(node.service.key);
+    if (node.service.type === 'database' && !node.service.runtime) {
+      errors.push(`"${node.service.key}" is a database with no engine selected`);
+    }
+    if (node.service.type !== 'database' && !node.service.runtime && !node.service.repo) {
+      errors.push(`"${node.service.key}" needs an image (runtime) or a git repo`);
+    }
+  }
+  for (const node of nodes) {
+    for (const dep of node.service.depends_on ?? []) {
+      if (dep === node.service.key) errors.push(`"${dep}" depends on itself`);
+      else if (!keys.has(dep)) errors.push(`"${node.service.key}" depends on unknown service "${dep}"`);
+    }
+  }
+  // Cycle detection — a cycle makes topo sort fail at deploy time.
+  const state = new Map<string, 0 | 1 | 2>();
+  const byKey = new Map(nodes.map((n) => [n.service.key, n]));
+  const visit = (key: string, trail: string[]): void => {
+    const s = state.get(key) ?? 0;
+    if (s === 2) return;
+    if (s === 1) {
+      errors.push(`dependency cycle: ${[...trail, key].join(' → ')}`);
+      return;
+    }
+    state.set(key, 1);
+    for (const dep of byKey.get(key)?.service.depends_on ?? []) {
+      if (byKey.has(dep)) visit(dep, [...trail, key]);
+    }
+    state.set(key, 2);
+  };
+  for (const node of nodes) visit(node.service.key, []);
+  return errors;
+}
+
+export function newServiceKey(type: BuilderServiceType, existing: Set<string>): string {
+  const base = type === 'database' ? 'db' : type;
+  if (!existing.has(base)) return base;
+  let i = 2;
+  while (existing.has(`${base}${i}`)) i += 1;
+  return `${base}${i}`;
+}

app/frontend/src/features/templates/pages/TemplatesPage.tsx

@@ -1,4 +1,4 @@
-import { useMemo, useState } from 'react';
+import { lazy, Suspense, useMemo, useState } from 'react';
 import { Link, useSearchParams } from 'react-router-dom';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import {
@@ -42,6 +42,10 @@ import {
   Network,
 } from 'lucide-react';
 
+const TemplateBuilder = lazy(() =>
+  import('@/features/templates/builder/TemplateBuilder').then((m) => ({ default: m.TemplateBuilder })),
+);
+
 function toServiceName(value: string): string {
   const normalized = value
     .toLowerCase()
@@ -127,6 +131,7 @@ export function TemplatesPage() {
   const isAdmin = Boolean(profileQuery.data?.isAdmin);
 
   const [editorOpen, setEditorOpen] = useState(false);
+  const [editorMode, setEditorMode] = useState<'json' | 'visual'>('json');
   const [editorJson, setEditorJson] = useState(EMPTY_TEMPLATE_JSON);
   const [editingTemplate, setEditingTemplate] = useState<TemplateEntity | null>(null);
   const [editorIsPublic, setEditorIsPublic] = useState(false);
@@ -1022,17 +1027,50 @@ export function TemplatesPage() {
       {/* Template editor — JSON only */}
       {editorOpen ? (
         <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4 backdrop-blur-sm">
-          <div className="flex max-h-[90vh] w-full max-w-2xl flex-col overflow-hidden rounded-[var(--radius-lg)] border border-[var(--border-subtle)] bg-[var(--bg-base)] shadow-2xl">
+          <div className={`flex max-h-[92vh] w-full flex-col overflow-hidden rounded-[var(--radius-lg)] border border-[var(--border-subtle)] bg-[var(--bg-base)] shadow-2xl ${editorMode === 'visual' ? 'max-w-6xl' : 'max-w-2xl'}`}>
             <div className="flex items-center justify-between border-b border-[var(--border-subtle)] px-5 py-4">
               <div>
                 <h2 className="text-[15px] font-semibold text-[var(--text-primary)]">
                   {editingTemplate ? `Edit ${editingTemplate.name}` : 'New template'}
                 </h2>
                 <p className="text-xs text-[var(--text-tertiary)]">
-                  JSON definition — name, category, config and variables.
+                  {editorMode === 'visual'
+                    ? 'Visual builder — drop service nodes, wire depends_on edges, apply back to JSON.'
+                    : 'JSON definition — name, category, config and variables.'}
                 </p>
               </div>
               <div className="flex items-center gap-2">
+                <div className="mr-1 inline-flex overflow-hidden rounded-[var(--radius-md)] border border-[var(--border-default)]">
+                  {(['json', 'visual'] as const).map((mode) => (
+                    <button
+                      key={mode}
+                      type="button"
+                      onClick={() => {
+                        if (mode === 'visual' && editorMode === 'json') {
+                          try {
+                            const parsed = JSON.parse(editorJson);
+                            if (!parsed || typeof parsed.config !== 'object') {
+                              setEditorError('Visual mode needs a valid JSON body with a "config" object first.');
+                              return;
+                            }
+                          } catch {
+                            setEditorError('Fix the JSON before switching to visual mode.');
+                            return;
+                          }
+                          setEditorError(null);
+                        }
+                        setEditorMode(mode);
+                      }}
+                      className={`px-3 py-1.5 text-[11px] font-medium capitalize ${
+                        editorMode === mode
+                          ? 'bg-[var(--surface-muted)] text-[var(--text-primary)]'
+                          : 'text-[var(--text-tertiary)] hover:text-[var(--text-primary)]'
+                      }`}
+                    >
+                      {mode}
+                    </button>
+                  ))}
+                </div>
                 <label className="inline-flex cursor-pointer items-center gap-1.5 rounded-[var(--radius-md)] border border-[var(--border-default)] px-3 py-1.5 text-xs font-medium text-[var(--text-secondary)] hover:text-[var(--text-primary)]">
                   <Upload size={12} /> Upload .json
                   <input
@@ -1055,12 +1093,49 @@ export function TemplatesPage() {
                 </button>
               </div>
             </div>
+            {editorMode === 'visual' ? (
+              <div className="flex min-h-[520px] flex-1 flex-col">
+                <Suspense
+                  fallback={
+                    <div className="flex flex-1 items-center justify-center text-[var(--text-tertiary)]">
+                      <Loader2 size={20} className="animate-spin" />
+                    </div>
+                  }
+                >
+                  {(() => {
+                    let cfg: Record<string, unknown> = {};
+                    try {
+                      const parsed = JSON.parse(editorJson) as { config?: Record<string, unknown> };
+                      cfg = parsed?.config ?? {};
+                    } catch {
+                      cfg = {};
+                    }
+                    return (
+                      <TemplateBuilder
+                        config={cfg}
+                        onCancel={() => setEditorMode('json')}
+                        onApply={(newConfig) => {
+                          try {
+                            const parsed = JSON.parse(editorJson) as Record<string, unknown>;
+                            setEditorJson(JSON.stringify({ ...parsed, config: newConfig }, null, 2));
+                          } catch {
+                            setEditorJson(JSON.stringify({ config: newConfig }, null, 2));
+                          }
+                          setEditorMode('json');
+                        }}
+                      />
+                    );
+                  })()}
+                </Suspense>
+              </div>
+            ) : (
               <textarea
                 value={editorJson}
                 onChange={(e) => setEditorJson(e.target.value)}
                 spellCheck={false}
                 className="mono min-h-[380px] flex-1 resize-none bg-[var(--bg-void)] p-4 text-[12.5px] leading-relaxed text-[var(--text-secondary)] outline-none"
               />
+            )}
             {composeWarnings.length > 0 ? (
               <div className="border-t border-[var(--border-subtle)] bg-[var(--warning-soft)]/60 px-5 py-2.5 text-xs text-[var(--warning)]">
                 <p className="font-medium mb-1">Compose import notes</p>
@@ -1074,7 +1149,7 @@ export function TemplatesPage() {
                 {editorError}
               </div>
             ) : null}
-            <div className="flex items-center justify-between border-t border-[var(--border-subtle)] px-5 py-3.5">
+            <div className={`flex items-center justify-between border-t border-[var(--border-subtle)] px-5 py-3.5 ${editorMode === 'visual' ? 'hidden' : ''}`}>
               <label className="inline-flex cursor-pointer items-center gap-2 text-[11px] text-[var(--text-secondary)]">
                 <input
                   type="checkbox"

app/frontend/src/features/workspace/canvas/ProjectCanvas.tsx

@@ -25,14 +25,22 @@ import {
 } from '@/lib/api-client';
 import { useToast } from '@/shared/hooks/use-toast';
 import { inferAutoConnections, type ServiceVariable } from '../auto-connections';
-import {
-  DEFAULT_VIEWPORT,
-  type CanvasGroup,
-  type CanvasNodeLayout,
-  type ProjectCanvasMetadata,
-} from '../model';
+import { DEFAULT_VIEWPORT, type ProjectCanvasMetadata } from '../model';
 import { hasCanvasMetadata, loadCanvasMetadata, saveCanvasMetadata } from '../storage';
 import { computeLayeredLayout, layoutFromVariables, NODE_HEIGHT, NODE_WIDTH } from './auto-layout';
+import {
+  buildMetadataFromFlow,
+  GROUP_DEFAULT_HEIGHT,
+  GROUP_DEFAULT_WIDTH,
+  GROUP_PAD_BOTTOM,
+  GROUP_PAD_TOP,
+  GROUP_PAD_X,
+  GRID_STEP,
+  groupSlot,
+  resolveFreeSpot,
+  type CanvasNode,
+  type Rect,
+} from './layout';
 import { GroupNode, ServiceNode, type GroupNodeData, type ServiceNodeData } from './nodes';
 import { ServiceInspector, type InspectorGroup } from './inspector';
 import { serviceAccent } from './service-visuals';
@@ -65,11 +73,7 @@ type CanvasProps = {
 
 type ServiceCanvasNode = Node<ServiceNodeData, 'serviceNode'>;
 type GroupCanvasNode = Node<GroupNodeData, 'groupNode'>;
-type CanvasNode = ServiceCanvasNode | GroupCanvasNode;
 type CanvasEdge = Edge<{ reasons: string[] }>;
-
-const GROUP_DEFAULT_WIDTH = 340;
-const GROUP_DEFAULT_HEIGHT = 230;
 const TRANSIENT_STATUSES = new Set(['building', 'deploying', 'pending', 'rolling_back']);
 
 const nodeTypes: NodeTypes = {
@@ -176,155 +180,6 @@ function toFlowEdges(
   });
 }
 
-const GROUP_PAD_X = 28;
-const GROUP_PAD_TOP = 56;
-const GROUP_PAD_BOTTOM = 24;
-const GROUP_ROW_GAP = 16;
-const GRID_STEP = 26;
-const NODE_GAP = 14;
-
-type Rect = { x: number; y: number; w: number; h: number };
-
-function rectsOverlap(a: Rect, b: Rect): boolean {
-  return (
-    a.x < b.x + b.w + NODE_GAP &&
-    a.x + a.w + NODE_GAP > b.x &&
-    a.y < b.y + b.h + NODE_GAP &&
-    a.y + a.h + NODE_GAP > b.y
-  );
-}
-
-// Nearest grid-aligned position where a node fits without touching any
-// occupied rect. Spiral-searches outward on the canvas lattice; falls back to
-// the given position when the neighbourhood is fully boxed in.
-function resolveFreeSpot(
-  desired: { x: number; y: number },
-  occupied: Rect[],
-  fallback: { x: number; y: number },
-  bounds?: Rect,
-): { x: number; y: number } {
-  const snap = (v: number) => Math.round(v / GRID_STEP) * GRID_STEP;
-  const base = { x: snap(desired.x), y: snap(desired.y) };
-  const fits = (x: number, y: number) => {
-    if (bounds && (x < bounds.x || y < bounds.y || x + NODE_WIDTH > bounds.x + bounds.w || y + NODE_HEIGHT > bounds.y + bounds.h)) {
-      return false;
-    }
-    return !occupied.some((rect) => rectsOverlap({ x, y, w: NODE_WIDTH, h: NODE_HEIGHT }, rect));
-  };
-
-  if (fits(base.x, base.y)) {
-    return base;
-  }
-
-  for (let ring = 1; ring <= 12; ring++) {
-    for (let dx = -ring; dx <= ring; dx++) {
-      for (let dy = -ring; dy <= ring; dy++) {
-        if (Math.max(Math.abs(dx), Math.abs(dy)) !== ring) {
-          continue;
-        }
-        const x = base.x + dx * GRID_STEP;
-        const y = base.y + dy * GRID_STEP;
-        if (fits(x, y)) {
-          return { x, y };
-        }
-      }
-    }
-  }
-
-  return fallback;
-}
-
-// Where an incoming service lands inside a group frame. If the point already
-// fits inside the padded area, honour it. Otherwise append beneath the lowest
-// member and grow the frame just enough — keeps groups compact instead of
-// ballooning the frame to wherever the node used to sit.
-function groupSlot(
-  nodes: CanvasNode[],
-  groupId: string,
-  group: CanvasNode,
-  desiredX: number,
-  desiredY: number,
-  ignoreServiceId?: string,
-): { x: number; y: number; width: number; height: number } {
-  const width = typeof group.style?.width === 'number' ? group.style.width : GROUP_DEFAULT_WIDTH;
-  const height = typeof group.style?.height === 'number' ? group.style.height : GROUP_DEFAULT_HEIGHT;
-
-  const members = nodes.filter(
-    (node) => node.type === 'serviceNode' && node.parentId === groupId && node.id !== ignoreServiceId,
-  );
-  const memberRects: Rect[] = members.map((node) => ({
-    x: node.position.x,
-    y: node.position.y,
-    w: NODE_WIDTH,
-    h: NODE_HEIGHT,
-  }));
-  const snap = (v: number) => Math.round(v / GRID_STEP) * GRID_STEP;
-  const snappedX = snap(desiredX);
-  const snappedY = snap(desiredY);
-  const snappedFits =
-    snappedX >= GROUP_PAD_X &&
-    snappedY >= GROUP_PAD_TOP &&
-    snappedX + NODE_WIDTH <= width - GROUP_PAD_X &&
-    snappedY + NODE_HEIGHT <= height - GROUP_PAD_BOTTOM;
-  const collides = memberRects.some((rect) =>
-    rectsOverlap({ x: snappedX, y: snappedY, w: NODE_WIDTH, h: NODE_HEIGHT }, rect),
-  );
-
-  if (snappedFits && !collides) {
-    return { x: snappedX, y: snappedY, width, height };
-  }
-
-  let bottom = GROUP_PAD_TOP - GROUP_ROW_GAP;
-  for (const node of nodes) {
-    if (node.type === 'serviceNode' && node.parentId === groupId && node.id !== ignoreServiceId) {
-      bottom = Math.max(bottom, node.position.y + NODE_HEIGHT);
-    }
-  }
-
-  const x = GROUP_PAD_X;
-  const y = bottom + GROUP_ROW_GAP;
-  return {
-    x,
-    y,
-    width: Math.max(width, x + NODE_WIDTH + GROUP_PAD_X),
-    height: Math.max(height, y + NODE_HEIGHT + GROUP_PAD_BOTTOM),
-  };
-}
-
-function buildMetadataFromFlow(nodes: CanvasNode[], viewport: { x: number; y: number; zoom: number }): ProjectCanvasMetadata {
-  const groups: CanvasGroup[] = [];
-  const layouts: CanvasNodeLayout[] = [];
-
-  for (const node of nodes) {
-    if (node.type === 'groupNode') {
-      const width = typeof node.style?.width === 'number' ? node.style.width : GROUP_DEFAULT_WIDTH;
-      const height = typeof node.style?.height === 'number' ? node.style.height : GROUP_DEFAULT_HEIGHT;
-      groups.push({
-        id: node.id,
-        title: node.data.title,
-        position: node.position,
-        width,
-        height,
-      });
-      continue;
-    }
-
-    if (node.type === 'serviceNode') {
-      layouts.push({
-        serviceId: node.id,
-        position: node.position,
-        groupId: node.parentId,
-      });
-    }
-  }
-
-  return {
-    groups,
-    nodes: layouts,
-    edges: [],
-    viewport,
-  };
-}
 
 function ZoomControls({ onTidy }: { onTidy: () => void }) {
   const { zoom } = useViewport();

app/frontend/src/features/workspace/canvas/canvas-layout.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildMetadataFromFlow,
+  groupSlot,
+  rectsOverlap,
+  resolveFreeSpot,
+} from './layout';
+import { NODE_HEIGHT, NODE_WIDTH } from './auto-layout';
+import type { GroupNodeType, ServiceNodeType } from './nodes';
+
+const GRID_STEP = 26;
+const NODE_GAP = 14;
+
+function serviceNode(
+  id: string,
+  position: { x: number; y: number },
+  parentId?: string,
+): ServiceNodeType {
+  return { id, type: 'serviceNode', position, parentId } as ServiceNodeType;
+}
+
+function groupNode(
+  id: string,
+  width = 340,
+  height = 230,
+): GroupNodeType {
+  return {
+    id,
+    type: 'groupNode',
+    position: { x: 0, y: 0 },
+    style: { width, height },
+    data: { title: `Group ${id}` },
+  } as GroupNodeType;
+}
+
+describe('rectsOverlap', () => {
+  const a = { x: 0, y: 0, w: 100, h: 100 };
+
+  it('detects intersection', () => {
+    expect(rectsOverlap(a, { x: 50, y: 50, w: 100, h: 100 })).toBe(true);
+    expect(rectsOverlap(a, { x: -50, y: -50, w: 100, h: 100 })).toBe(true);
+  });
+
+  it('returns false for fully disjoint rects', () => {
+    expect(rectsOverlap(a, { x: 500, y: 500, w: 100, h: 100 })).toBe(false);
+  });
+
+  it('treats the node gap as a collision zone', () => {
+    // b sits just inside NODE_GAP to the right of a.
+    expect(rectsOverlap(a, { x: 100 + NODE_GAP - 1, y: 0, w: 50, h: 50 })).toBe(true);
+    // Beyond the gap there is no overlap.
+    expect(rectsOverlap(a, { x: 100 + NODE_GAP + 1, y: 0, w: 50, h: 50 })).toBe(false);
+  });
+});
+
+describe('resolveFreeSpot', () => {
+  it('snaps the desired position to the grid when free', () => {
+    const spot = resolveFreeSpot({ x: 40, y: 70 }, [], { x: 0, y: 0 });
+    expect(spot).toEqual({ x: 52, y: 78 });
+    expect(spot.x % GRID_STEP).toBe(0);
+    expect(spot.y % GRID_STEP).toBe(0);
+  });
+
+  it('finds a neighbouring free grid point when occupied', () => {
+    const occupied = [{ x: 0, y: 0, w: NODE_WIDTH, h: NODE_HEIGHT }];
+    const spot = resolveFreeSpot({ x: 0, y: 0 }, occupied, { x: -1, y: -1 });
+    expect(spot).not.toEqual({ x: -1, y: -1 });
+    expect(Number.isInteger(spot.x / GRID_STEP)).toBe(true);
+    expect(Number.isInteger(spot.y / GRID_STEP)).toBe(true);
+    expect(
+      rectsOverlap({ x: spot.x, y: spot.y, w: NODE_WIDTH, h: NODE_HEIGHT }, occupied[0]),
+    ).toBe(false);
+  });
+
+  it('falls back when bounds reject every candidate', () => {
+    // Node is wider than the bounds, so nothing can fit.
+    const bounds = { x: 0, y: 0, w: 10, h: 10 };
+    const fallback = { x: 999, y: 888 };
+    expect(resolveFreeSpot({ x: 0, y: 0 }, [], fallback, bounds)).toEqual(fallback);
+  });
+});
+
+describe('groupSlot', () => {
+  it('honours a point that fits inside the padded frame', () => {
+    const group = groupNode('g1');
+    const slot = groupSlot([group], 'g1', group, 40, 70);
+    expect(slot).toEqual({ x: 52, y: 78, width: 340, height: 230 });
+  });
+
+  it('appends below the lowest member and grows the frame on collision', () => {
+    const group = groupNode('g1');
+    const member = serviceNode('s1', { x: 52, y: 78 }, 'g1');
+    const slot = groupSlot([group, member], 'g1', group, 40, 70);
+    // bottom = 78 + 104 = 182; y = 182 + 16 = 198; grows height to 326.
+    expect(slot.x).toBe(28);
+    expect(slot.y).toBe(198);
+    expect(slot.height).toBe(326);
+    expect(slot.width).toBe(340);
+  });
+
+  it('appends under the padding when the desired point is outside', () => {
+    const group = groupNode('g1');
+    const slot = groupSlot([group], 'g1', group, 5000, 5000);
+    expect(slot).toEqual({ x: 28, y: 56, width: 340, height: 230 });
+  });
+
+  it('ignores the dragged node when checking collisions', () => {
+    const group = groupNode('g1');
+    const dragged = serviceNode('s1', { x: 52, y: 78 }, 'g1');
+    const slot = groupSlot([group, dragged], 'g1', group, 40, 70, 's1');
+    expect(slot).toEqual({ x: 52, y: 78, width: 340, height: 230 });
+  });
+});
+
+describe('buildMetadataFromFlow', () => {
+  it('serializes groups and service layouts', () => {
+    const nodes = [
+      { ...groupNode('g1', 400, 300), position: { x: 10, y: 20 } },
+      serviceNode('s1', { x: 5, y: 6 }, 'g1'),
+      serviceNode('s2', { x: 100, y: 200 }),
+    ];
+    const viewport = { x: 1, y: 2, zoom: 0.5 };
+    const meta = buildMetadataFromFlow(nodes, viewport);
+
+    expect(meta.groups).toEqual([
+      { id: 'g1', title: 'Group g1', position: { x: 10, y: 20 }, width: 400, height: 300 },
+    ]);
+    expect(meta.nodes).toEqual([
+      { serviceId: 's1', position: { x: 5, y: 6 }, groupId: 'g1' },
+      { serviceId: 's2', position: { x: 100, y: 200 }, groupId: undefined },
+    ]);
+    expect(meta.edges).toEqual([]);
+    expect(meta.viewport).toEqual(viewport);
+  });
+
+  it('uses default group dimensions when style is missing', () => {
+    const bare = { id: 'g2', type: 'groupNode', position: { x: 0, y: 0 }, data: { title: 'bare' } } as GroupNodeType;
+    const meta = buildMetadataFromFlow([bare], { x: 0, y: 0, zoom: 1 });
+    expect(meta.groups[0].width).toBe(340);
+    expect(meta.groups[0].height).toBe(230);
+  });
+});

app/frontend/src/features/workspace/canvas/layout.ts

@@ -0,0 +1,156 @@
+import type { CanvasGroup, CanvasNodeLayout, ProjectCanvasMetadata } from '../model';
+import { NODE_HEIGHT, NODE_WIDTH } from './auto-layout';
+import type { GroupNodeType, ServiceNodeType } from './nodes';
+
+export type CanvasNode = ServiceNodeType | GroupNodeType;
+export type Rect = { x: number; y: number; w: number; h: number };
+
+export const GROUP_DEFAULT_WIDTH = 340;
+export const GROUP_DEFAULT_HEIGHT = 230;
+export const GROUP_PAD_X = 28;
+export const GROUP_PAD_TOP = 56;
+export const GROUP_PAD_BOTTOM = 24;
+export const GROUP_ROW_GAP = 16;
+export const GRID_STEP = 26;
+export const NODE_GAP = 14;
+
+export function rectsOverlap(a: Rect, b: Rect): boolean {
+  return (
+    a.x < b.x + b.w + NODE_GAP &&
+    a.x + a.w + NODE_GAP > b.x &&
+    a.y < b.y + b.h + NODE_GAP &&
+    a.y + a.h + NODE_GAP > b.y
+  );
+}
+
+// Nearest grid-aligned position where a node fits without touching any
+// occupied rect. Spiral-searches outward on the canvas lattice; falls back to
+// the given position when the neighbourhood is fully boxed in.
+export function resolveFreeSpot(
+  desired: { x: number; y: number },
+  occupied: Rect[],
+  fallback: { x: number; y: number },
+  bounds?: Rect,
+): { x: number; y: number } {
+  const snap = (v: number) => Math.round(v / GRID_STEP) * GRID_STEP;
+  const base = { x: snap(desired.x), y: snap(desired.y) };
+  const fits = (x: number, y: number) => {
+    if (bounds && (x < bounds.x || y < bounds.y || x + NODE_WIDTH > bounds.x + bounds.w || y + NODE_HEIGHT > bounds.y + bounds.h)) {
+      return false;
+    }
+    return !occupied.some((rect) => rectsOverlap({ x, y, w: NODE_WIDTH, h: NODE_HEIGHT }, rect));
+  };
+
+  if (fits(base.x, base.y)) {
+    return base;
+  }
+
+  for (let ring = 1; ring <= 12; ring++) {
+    for (let dx = -ring; dx <= ring; dx++) {
+      for (let dy = -ring; dy <= ring; dy++) {
+        if (Math.max(Math.abs(dx), Math.abs(dy)) !== ring) {
+          continue;
+        }
+        const x = base.x + dx * GRID_STEP;
+        const y = base.y + dy * GRID_STEP;
+        if (fits(x, y)) {
+          return { x, y };
+        }
+      }
+    }
+  }
+
+  return fallback;
+}
+
+// Where an incoming service lands inside a group frame. If the point already
+// fits inside the padded area, honour it. Otherwise append beneath the lowest
+// member and grow the frame just enough — keeps groups compact instead of
+// ballooning the frame to wherever the node used to sit.
+export function groupSlot(
+  nodes: CanvasNode[],
+  groupId: string,
+  group: CanvasNode,
+  desiredX: number,
+  desiredY: number,
+  ignoreServiceId?: string,
+): { x: number; y: number; width: number; height: number } {
+  const width = typeof group.style?.width === 'number' ? group.style.width : GROUP_DEFAULT_WIDTH;
+  const height = typeof group.style?.height === 'number' ? group.style.height : GROUP_DEFAULT_HEIGHT;
+
+  const members = nodes.filter(
+    (node) => node.type === 'serviceNode' && node.parentId === groupId && node.id !== ignoreServiceId,
+  );
+  const memberRects: Rect[] = members.map((node) => ({
+    x: node.position.x,
+    y: node.position.y,
+    w: NODE_WIDTH,
+    h: NODE_HEIGHT,
+  }));
+  const snap = (v: number) => Math.round(v / GRID_STEP) * GRID_STEP;
+  const snappedX = snap(desiredX);
+  const snappedY = snap(desiredY);
+  const snappedFits =
+    snappedX >= GROUP_PAD_X &&
+    snappedY >= GROUP_PAD_TOP &&
+    snappedX + NODE_WIDTH <= width - GROUP_PAD_X &&
+    snappedY + NODE_HEIGHT <= height - GROUP_PAD_BOTTOM;
+  const collides = memberRects.some((rect) =>
+    rectsOverlap({ x: snappedX, y: snappedY, w: NODE_WIDTH, h: NODE_HEIGHT }, rect),
+  );
+
+  if (snappedFits && !collides) {
+    return { x: snappedX, y: snappedY, width, height };
+  }
+
+  let bottom = GROUP_PAD_TOP - GROUP_ROW_GAP;
+  for (const node of nodes) {
+    if (node.type === 'serviceNode' && node.parentId === groupId && node.id !== ignoreServiceId) {
+      bottom = Math.max(bottom, node.position.y + NODE_HEIGHT);
+    }
+  }
+
+  const x = GROUP_PAD_X;
+  const y = bottom + GROUP_ROW_GAP;
+  return {
+    x,
+    y,
+    width: Math.max(width, x + NODE_WIDTH + GROUP_PAD_X),
+    height: Math.max(height, y + NODE_HEIGHT + GROUP_PAD_BOTTOM),
+  };
+}
+
+export function buildMetadataFromFlow(nodes: CanvasNode[], viewport: { x: number; y: number; zoom: number }): ProjectCanvasMetadata {
+  const groups: CanvasGroup[] = [];
+  const layouts: CanvasNodeLayout[] = [];
+
+  for (const node of nodes) {
+    if (node.type === 'groupNode') {
+      const width = typeof node.style?.width === 'number' ? node.style.width : GROUP_DEFAULT_WIDTH;
+      const height = typeof node.style?.height === 'number' ? node.style.height : GROUP_DEFAULT_HEIGHT;
+      groups.push({
+        id: node.id,
+        title: node.data.title,
+        position: node.position,
+        width,
+        height,
+      });
+      continue;
+    }
+
+    if (node.type === 'serviceNode') {
+      layouts.push({
+        serviceId: node.id,
+        position: node.position,
+        groupId: node.parentId,
+      });
+    }
+  }
+
+  return {
+    groups,
+    nodes: layouts,
+    edges: [],
+    viewport,
+  };
+}

app/frontend/src/generated/api-types.ts

@@ -5633,6 +5633,90 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/setup/status": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * First-run setup status
+         * @description Public. Drives the setup wizard — needs_setup is true until setup_completed is recorded. Instances with users and projects that predate the wizard report completed automatically.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Setup state */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            has_users?: boolean;
+                            setup_completed?: boolean;
+                            needs_setup?: boolean;
+                            /** @description GitHub App credentials configured (manifest flow or env) */
+                            has_github_app?: boolean;
+                            /** @description Cloudflare tunnel token configured */
+                            has_tunnel?: boolean;
+                            signup_enabled?: boolean;
+                        };
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/setup/complete": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Mark the setup wizard complete */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Setup completed */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["MessageResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/settings": {
         parameters: {
             query?: never;

app/frontend/src/lib/api-client.ts

@@ -490,6 +490,32 @@ export function getApiBaseUrl(): string {
   return API_BASE;
 }
 
+// pingServer hits the public /health route — any HTTP response proves
+// reachability, and no auth means no 401 noise in the connectivity probe.
+export async function pingServer(): Promise<void> {
+  const res = await fetch(`${API_ROOT}/health`);
+  if (!res.ok) {
+    throw new Error(`Server returned ${res.status}`);
+  }
+}
+
+export type SetupStatus = {
+  has_users: boolean;
+  setup_completed: boolean;
+  needs_setup: boolean;
+  has_github_app: boolean;
+  has_tunnel: boolean;
+  signup_enabled: boolean;
+};
+
+export async function getSetupStatus(): Promise<SetupStatus> {
+  return requestJson<SetupStatus>('/setup/status');
+}
+
+export async function completeSetup(): Promise<void> {
+  await requestJson('/setup/complete', { method: 'POST', body: JSON.stringify({}) });
+}
+
 export function getAgentPublicBaseUrl(): string {
   return `${API_ROOT}/api/agents`;
 }

app/frontend/src/main.tsx

@@ -1,6 +1,8 @@
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { QueryClient } from '@tanstack/react-query';
+import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';
+import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister';
 import { BrowserRouter } from 'react-router-dom';
 import App from './app/App';
 import { ToastProvider } from './shared/components';
@@ -12,18 +14,49 @@ const queryClient = new QueryClient({
       staleTime: 30_000,
       retry: 1,
       refetchOnWindowFocus: false,
+      // Serve the persisted snapshot while offline instead of erroring.
+      networkMode: 'offlineFirst',
     },
   },
 });
 
+// High-churn or bulky keys never hit localStorage — a stale log tail is
+// worse than none.
+const NEVER_PERSIST = new Set([
+  'shell-notifications',
+  'notifications',
+  'service-logs',
+  'logs',
+  'activity',
+  'audit-logs',
+  'audit',
+  'metrics',
+  'connectivity',
+]);
+
+const persister = createSyncStoragePersister({
+  storage: window.localStorage,
+  key: 'containr-query-cache-v1',
+});
+
 createRoot(document.getElementById('root')!).render(
   <StrictMode>
-    <QueryClientProvider client={queryClient}>
+    <PersistQueryClientProvider
+      client={queryClient}
+      persistOptions={{
+        persister,
+        maxAge: 24 * 60 * 60 * 1000,
+        dehydrateOptions: {
+          shouldDehydrateQuery: (q) =>
+            q.state.status === 'success' && !NEVER_PERSIST.has(String(q.queryKey[0])),
+        },
+      }}
+    >
       <BrowserRouter>
         <ToastProvider>
           <App />
         </ToastProvider>
       </BrowserRouter>
-    </QueryClientProvider>
+    </PersistQueryClientProvider>
   </StrictMode>,
 );

app/mobile/package-lock.json

@@ -9,11 +9,15 @@
       "version": "1.0.0",
       "dependencies": {
         "@expo/vector-icons": "^15.0.2",
+        "@react-native-async-storage/async-storage": "2.2.0",
+        "@tanstack/query-async-storage-persister": "^5.104.1",
         "@tanstack/react-query": "^5.104.1",
+        "@tanstack/react-query-persist-client": "^5.104.1",
         "expo": "~57.0.27",
         "expo-constants": "~57.0.21",
         "expo-font": "~57.0.4",
         "expo-linking": "~57.0.12",
+        "expo-network": "~57.0.2",
         "expo-router": "~57.0.25",
         "expo-secure-store": "~57.0.4",
         "expo-status-bar": "~57.0.1",
@@ -2165,6 +2169,18 @@
         }
       }
     },
+    "node_modules/@react-native-async-storage/async-storage": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/@react-native-async-storage/async-storage/-/async-storage-2.2.0.tgz",
+      "integrity": "sha512-gvRvjR5JAaUZF8tv2Kcq/Gbt3JHwbKFYfmb445rhOj6NUMx3qPLixmDx5pZAyb9at1bYvJ4/eTUipU5aki45xw==",
+      "license": "MIT",
+      "dependencies": {
+        "merge-options": "^3.0.4"
+      },
+      "peerDependencies": {
+        "react-native": "^0.0.0-0 || >=0.65 <1.0"
+      }
+    },
     "node_modules/@react-native-masked-view/masked-view": {
       "version": "0.3.2",
       "resolved": "https://registry.npmjs.org/@react-native-masked-view/masked-view/-/masked-view-0.3.2.tgz",
@@ -2469,6 +2485,20 @@
       "integrity": "sha512-hhyNJ+nbR6ZR7pToHvllEFun9TL0sbL+tk/ON75lo+Xas054uez98qRbsuNt7MBCyZKK4+8Yli/OAGZhmfBZ/g==",
       "license": "MIT"
     },
+    "node_modules/@tanstack/query-async-storage-persister": {
+      "version": "5.104.1",
+      "resolved": "https://registry.npmjs.org/@tanstack/query-async-storage-persister/-/query-async-storage-persister-5.104.1.tgz",
+      "integrity": "sha512-wSs/HrangoSMVW3zLifawRT9lA+fbiilPQmaY+YhxBOM/VS9oqx+MQvROHpW+hKwDpdvFmhyBjWiyDhTHL1YXg==",
+      "license": "MIT",
+      "dependencies": {
+        "@tanstack/query-core": "5.104.1",
+        "@tanstack/query-persist-client-core": "5.104.1"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      }
+    },
     "node_modules/@tanstack/query-core": {
       "version": "5.104.1",
       "resolved": "https://registry.npmjs.org/@tanstack/query-core/-/query-core-5.104.1.tgz",
@@ -2479,6 +2509,19 @@
         "url": "https://github.com/sponsors/tannerlinsley"
       }
     },
+    "node_modules/@tanstack/query-persist-client-core": {
+      "version": "5.104.1",
+      "resolved": "https://registry.npmjs.org/@tanstack/query-persist-client-core/-/query-persist-client-core-5.104.1.tgz",
+      "integrity": "sha512-ONiadXqe56iNrw6RESqKILpTIVG9ZMI/DageTQnrBDt/nZ6WiP4G13iIiMwJEsiO12gQ3Gychx8tcFIPw4k25g==",
+      "license": "MIT",
+      "dependencies": {
+        "@tanstack/query-core": "5.104.1"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      }
+    },
     "node_modules/@tanstack/react-query": {
       "version": "5.104.1",
       "resolved": "https://registry.npmjs.org/@tanstack/react-query/-/react-query-5.104.1.tgz",
@@ -2495,6 +2538,23 @@
         "react": "^18 || ^19"
       }
     },
+    "node_modules/@tanstack/react-query-persist-client": {
+      "version": "5.104.1",
+      "resolved": "https://registry.npmjs.org/@tanstack/react-query-persist-client/-/react-query-persist-client-5.104.1.tgz",
+      "integrity": "sha512-kU3YaqjkwEUzUUfPF0JVg56d6gJKWHaFVqOlQztwc4C2IT0P5sv/23orrSoQqjxKaUe6Ejw5IIQtA/G12uNmow==",
+      "license": "MIT",
+      "dependencies": {
+        "@tanstack/query-persist-client-core": "5.104.1"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      },
+      "peerDependencies": {
+        "@tanstack/react-query": "^5.104.1",
+        "react": "^18 || ^19"
+      }
+    },
     "node_modules/@tybys/wasm-util": {
       "version": "0.10.4",
       "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.4.tgz",
@@ -5416,6 +5476,16 @@
         "react-native": "*"
       }
     },
+    "node_modules/expo-network": {
+      "version": "57.0.2",
+      "resolved": "https://registry.npmjs.org/expo-network/-/expo-network-57.0.2.tgz",
+      "integrity": "sha512-BfK1kdftZcM6o9o1FAG7/y0l6vWX0n8td0M5lwkvaMeRXZ9LkRwOi9CQXwvsMTQGQiPwtQXgwiAze13cqjt75g==",
+      "license": "MIT",
+      "peerDependencies": {
+        "expo": "*",
+        "react": "*"
+      }
+    },
     "node_modules/expo-router": {
       "version": "57.0.25",
       "resolved": "https://registry.npmjs.org/expo-router/-/expo-router-57.0.25.tgz",
@@ -7084,6 +7154,15 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/is-plain-obj": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-2.1.0.tgz",
+      "integrity": "sha512-YWnfyRwxL/+SsrWYfOpUtz5b3YD+nyfkHvjbcanzk8zgyO4ASD67uVMRt8k5bM4lLMDnXfriRhOpemw+NfT1eA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/is-regex": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/is-regex/-/is-regex-1.2.1.tgz",
@@ -7968,6 +8047,18 @@
       "integrity": "sha512-zYiwtZUcYyXKo/np96AGZAckk+FWWsUdJ3cHGGmld7+AhvcWmQyGCYUh1hc4Q/pkOhb65dQR/pqCyK0cOaHz4Q==",
       "license": "MIT"
     },
+    "node_modules/merge-options": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/merge-options/-/merge-options-3.0.4.tgz",
+      "integrity": "sha512-2Sug1+knBjkaMsMgf1ctR1Ujx+Ayku4EdJN4Z+C2+JzoeF7A3OZ9KM2GY0CpQS51NR61LTurMJrRKPhSs3ZRTQ==",
+      "license": "MIT",
+      "dependencies": {
+        "is-plain-obj": "^2.1.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/merge-stream": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz",

app/mobile/package.json

@@ -4,11 +4,15 @@
   "main": "expo-router/entry",
   "dependencies": {
     "@expo/vector-icons": "^15.0.2",
+    "@react-native-async-storage/async-storage": "2.2.0",
+    "@tanstack/query-async-storage-persister": "^5.104.1",
     "@tanstack/react-query": "^5.104.1",
+    "@tanstack/react-query-persist-client": "^5.104.1",
     "expo": "~57.0.27",
     "expo-constants": "~57.0.21",
     "expo-font": "~57.0.4",
     "expo-linking": "~57.0.12",
+    "expo-network": "~57.0.2",
     "expo-router": "~57.0.25",
     "expo-secure-store": "~57.0.4",
     "expo-status-bar": "~57.0.1",

app/mobile/src/api.ts

@@ -102,6 +102,30 @@ export interface NotificationChannel {
   created_at?: string;
 }
 
+export interface CronJob {
+  id: string;
+  service_id?: string;
+  name: string;
+  schedule: string;
+  command: string;
+  timezone?: string;
+  enabled?: boolean;
+  last_run_at?: string;
+  next_run_at?: string;
+  last_status?: string;
+  last_output?: string;
+}
+
+export interface CronExecution {
+  id: string;
+  cron_job_id: string;
+  started_at?: string;
+  finished_at?: string;
+  status?: string;
+  output?: string;
+  error?: string;
+}
+
 // Masked value the API returns for secret variables; echoing it back on
 // update preserves the stored ciphertext.
 export const MASKED_SECRET = '********';
@@ -273,6 +297,24 @@ export class Api {
     return this.req<unknown>('POST', `/notifications/channels/${id}/test`, {});
   }
 
+  cronJobs(serviceId: string) {
+    return this.req<{ cron_jobs: CronJob[] }>(
+      'GET',
+      `/cron-jobs?service_id=${serviceId}`,
+    ).then((r) => r.cron_jobs ?? []);
+  }
+
+  cronExecutions(jobId: string) {
+    return this.req<{ executions: CronExecution[] }>(
+      'GET',
+      `/cron-jobs/${jobId}/executions`,
+    ).then((r) => r.executions ?? []);
+  }
+
+  triggerCronJob(jobId: string) {
+    return this.req<unknown>('POST', `/cron-jobs/${jobId}/trigger`, {});
+  }
+
   serviceDeployments(id: string) {
     return this.req<{ deployments: Deployment[] }>(
       'GET',

app/mobile/src/app/(tabs)/_layout.tsx

@@ -1,10 +1,39 @@
 import React from 'react';
+import { StyleSheet, Text, View } from 'react-native';
 import { Tabs } from 'expo-router';
 import { Ionicons } from '@expo/vector-icons';
 import { useQuery } from '@tanstack/react-query';
+import * as Network from 'expo-network';
 import { useApi } from '../../session';
 import { colors } from '../../theme';
 
+// OfflineBanner pings /health every 15s; expo-network gives a fast local
+// signal, the ping catches "device online but instance down".
+function OfflineBanner() {
+  const api = useApi();
+  const net = useQuery({
+    queryKey: ['connectivity', 'net'],
+    queryFn: async () => (await Network.getNetworkStateAsync()).isConnected !== false,
+    refetchInterval: 15_000,
+  });
+  const ping = useQuery({
+    queryKey: ['connectivity', 'ping'],
+    queryFn: () => api.ping(),
+    refetchInterval: 15_000,
+    retry: 0,
+    networkMode: 'always',
+  });
+  if (net.data !== false && ping.data !== false && !ping.isError) return null;
+  return (
+    <View style={styles.banner}>
+      <Ionicons name="cloud-offline-outline" size={13} color={colors.warn} />
+      <Text style={styles.bannerText}>
+        {net.data === false ? 'No connection' : 'Instance unreachable'} — showing last-known data
+      </Text>
+    </View>
+  );
+}
+
 export default function TabsLayout() {
   const api = useApi();
   const notifs = useQuery({
@@ -15,6 +44,8 @@ export default function TabsLayout() {
   const unread = notifs.data?.unread ?? 0;
 
   return (
+    <View style={{ flex: 1 }}>
+      <OfflineBanner />
       <Tabs
       screenOptions={{
         headerStyle: { backgroundColor: colors.bg },
@@ -71,5 +102,20 @@ export default function TabsLayout() {
         }}
       />
       </Tabs>
+    </View>
   );
 }
+
+const styles = StyleSheet.create({
+  banner: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 6,
+    paddingVertical: 6,
+    backgroundColor: colors.surface,
+    borderBottomWidth: 1,
+    borderBottomColor: colors.warn,
+  },
+  bannerText: { color: colors.textDim, fontSize: 11 },
+});

app/mobile/src/app/_layout.tsx

@@ -1,16 +1,28 @@
 import React, { useEffect } from 'react';
 import { Stack, useRouter, useSegments } from 'expo-router';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { QueryClient } from '@tanstack/react-query';
+import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';
+import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister';
+import AsyncStorage from '@react-native-async-storage/async-storage';
 import { StatusBar } from 'expo-status-bar';
 import { SessionProvider, useSession } from '../session';
 import { colors } from '../theme';
 
 const queryClient = new QueryClient({
   defaultOptions: {
-    queries: { staleTime: 15_000, retry: 1 },
+    queries: { staleTime: 15_000, retry: 1, networkMode: 'offlineFirst' },
   },
 });
 
+// High-churn keys never hit disk — a stale notification count or log
+// tail is worse than none.
+const NEVER_PERSIST = new Set(['notifications', 'notification-channels', 'logs', 'connectivity']);
+
+const persister = createAsyncStoragePersister({
+  storage: AsyncStorage,
+  key: 'containr-query-cache-v1',
+});
+
 function AuthGate() {
   const { ready, api } = useSession();
   const segments = useSegments();
@@ -39,6 +51,7 @@ function AuthGate() {
         <Stack.Screen name="service/logs" options={{ title: 'Logs' }} />
         <Stack.Screen name="service/variables" options={{ title: 'Variables' }} />
         <Stack.Screen name="service/domains" options={{ title: 'Domains' }} />
+        <Stack.Screen name="service/cron" options={{ title: 'Cron jobs' }} />
         <Stack.Screen name="service/settings" options={{ title: 'Service settings' }} />
       </Stack.Protected>
       <Stack.Screen name="login" options={{ headerShown: false }} />
@@ -48,11 +61,21 @@ function AuthGate() {
 
 export default function RootLayout() {
   return (
-    <QueryClientProvider client={queryClient}>
+    <PersistQueryClientProvider
+      client={queryClient}
+      persistOptions={{
+        persister,
+        maxAge: 7 * 24 * 60 * 60 * 1000,
+        dehydrateOptions: {
+          shouldDehydrateQuery: (q) =>
+            q.state.status === 'success' && !NEVER_PERSIST.has(String(q.queryKey[0])),
+        },
+      }}
+    >
       <SessionProvider>
         <StatusBar style="light" />
         <AuthGate />
       </SessionProvider>
-    </QueryClientProvider>
+    </PersistQueryClientProvider>
   );
 }

app/mobile/src/app/service/[id].tsx

@@ -157,6 +157,11 @@ export default function ServiceDetail() {
           subtitle={s.domain ?? 'Hostnames routed to this service'}
           onPress={() => router.push(`/service/domains?id=${s.id}`)}
         />
+        <Row
+          title="Cron jobs"
+          subtitle="Schedules, run now, history"
+          onPress={() => router.push(`/service/cron?id=${s.id}`)}
+        />
         <Row
           title="Scale & sleep"
           subtitle={`${s.replicas ?? 1} replica${(s.replicas ?? 1) === 1 ? '' : 's'}` +

app/mobile/src/app/service/cron.tsx

@@ -0,0 +1,144 @@
+import React, { useState } from 'react';
+import { Alert, RefreshControl, ScrollView, StyleSheet, Text, View } from 'react-native';
+import { useLocalSearchParams } from 'expo-router';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useApi } from '../../session';
+import { colors } from '../../theme';
+import { relTime } from '../../time';
+import {
+  ActionButton,
+  Card,
+  Empty,
+  ErrorBox,
+  Loading,
+  StatusBadge,
+} from '../../components';
+
+export default function ServiceCron() {
+  const { id } = useLocalSearchParams<{ id: string }>();
+  const api = useApi();
+  const qc = useQueryClient();
+  const [historyFor, setHistoryFor] = useState<string | null>(null);
+
+  const jobs = useQuery({
+    queryKey: ['service-cron', id],
+    queryFn: () => api.cronJobs(id!),
+    enabled: !!id,
+    refetchInterval: 15_000,
+  });
+  const executions = useQuery({
+    queryKey: ['cron-executions', historyFor],
+    queryFn: () => api.cronExecutions(historyFor!),
+    enabled: !!historyFor,
+  });
+
+  const trigger = useMutation({
+    mutationFn: (jobId: string) => api.triggerCronJob(jobId),
+    onSuccess: (_d, jobId) => {
+      qc.invalidateQueries({ queryKey: ['service-cron', id] });
+      setHistoryFor(jobId);
+      setTimeout(
+        () => qc.invalidateQueries({ queryKey: ['cron-executions', jobId] }),
+        2000,
+      );
+    },
+    onError: (e) =>
+      Alert.alert('Trigger failed', e instanceof Error ? e.message : String(e)),
+  });
+
+  if (jobs.isLoading) return <Loading />;
+  if (jobs.error) return <ErrorBox error={jobs.error} />;
+
+  const list = jobs.data ?? [];
+
+  return (
+    <ScrollView
+      style={styles.root}
+      contentContainerStyle={{ padding: 16 }}
+      refreshControl={
+        <RefreshControl
+          refreshing={jobs.isRefetching}
+          onRefresh={() => jobs.refetch()}
+          tintColor={colors.accent}
+        />
+      }
+    >
+      {list.length === 0 ? <Empty text="No cron jobs on this service" /> : null}
+      {list.map((job) => (
+        <Card key={job.id}>
+          <View style={styles.jobHead}>
+            <View style={{ flex: 1 }}>
+              <Text style={styles.jobName}>{job.name}</Text>
+              <Text style={styles.meta}>
+                {job.schedule}
+                {job.timezone ? ` · ${job.timezone}` : ''}
+                {job.enabled === false ? ' · disabled' : ''}
+              </Text>
+              <Text style={styles.cmd} numberOfLines={1}>
+                {job.command}
+              </Text>
+              <Text style={styles.meta}>
+                {job.last_run_at ? `last ${relTime(job.last_run_at)}` : 'never run'}
+                {job.next_run_at ? ` · next ${relTime(job.next_run_at)}` : ''}
+              </Text>
+            </View>
+            {job.last_status ? <StatusBadge status={job.last_status} /> : null}
+          </View>
+          <View style={styles.jobActions}>
+            <ActionButton
+              label="Run now"
+              kind="primary"
+              disabled={trigger.isPending}
+              onPress={() => trigger.mutate(job.id)}
+            />
+            <ActionButton
+              label={historyFor === job.id ? 'Hide history' : 'History'}
+              onPress={() => setHistoryFor(historyFor === job.id ? null : job.id)}
+            />
+          </View>
+          {historyFor === job.id ? (
+            <View style={styles.history}>
+              {executions.isLoading ? (
+                <Loading />
+              ) : (executions.data ?? []).length === 0 ? (
+                <Text style={styles.meta}>No executions yet</Text>
+              ) : (
+                (executions.data ?? []).slice(0, 10).map((ex) => (
+                  <View key={ex.id} style={styles.execRow}>
+                    <View style={{ flex: 1 }}>
+                      <Text style={styles.execTime}>{relTime(ex.started_at)}</Text>
+                      {ex.error ? (
+                        <Text style={styles.execErr} numberOfLines={2}>
+                          {ex.error}
+                        </Text>
+                      ) : ex.output ? (
+                        <Text style={styles.execOut} numberOfLines={2}>
+                          {ex.output}
+                        </Text>
+                      ) : null}
+                    </View>
+                    <StatusBadge status={ex.status ?? 'unknown'} />
+                  </View>
+                ))
+              )}
+            </View>
+          ) : null}
+        </Card>
+      ))}
+    </ScrollView>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1, backgroundColor: colors.bg },
+  jobHead: { flexDirection: 'row', alignItems: 'flex-start' },
+  jobName: { color: colors.text, fontSize: 15, fontWeight: '600' },
+  meta: { color: colors.textDim, fontSize: 11, marginTop: 3 },
+  cmd: { color: colors.textDim, fontSize: 12, fontFamily: 'monospace', marginTop: 4 },
+  jobActions: { flexDirection: 'row', gap: 8, marginTop: 10 },
+  history: { marginTop: 10, borderTopWidth: 1, borderTopColor: colors.border, paddingTop: 8 },
+  execRow: { flexDirection: 'row', alignItems: 'flex-start', paddingVertical: 6 },
+  execTime: { color: colors.text, fontSize: 12 },
+  execErr: { color: colors.err, fontSize: 11, marginTop: 2 },
+  execOut: { color: colors.textDim, fontSize: 11, marginTop: 2 },
+});

docs/api/openapi.yaml

@@ -3705,6 +3705,50 @@ paths:
                     type: boolean
                     description: True when the owner re-opened public registration in Settings
 
+  /setup/status:
+    get:
+      tags:
+        - Authentication
+      summary: First-run setup status
+      description: Public. Drives the setup wizard — needs_setup is true until setup_completed is recorded. Instances with users and projects that predate the wizard report completed automatically.
+      responses:
+        '200':
+          description: Setup state
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  has_users:
+                    type: boolean
+                  setup_completed:
+                    type: boolean
+                  needs_setup:
+                    type: boolean
+                  has_github_app:
+                    type: boolean
+                    description: GitHub App credentials configured (manifest flow or env)
+                  has_tunnel:
+                    type: boolean
+                    description: Cloudflare tunnel token configured
+                  signup_enabled:
+                    type: boolean
+
+  /setup/complete:
+    post:
+      tags:
+        - Authentication
+      summary: Mark the setup wizard complete
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: Setup completed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+
   /settings:
     get:
       tags: