homelab-optimized/docs/superpowers/specs/2026-04-04-homelab-dashboard-design.md

Homelab Dashboard — Design Spec

Context

The homelab has 73 MCP tools, 11 automation scripts, and data scattered across 15+ services. There's no unified view — you switch between Homarr, Grafana, Portainer, and terminal logs. This dashboard consolidates everything into a single production-grade UI.

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌──────────────────────┐
│  Next.js UI      │────▶│  FastAPI Backend  │────▶│  Services            │
│  (dashboard-ui)  │     │  (dashboard-api)  │     │                      │
│  Port 3000       │     │  Port 8888        │     │  Portainer (5 hosts) │
│                  │     │                   │     │  Jellyfin (olares)   │
│  - shadcn/ui     │     │  - scripts/lib/*  │     │  Ollama (olares)     │
│  - Tailwind CSS  │     │  - SQLite readers │     │  Prometheus          │
│  - SWR polling   │     │  - SSE stream     │     │  Gitea               │
│  - dark theme    │     │  - /api/* routes  │     │  Headscale           │
│                  │     │                   │     │  SQLite DBs (6)      │
└─────────────────┘     └──────────────────┘     │  expenses.csv        │
                                                   └──────────────────────┘

Docker Compose runs both containers. Mounts scripts/ read-only for the Python backend to access lib/ modules and SQLite DBs.

Tech Stack

Layer	Technology	Why
Frontend	Next.js 15 + React 19	Best component ecosystem
UI Components	shadcn/ui + Tailwind CSS	Production-grade, dark mode built-in
Data Fetching	SWR (stale-while-revalidate)	Auto-polling with caching
Real-time	EventSource (SSE)	Activity feed + alerts
Backend	FastAPI (Python 3.12)	Reuses existing scripts/lib/ modules
Database	SQLite (read-only) + CSV	Existing automation data, no new DB
Deployment	Docker Compose (2 containers)	dashboard-ui + dashboard-api

Tabs & Content

1. Dashboard (Overview)

Quick Stats Row (5 cards, polled every 60s):

• Total containers (sum across all Portainer endpoints) + health status
• Hosts online (Portainer endpoint health checks)
• GPU status (nvidia-smi via SSH to olares: temp, utilization, VRAM)
• Emails classified today (query processed.db WHERE date = today)
• Active alerts (count of unhealthy containers from stack-restart.db)

Activity Feed (SSE, real-time):

• Reads from a combined event log the API builds from:
  • /tmp/stack-restart.log (container health events)
  • /tmp/backup-validator.log (backup results)
  • /tmp/gmail-organizer-dvish.log + others (email classifications)
  • /tmp/receipt-tracker.log (expense extractions)
  • /tmp/config-drift.log (drift detections)
• Shows most recent 20 events with color-coded dots by type
• New events push via SSE

Jellyfin Card (polled every 30s):

• Now playing (active sessions via Jellyfin API)
• Library item counts (movies, TV, anime, music)

Ollama Card (polled every 60s):

• Model status (loaded/unloaded, model name)
• VRAM usage
• Daily call count (parsed from automation logs)

Hosts Grid (polled every 60s):

• 5 Portainer endpoints with container counts
• Status indicator (green/red)
• Click to navigate to Infrastructure tab filtered by host

2. Infrastructure

Container Table (polled every 30s):

• All containers across all Portainer endpoints
• Columns: Name, Host, Status, Image, Uptime
• Filter by endpoint, search by name
• Click to view logs (modal with last 100 lines)
• Restart button per container

Olares Pods (polled every 30s):

• K3s pod list from kubectl get pods -A
• GPU processes from nvidia-smi
• Restart deployment button

Headscale Nodes (polled every 120s):

• Node list with online/offline status
• Last seen timestamp
• IP addresses

3. Media

Jellyfin Now Playing (polled every 15s):

• Active streams with user, device, title, transcode status
• Bandwidth indicator

Download Queues (polled every 30s):

• Sonarr queue (upcoming episodes, download status)
• Radarr queue (upcoming movies, download status)
• SABnzbd queue (active downloads, speed, ETA)

Library Stats (polled every 300s):

• Jellyfin library counts
• Recent additions (if API supports it)

4. Automations

Email Organizer Status (polled every 120s):

• Per-account stats: lzbellina92, dvish92, admin@thevish.io
• Today's classifications by category (bar chart)
• Sender cache hit rate
• Last run time + errors

Stack Restart History (polled every 60s):

• Table from stack-restart.db: container, endpoint, duration, action taken, LLM analysis
• Last 7 days

Backup Status (polled every 300s):

• Parse latest /tmp/gmail-backup-daily.log
• OK/FAIL indicator with last run time
• Email count backed up

Config Drift (polled every 300s):

• Table of detected drifts (if any)
• Last scan time

Disk Predictions (polled every 3600s):

• Table from latest disk-predictor run
• Volumes approaching 90% highlighted

5. Expenses

Expense Table (polled every 300s):

• Read from data/expenses.csv
• Columns: Date, Vendor, Amount, Currency, Order#, Account
• Sortable, filterable
• Running total for current month

Monthly Summary (polled every 300s):

• Total spend this month
• Spend by vendor (top 10)
• Spend by category (if derivable from vendor)

Subscription Audit (static, monthly):

• Latest audit results from subscription-auditor
• Active, dormant, marketing sender counts

FastAPI Backend Endpoints

GET  /api/health                    → backend health check

# Dashboard
GET  /api/stats/overview            → container count, host health, GPU, email count, alerts
GET  /api/activity                  → SSE stream of recent events
GET  /api/jellyfin/status           → now playing + library counts
GET  /api/ollama/status             → model, VRAM, call count

# Infrastructure
GET  /api/containers                → all containers across endpoints (?endpoint=atlantis)
GET  /api/containers/{id}/logs      → container logs (?endpoint=atlantis&tail=100)
POST /api/containers/{id}/restart   → restart container
GET  /api/olares/pods               → k3s pod list (?namespace=)
GET  /api/olares/gpu                → nvidia-smi output
GET  /api/headscale/nodes           → headscale node list

# Media
GET  /api/jellyfin/sessions         → active playback sessions
GET  /api/sonarr/queue              → download queue
GET  /api/radarr/queue              → download queue
GET  /api/sabnzbd/queue             → active downloads

# Automations
GET  /api/automations/email         → organizer stats from processed.db files
GET  /api/automations/restarts      → stack-restart history from DB
GET  /api/automations/backup        → backup log parse
GET  /api/automations/drift         → config drift status
GET  /api/automations/disk          → disk predictions

# Expenses
GET  /api/expenses                  → expenses.csv data (?month=2026-04)
GET  /api/expenses/summary          → monthly totals, top vendors
GET  /api/subscriptions             → latest subscription audit

SSE Activity Stream

The /api/activity endpoint uses Server-Sent Events:

@app.get("/api/activity")
async def activity_stream():
    async def event_generator():
        # Tail all automation log files
        # Parse new lines into structured events
        # Yield as SSE: data: {"type": "email", "message": "...", "time": "..."}
    return StreamingResponse(event_generator(), media_type="text/event-stream")

Event types: container_health, backup, email_classified, receipt_extracted, config_drift, stack_restart, pr_review.

Docker Compose

# dashboard/docker-compose.yml
services:
  dashboard-api:
    build: ./api
    ports:
      - "8888:8888"
    volumes:
      - ../../scripts:/app/scripts:ro        # access lib/ and SQLite DBs
      - ../../data:/app/data:ro              # expenses.csv
      - /tmp:/app/logs:ro                    # automation log files
    environment:
      - PORTAINER_URL=http://100.83.230.112:10000
      - PORTAINER_TOKEN=${PORTAINER_TOKEN}
      - OLLAMA_URL=http://192.168.0.145:31434
    restart: unless-stopped

  dashboard-ui:
    build: ./ui
    ports:
      - "3000:3000"
    environment:
      - API_URL=http://dashboard-api:8888
    depends_on:
      - dashboard-api
    restart: unless-stopped

File Structure

dashboard/
  docker-compose.yml
  api/
    Dockerfile
    requirements.txt        # fastapi, uvicorn, httpx
    main.py                 # FastAPI app
    routers/
      overview.py           # /api/stats, /api/activity
      containers.py         # /api/containers/*
      media.py              # /api/jellyfin/*, /api/sonarr/*, etc.
      automations.py        # /api/automations/*
      expenses.py           # /api/expenses/*
      olares.py             # /api/olares/*
  ui/
    Dockerfile
    package.json
    next.config.js
    tailwind.config.ts
    app/
      layout.tsx            # root layout with top nav
      page.tsx              # Dashboard tab (default)
      infrastructure/
        page.tsx
      media/
        page.tsx
      automations/
        page.tsx
      expenses/
        page.tsx
    components/
      nav.tsx               # top navigation bar
      stat-card.tsx         # quick stats cards
      activity-feed.tsx     # SSE-powered activity feed
      container-table.tsx   # sortable container list
      host-card.tsx         # host status card
      expense-table.tsx     # expense data table
      jellyfin-card.tsx     # now playing + library stats
      ollama-card.tsx       # LLM status card
    lib/
      api.ts                # fetch wrapper for backend API
      use-sse.ts            # SSE hook for activity feed

Polling Intervals

Data	Interval	Rationale
Container status	30s	Detect issues quickly
Jellyfin sessions	15s	Now playing should feel live
GPU / Ollama	60s	Changes slowly
Email stats	120s	Organizer runs every 30min
Activity feed	SSE (real-time)	Should feel instant
Expenses	300s	Changes once/day at most
Headscale nodes	120s	Rarely changes
Disk predictions	3600s	Weekly report, hourly check is plenty

Design Tokens (Dark Theme)

Based on the approved mockup:

Background:     #0a0a1a (page), #0f172a (cards), #1e293b (borders)
Text:           #f1f5f9 (primary), #94a3b8 (secondary), #475569 (muted)
Accent:         #3b82f6 (blue, primary action)
Success:        #22c55e (green, healthy)
Warning:        #f59e0b (amber)
Error:          #ef4444 (red)
Purple:         #8b5cf6 (Ollama/AI indicators)

These map directly to Tailwind's slate/blue/green/amber/red/violet palette, so shadcn/ui theming is straightforward.

Verification

1. docker compose up should start both containers
2. http://localhost:3000 loads the dashboard
3. All 5 tabs render REDACTED_APP_PASSWORD the homelab
4. Activity feed updates in real-time when an automation runs
5. Container restart button works
6. Expenses table shows data from expenses.csv
7. Mobile-responsive (test at 375px width)