Dash/Plan.md

Homelab Dashboard Project Plan

Summary

Create project.md as full build spec for self-hosted homelab dashboard: Next.js React frontend, shadcn/ui, Go Gin backend, PostgreSQL via Docker Compose. Core v1: service cards, groups, drag/drop ordering, multi-URL launch picker, no auth, dark-first Vercel/Nothing-inspired UI, extensible widget framework with one real Pi-hole widget.

Key Changes

• Scaffold monorepo:
  • /frontend: Next.js App Router, React, TypeScript strict, Tailwind, shadcn/ui.
  • /backend: Go + Gin API, zap logging, OpenAPI contract.
  • /db: PostgreSQL migrations with goose, typed queries with sqlc.
  • /deploy: Docker Compose for frontend, backend, Postgres.
• API source of truth: OpenAPI spec generates frontend TypeScript client/types.
• No authentication in v1; assume trusted LAN/self-hosted deployment.
• Persist:
  • services
  • service URLs marked local / external / custom label
  • icon URL or uploaded icon file reference
  • groups
  • group collapsed state
  • drag/drop ordering
  • dashboard widget instances/settings
• UI:
  • Dark-first, light mode also supported.
  • Vercel base: Geist Sans, Geist Mono, white/black neutrals, shadow-as-border, 6-8px radius.
  • Nothing accent: OLED dark mode, mono uppercase labels, red signal accent, sparse dot-grid detail.
  • Fonts loaded through next/font/google: Geist, Geist_Mono; optional Doto only for clock/hero widget if used.
• shadcn components:
  • Button, Card, Dialog, Sheet, Input, Select, Switch, Tabs, Badge, DropdownMenu, Tooltip, Collapsible, Alert, Empty, Separator, ScrollArea.
  • Drag/drop via @dnd-kit.
  • Forms use shadcn FieldGroup / Field patterns.

Product Behavior

• Dashboard opens to time/date/timezone strip, widget row, grouped service grid.
• + action opens add-service dialog:
  • name
  • icon URL or uploaded icon
  • one or more URLs
  • URL label/type: local, external, custom
  • optional group
• Clicking service:
  • one URL: open directly
  • multiple URLs: show picker dialog, then open chosen URL
• Groups:
  • create, rename, delete empty group
  • collapse/expand
  • drag groups
  • drag services within and across groups
• Widgets:
  • v1 includes widget framework plus Pi-hole adapter.
  • Pi-hole widget stores base URL/API token locally in backend DB.
  • Widget failures render inline [ERROR: ...], no toast spam.
  • Future adapters: AdGuard, Immich, custom image/status widgets.

Test Plan

• Backend:
  • Go unit tests for service/group ordering, URL validation, widget config validation.
  • API integration tests against test Postgres.
  • Migration up/down check with goose.
• Frontend:
  • Component tests for service form, URL picker, group collapse.
  • Playwright flow: add service, add multiple URLs, choose URL, reorder cards, collapse group, toggle theme.
  • Accessibility check: keyboard focus, dialog titles, labels, contrast.
• Build:
  • docker compose up starts full stack.
  • OpenAPI generation succeeds.
  • Frontend typecheck and backend tests pass.

Assumptions

• Use Next.js React, not SolidJS, because user wants to try Next.js and remain React-focused.
• Use PostgreSQL Docker, not SQLite, per chosen TDvorak default.
• Start visual design dark-first; light mode remains first-class.
• v1 ships no auth and is intended for trusted self-hosted network.
• project.md will be written with this plan when execution/mutation is allowed.