feat(#79): HAProxy dashboard stack-layout redesign (#85)

* docs(#79): add HAProxy dashboard stack-layout research

Captures current-state analysis, best-practice survey (Portainer / Lens /
ArgoCD / Datadog / HAProxy stats / Grafana / NN/g), three layout options
with ASCII mockups, and a recommendation (stack-as-section + compact
backend cards). Includes live screenshot of the current dashboard with
the duplicated 6-container Arr stack and live-inspection notes on the
bottom-of-page widgets (which render correctly in current dev — likely
already fixed since the issue was filed).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(#79): hoist stack topology out of repeated backend cards

Previously every backend card re-rendered the full docker-compose stack's
container topology with one container highlighted. A 5-route Arr stack
with 6 containers drew the same 6-container diagram 5 times — visual
noise, wasted vertical space, easy to misread as duplicate state.

Group backends by parsed `BackendGroupInfo.Group` (the docker-compose
project prefix). Multi-backend stacks now render as a labeled `<section>`
with:

  - "STACK" badge + capitalized stack name + "N backends · M containers"
  - The merged container topology rendered ONCE
    (IsBackend OR'd across all members so every actually-routed container
    shows blue)
  - A grid of compact backend cards below — no inline ContainerDiagram

Singleton non-hardware backends and hardware backends fold into trailing
synthetic Standalone / Hardware buckets, which render as a flat card
grid with no wrapper chrome — preserving the existing look-and-feel for
trivial cases (vaultwarden, gitea, IPMI hosts, etc).

Tooltip text in BackendCard gets a new "Stack Member" branch so cards
inside a stack section no longer mislabel themselves as "Hardware
Service". Hardware check moved to the top of the chain to avoid the
empty-containers fall-through.

Verified against the live light-hugger agent:

  - HTML for /htmx/light-hugger/stats contains exactly two `<section>`
    blocks: Arr (5 backends · 6 containers) and Qbittorrent (2 backends
    · 2 containers). All 26 backends present in the DOM.
  - arr_sonarr_backend's card no longer contains a ContainerDiagram
    (the bg-blue-100 / bg-gray-100 chips for sibling containers are gone)
  - vaultwarden_vaultwarden_backend's standalone card still renders its
    single container topology as before.
  - `go build -tags dev`, `go build`, `go vet -tags dev ./...`, and
    `go vet ./...` all pass.

See docs/research/haproxy-dashboard-stack-layout.md for the full
research, layout-option comparison, and recommendation that this commit
implements (Option 1: stack-as-section + compact backend cards).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat: enhance StackSection rendering for multi-backend stacks and add stackBucketHeader and stackTopologyChip templates

* feat: enhance GetUserPermissions to prefer user from context for improved auth handling

* feat: refactor StackGroup and StackSection to consolidate standalone and hardware backends into a flat bucket

* chore(#79): drop dead singleContainerDiagram; document final layout

singleContainerDiagram was reachable only when BackendCard called
ContainerDiagram with len(containers) == 1, but the per-card diagram
is now only drawn for multi-container topology (len > 1) — the singleton
case renders the IP inline in the card header instead. The len == 1
branch inside ContainerDiagram became unreachable, and the helper that
backed it was dead. Removed both; ContainerDiagram now collapses to
"VPN gateway or simple multi-container," which matches its actual scope.

Also extended docs/research/haproxy-dashboard-stack-layout.md with a
"What shipped" section so the doc isn't stuck at "no code changes yet" —
captures the refinements that landed after the initial Option 1 design
(headerless flat bucket, inStackSection title flag, cursor-help removal,
ACTIVE pill suppression, tooltip anchor flip, baseline alignment).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sarg3nt

docs/research/README.md

@@ -16,6 +16,13 @@ This directory contains active design documents and architectural research for t
   - Comparison of architectural approaches
   - Implementation recommendations and trade-offs
 
+### Gear UX
+
+- **[haproxy-dashboard-stack-layout.md](haproxy-dashboard-stack-layout.md)**
+  - Redesign proposal for the HAProxy dashboard's stack-with-multiple-containers layout ([#79](https://github.com/sarg3nt/gearbox/issues/79))
+  - Best-practice survey (Portainer, Lens, ArgoCD, Datadog, HAProxy stats, Grafana, NN/g)
+  - Three layout options with ASCII mockups, recommendation, and implementation outline
+
 ## Purpose
 
 These documents serve as:

docs/research/haproxy-dashboard-stack-layout.md

@@ -638,7 +638,16 @@ func (m *Manager) GetDB() *database.DB {
 }
 
 // GetUserPermissions retrieves permissions for the current user.
+//
+// Prefers the user placed in the request context by RequireAuth (which is
+// also where the dev-loopback bypass injects its synthetic user). Falls back
+// to the session-cookie lookup so callers that build a request without the
+// auth middleware in front of them — e.g. SSE setup, tests — still resolve.
 func (m *Manager) GetUserPermissions(r *http.Request) (*models.UserPermissions, error) {
+	if user, ok := GetUserFromContext(r.Context()); ok && user != nil {
+		return m.db.GetUserPermissions(user.ID)
+	}
+
 	user, err := m.GetUser(r)
 	if err != nil {
 		return nil, err

docs/research/images/haproxy-dashboard-current.png

@@ -5,18 +5,19 @@ import (
 	"strings"
 )
 
-// ContainerDiagram displays all containers in a backend with their relationships
+// ContainerDiagram renders a multi-container backend's topology — a stack
+// of boxes, blue for the container HAProxy routes to and grey for siblings
+// that share its network or support it. Intended only for backends with
+// real topology to show (VPN gateway or multi-container service); single-
+// container backends render their IP inline in the card header instead
+// and do not call this component. See BackendCard's `len(containers) > 1`
+// guard.
 templ ContainerDiagram(containers []models.Container, serverAddress string) {
 	if len(containers) > 0 {
 		<div class="mt-3">
 			if hasVPNGatewayPattern(containers) {
-				<!-- VPN Gateway Pattern: Stacked visualization -->
 				@vpnGatewayDiagram(containers, serverAddress)
-			} else if len(containers) == 1 {
-				<!-- Single Container: Taller box with IP on second line -->
-				@singleContainerDiagram(containers[0], serverAddress)
 			} else {
-				<!-- Multi Container Pattern: Stacked visualization -->
 				@simpleContainerDiagram(containers, serverAddress)
 			}
 		</div>
@@ -57,20 +58,6 @@ func getNestedContainers(containers []models.Container) []models.Container {
 	return nested
 }
 
-// singleContainerDiagram renders a single container with IP on second line
-templ singleContainerDiagram(container models.Container, serverAddress string) {
-	<div class="px-4 py-3 bg-blue-100 dark:bg-blue-900 border-2 border-blue-500 rounded-lg">
-		<div class="text-sm font-semibold text-blue-900 dark:text-blue-100">
-			{ container.Name }
-		</div>
-		if serverAddress != "" {
-			<div class="text-xs text-blue-700 dark:text-blue-300 font-mono mt-1">
-				{ serverAddress }
-			</div>
-		}
-	</div>
-}
-
 // vpnGatewayDiagram renders the VPN gateway pattern as stacked rows
 templ vpnGatewayDiagram(containers []models.Container, serverAddress string) {
 	if gateway := getGatewayContainer(containers); gateway != nil {

gearbox/internal/framework/auth/auth.go

@@ -350,6 +350,140 @@ func GetServiceURL(backendName string, metadata *models.Metadata) string {
 	return "https://" + backendMeta.Hostname
 }
 
+// StackGroup is a group of HAProxy backends that share a single
+// docker-compose stack (a "stack" being the leading underscore-separated
+// segment of the backend name, e.g. `arr` in `arr_sonarr_backend`).
+//
+// Existed to fix #79: previously every backend card re-rendered the full
+// stack topology with one container highlighted, so a 5-backend Arr stack
+// drew 5 copies of the same 6-container diagram. With StackGroup the
+// topology is hoisted to the stack level and rendered once; each backend
+// card inside the stack is compact (no per-card diagram).
+//
+// Singleton stacks (one backend per group) and hardware backends are
+// collected into a trailing flat bucket (IsFlat=true) so the UI doesn't
+// grow section chrome for trivial cases — those still render as flat
+// cards. Their type (container vs hardware) is conveyed by the per-card
+// CT / HW badge, so a section label would only repeat that information.
+type StackGroup struct {
+	StackName   string             // the parsed group key, e.g. "arr" — empty for the synthetic flat bucket
+	DisplayName string             // capitalized label used in the section header
+	IsFlat      bool               // synthetic bucket for singleton + hardware backends; rendered headerless
+	Backends    []models.Backend   // backends in this stack, sorted alphabetically
+	Topology    []models.Container // merged container list — IsBackend OR'd across members
+}
+
+// GroupBackendsByStack groups backends within a frontend by their parsed
+// `BackendGroupInfo.Group` (the docker-compose project prefix). Multi-
+// backend non-hardware groups become their own StackGroup with a merged
+// container topology; singleton non-hardware groups and all hardware
+// backends fold into a single trailing flat bucket (IsFlat=true). The
+// returned slice is ordered: real stacks alphabetically, then the flat
+// bucket — so the visually heavy multi-container stacks lead and the
+// cheap rows trail. Within the flat bucket, singletons come before
+// hardware so the container-y stuff stays grouped.
+//
+// metadata may be nil; in that case Topology is empty for every group.
+func GroupBackendsByStack(backends []models.Backend, metadata *models.Metadata) []StackGroup {
+	type bucket struct {
+		stackName  string
+		backends   []models.Backend
+		containers []models.Container
+		isBackend  map[string]bool // container name -> true if it serves at least one backend in this group
+	}
+
+	byKey := map[string]*bucket{}
+	keyOrder := []string{}
+
+	for _, b := range backends {
+		info := ParseBackendName(b.Name)
+		key := info.Group
+		if key == "" {
+			key = "__none__"
+		}
+		bk, ok := byKey[key]
+		if !ok {
+			bk = &bucket{stackName: info.Group, isBackend: map[string]bool{}}
+			byKey[key] = bk
+			keyOrder = append(keyOrder, key)
+		}
+		bk.backends = append(bk.backends, b)
+		if metadata == nil {
+			continue
+		}
+		bm := metadata.GetMetadataForBackend(b.Name)
+		if bm == nil {
+			continue
+		}
+		for _, c := range bm.Containers {
+			if c.IsBackend {
+				bk.isBackend[c.Name] = true
+			}
+			// dedupe by name, preserve first-seen order
+			already := false
+			for _, existing := range bk.containers {
+				if existing.Name == c.Name {
+					already = true
+					break
+				}
+			}
+			if !already {
+				bk.containers = append(bk.containers, c)
+			}
+		}
+	}
+
+	// Apply the OR-merged IsBackend flag back onto the topology list and
+	// sort each bucket's backends for stable display.
+	for _, bk := range byKey {
+		for i := range bk.containers {
+			bk.containers[i].IsBackend = bk.isBackend[bk.containers[i].Name]
+		}
+		sort.Slice(bk.backends, func(i, j int) bool { return bk.backends[i].Name < bk.backends[j].Name })
+	}
+
+	// Partition into real multi-backend stacks vs the trailing flat
+	// bucket. Real stacks are alphabetized. The flat bucket collects
+	// singletons first (in keyOrder), then hardware (also keyOrder) —
+	// hardware trails so a visual scan from top to bottom moves from
+	// container-y stuff to the on-iron services.
+	var (
+		realStacks    []StackGroup
+		flatBackends  []models.Backend
+		hardwareLast  []models.Backend
+	)
+
+	for _, key := range keyOrder {
+		bk := byKey[key]
+		if key == "hardware" {
+			hardwareLast = append(hardwareLast, bk.backends...)
+			continue
+		}
+		if len(bk.backends) <= 1 {
+			flatBackends = append(flatBackends, bk.backends...)
+			continue
+		}
+		display := bk.stackName
+		if display != "" {
+			display = strings.ToUpper(display[:1]) + display[1:]
+		}
+		realStacks = append(realStacks, StackGroup{
+			StackName:   bk.stackName,
+			DisplayName: display,
+			Backends:    bk.backends,
+			Topology:    bk.containers,
+		})
+	}
+	sort.Slice(realStacks, func(i, j int) bool { return realStacks[i].StackName < realStacks[j].StackName })
+
+	flatBackends = append(flatBackends, hardwareLast...)
+
+	result := realStacks
+	if len(flatBackends) > 0 {
+		result = append(result, StackGroup{IsFlat: true, Backends: flatBackends})
+	}
+	return result
+}
 
 // StatusSummary holds summary statistics for status doughnuts
 type StatusSummary struct {