935 lines
32 KiB
Markdown
935 lines
32 KiB
Markdown
# Home Lab Dashboard - Product Requirements Document (PRD)
|
|
|
|
## Executive Summary
|
|
|
|
The Home Lab Dashboard is a Vue 3-based Single Page Application (SPA) designed to provide comprehensive introspection and monitoring of a home lab infrastructure at a glance. The dashboard serves as a central command center for observing system health, service status, resource utilization, and operational metrics across the entire home lab ecosystem.
|
|
|
|
**Core Value Proposition**: Deliver instant visibility into home lab operations through a clean, modern interface that transforms complex infrastructure data into actionable insights.
|
|
|
|
## Product Vision
|
|
|
|
**Vision Statement**: "A unified dashboard that transforms home lab complexity into clarity, enabling operators to understand, monitor, and manage their infrastructure through elegant data visualization and real-time insights."
|
|
|
|
**Mission**: Provide home lab operators with immediate situational awareness of their infrastructure through intuitive data presentation, reducing time-to-insight from minutes to seconds.
|
|
|
|
## Table of Contents
|
|
|
|
1. [Product Overview](#product-overview)
|
|
2. [User Personas & Use Cases](#user-personas--use-cases)
|
|
3. [Functional Requirements](#functional-requirements)
|
|
4. [Technical Architecture](#technical-architecture)
|
|
5. [User Interface Design](#user-interface-design)
|
|
6. [Data Requirements](#data-requirements)
|
|
7. [Performance Requirements](#performance-requirements)
|
|
8. [Security Requirements](#security-requirements)
|
|
9. [Implementation Roadmap](#implementation-roadmap)
|
|
|
|
## Product Overview
|
|
|
|
### Problem Statement
|
|
|
|
Home lab operators face several challenges:
|
|
|
|
- **Information Scatter**: Critical metrics are spread across multiple tools and interfaces - solution: use netdata already part of the project not implemented
|
|
- **Context Switching**: Constant jumping between different monitoring solutions
|
|
- **Alert Fatigue**: Too many notifications without proper context or prioritization
|
|
- **Lack of Holistic View**: Difficulty understanding system interdependencies
|
|
- **Response Delay**: Slow access to critical information during incidents
|
|
|
|
### Solution Overview
|
|
|
|
The Home Lab Dashboard addresses these challenges by providing:
|
|
|
|
- **Unified Data Presentation**: All critical metrics in a single interface
|
|
- **Real-time Monitoring**: Live updates without manual refresh
|
|
- **Contextual Information**: Related data grouped logically
|
|
- **Priority-based Alerts**: Intelligent notification system
|
|
- **Quick Action Access**: Direct links to detailed tools when needed
|
|
|
|
### Key Success Metrics
|
|
|
|
- **Time to Information**: < 3 seconds to load critical system status
|
|
- **User Engagement**: 95% of daily monitoring tasks completed within dashboard
|
|
- **Alert Accuracy**: < 5% false positive rate for critical alerts
|
|
- **Performance**: Dashboard loads in < 2 seconds on typical home network
|
|
- **Uptime**: 99.9% availability during normal operations
|
|
|
|
## User Personas & Use Cases
|
|
|
|
### Primary Persona: The Home Lab Operator
|
|
|
|
**Profile**:
|
|
|
|
- Technical background with system administration experience
|
|
- Manages 5-20 services across 2-5 physical machines
|
|
- Values efficiency and quick problem resolution
|
|
- Prefers clean, information-dense interfaces
|
|
- Uses dashboard multiple times daily for routine checks
|
|
|
|
**Primary Use Cases**:
|
|
|
|
#### UC-1: Daily Health Check
|
|
|
|
**Goal**: Quickly assess overall system health
|
|
**Frequency**: 2-3 times daily
|
|
**Scenario**: Operator opens dashboard to verify all services are running normally
|
|
**Success Criteria**: Complete system status visible within 3 seconds
|
|
|
|
#### UC-2: Incident Response
|
|
|
|
**Goal**: Rapidly identify and assess system issues
|
|
**Frequency**: Ad-hoc (when alerts trigger)
|
|
**Scenario**: Operator receives alert and needs immediate context
|
|
**Success Criteria**: Problem source and impact clearly identified within 10 seconds
|
|
|
|
#### UC-3: Capacity Planning
|
|
|
|
**Goal**: Monitor resource utilization trends
|
|
**Frequency**: Weekly
|
|
**Scenario**: Operator reviews resource usage to plan upgrades
|
|
**Success Criteria**: Historical and current resource data easily accessible
|
|
|
|
#### UC-4: Service Management
|
|
|
|
**Goal**: Monitor specific service health and performance
|
|
**Frequency**: Daily
|
|
**Scenario**: Operator checks critical services (NAS, reverse proxy, etc.)
|
|
**Success Criteria**: Service-specific metrics clearly presented
|
|
|
|
## Functional Requirements
|
|
|
|
### F-1: Authentication & Access Control
|
|
|
|
#### F-1.1: User Authentication
|
|
|
|
- **Requirement**: Secure login system with session management
|
|
- **Implementation**: Simple username/password authentication
|
|
- **Validation**: Session timeout after 24 hours of inactivity
|
|
- **Security**: Password hashing, CSRF protection, secure cookies
|
|
|
|
#### F-1.2: Single Session Management
|
|
|
|
- **Requirement**: Prevent multiple concurrent sessions
|
|
- **Implementation**: Token-based session invalidation
|
|
- **Behavior**: New login invalidates previous sessions
|
|
|
|
### F-2: Dashboard Layout & Navigation
|
|
|
|
#### F-2.1: Two-Page Architecture
|
|
|
|
- **Page 1**: Login page with centered login component
|
|
- **Page 2**: Dashboard page with header, aside, and main sections
|
|
- **Navigation**: SPA routing between pages
|
|
- **State**: Preserve application state during navigation
|
|
|
|
#### F-2.2: Responsive Layout Structure
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ Header │
|
|
├─────────┬───────────────────────────┤
|
|
│ │ │
|
|
│ Aside │ Main │
|
|
│ │ Content │
|
|
│ (Menu) │ (Widgets) │
|
|
│ │ │
|
|
└─────────┴───────────────────────────┘
|
|
```
|
|
|
|
### F-3: Core Dashboard Components
|
|
|
|
#### F-3.1: System Overview Widget
|
|
|
|
- **Purpose**: High-level system health status
|
|
- **Metrics**: Overall health score, critical alerts count, services running
|
|
- **Visual**: Status indicators (green/yellow/red) with summary numbers
|
|
- **Update Frequency**: Real-time (< 30 seconds)
|
|
|
|
#### F-3.2: Infrastructure Status Widget
|
|
|
|
- **Purpose**: Physical host and VM status
|
|
- **Metrics**: CPU, RAM, disk usage per host
|
|
- **Visual**: Progress bars or gauges with percentage values
|
|
- **Drill-down**: Click to view detailed host information
|
|
|
|
#### F-3.3: Service Health Matrix
|
|
|
|
- **Purpose**: Status of all monitored services
|
|
- **Display**: Grid layout with service names and status indicators
|
|
- **Information**: Service name, status, uptime, last check time
|
|
- **Interaction**: Click service for detailed metrics
|
|
|
|
#### F-3.4: Network Status Widget
|
|
|
|
- **Purpose**: Network connectivity and performance
|
|
- **Metrics**: Internet connectivity, internal network status, bandwidth usage
|
|
- **Visual**: Connection status icons with performance indicators
|
|
- **Alerts**: Network outage or degraded performance warnings
|
|
|
|
#### F-3.5: Storage Overview Widget
|
|
|
|
- **Purpose**: Storage capacity and health across all systems
|
|
- **Metrics**: Used/available space, RAID status, backup status
|
|
- **Visual**: Capacity bars with health indicators
|
|
- **Critical Alerts**: Storage approaching capacity (>80% full)
|
|
|
|
#### F-3.6: Recent Events Feed
|
|
|
|
- **Purpose**: Chronological list of system events
|
|
- **Content**: Service starts/stops, alerts, configuration changes
|
|
- **Display**: Time-ordered list with event type icons
|
|
- **Retention**: Last 50 events or 24 hours, whichever is more
|
|
|
|
#### F-3.7: Quick Actions Panel
|
|
|
|
- **Purpose**: Common administrative tasks
|
|
- **Actions**: Restart services, view logs, access admin interfaces
|
|
- **Implementation**: Direct links or API calls where possible
|
|
- **Security**: Role-based action availability
|
|
|
|
### F-4: Data Management & State
|
|
|
|
#### F-4.1: Centralized Store Architecture
|
|
|
|
- **Implementation**: Pinia store as single source of truth
|
|
- **Pattern**: All components receive data via props
|
|
- **Communication**: Components emit events to store
|
|
- **State Management**: Store handles all business logic and API calls
|
|
|
|
#### F-4.2: Real-time Data Updates
|
|
|
|
- **Mechanism**: WebSocket or Server-Sent Events
|
|
- **Frequency**: Configurable (default 30 seconds)
|
|
- **Efficiency**: Only updated data transmitted
|
|
- **Fallback**: Polling mechanism if real-time unavailable
|
|
|
|
#### F-4.3: Data Persistence
|
|
|
|
- **Client-side**: Store critical state in localStorage
|
|
- **Recovery**: Restore state on page reload
|
|
- **Expiration**: Clear stale data after 24 hours
|
|
- **Privacy**: No sensitive data in local storage
|
|
|
|
## Technical Architecture
|
|
|
|
### Technology Stack
|
|
|
|
#### Frontend Framework
|
|
|
|
- **Vue 3.5.13**: Latest stable version with Composition API and `<script setup>` syntax
|
|
- **TypeScript 5.8**: Full type safety throughout application with strict mode
|
|
- **Vite 6.2.4**: Next-generation build tool for fast development and optimized production builds
|
|
- **Pinia 3.0.1**: Official Vue state management library with TypeScript support
|
|
- **Vue Router 4**: Client-side routing for SPA navigation with route guards
|
|
|
|
#### Styling & Design System
|
|
|
|
- **Tailwind CSS v4 (Latest)**: Modern utility-first CSS framework with new engine
|
|
- **@tailwindcss/vite**: Dedicated Vite plugin for optimized integration
|
|
- **CSS-first Configuration**: Using `@theme` directive for design tokens
|
|
- **No Config File**: Streamlined setup without separate `tailwind.config.js`
|
|
- **Built-in Import Support**: Native `@import` handling without PostCSS plugins
|
|
- **Improved Performance**: Faster builds and better dev experience
|
|
- **Component Design System**: Custom component library built on Tailwind utilities
|
|
- **Responsive Design**: Mobile-first approach with desktop optimization
|
|
- **Modern Color System**: Using oklch() color space for better color consistency
|
|
|
|
#### Development Tools & Quality
|
|
|
|
- **ESLint 9.22**: Code linting with Vue 3 and TypeScript rules
|
|
- **Prettier 3.5.3**: Consistent code formatting across the project
|
|
- **Vitest 3.1.1**: Fast unit testing framework with Vue Test Utils
|
|
- **Vue DevTools**: Development debugging and inspection
|
|
- **Oxlint 0.16**: Fast linting for additional code quality checks
|
|
- **TypeScript Strict Mode**: Comprehensive type checking and safety
|
|
|
|
### Application Architecture
|
|
|
|
#### Implemented Component Hierarchy
|
|
|
|
```plaintext
|
|
App.vue (Router outlet with auth initialization)
|
|
├── LoginView.vue (Route: /)
|
|
│ └── LoginForm.vue (Reactive form with validation)
|
|
└── DashboardView.vue (Route: /dashboard)
|
|
└── DashboardLayout.vue
|
|
├── DashboardHeader.vue (User info, logout, refresh)
|
|
├── DashboardSidebar.vue (Navigation, quick links)
|
|
└── Main Content Area
|
|
├── SystemCard.vue (System info overview)
|
|
├── ServiceStatusCard.vue (Service health summary)
|
|
├── UptimeCard.vue (System uptime display)
|
|
├── LoadAverageCard.vue (CPU load metrics)
|
|
├── ServicesTable.vue (Detailed service status)
|
|
├── QuickActions.vue (Action buttons grid)
|
|
├── ErrorAlert.vue (Error message display)
|
|
└── LoadingSpinner.vue (Loading indicator)
|
|
```
|
|
|
|
#### Store Architecture (Pinia)
|
|
|
|
```typescript
|
|
// Implemented Store Modules
|
|
├── authStore.ts // Authentication state, login/logout actions
|
|
│ ├── State: user, isAuthenticated, isLoading, error
|
|
│ ├── Getters: currentUser, isLoggedIn
|
|
│ └── Actions: login(), logout(), initializeAuth()
|
|
│
|
|
├── dashboardStore.ts // System metrics and service status
|
|
│ ├── State: systemInfo, services, isLoading, error, lastUpdated
|
|
│ ├── Getters: runningServices, stoppedServices, errorServices,
|
|
│ │ memoryUsagePercent, diskUsagePercent
|
|
│ └── Actions: fetchSystemInfo(), fetchServices(), refreshData()
|
|
│
|
|
└── Future Modules:
|
|
├── networkStore.ts // Network metrics and connectivity
|
|
├── storageStore.ts // Storage capacity and health
|
|
├── eventsStore.ts // Event feed and notifications
|
|
└── configStore.ts // User preferences and settings
|
|
```
|
|
|
|
#### Component Communication Pattern
|
|
|
|
```plaintext
|
|
┌─────────────┐ Props ┌─────────────┐
|
|
│ Pinia │ ──────────> │ Component │
|
|
│ Store │ │ │
|
|
│ │ <────────── │ │
|
|
└─────────────┘ Emits └─────────────┘
|
|
│
|
|
│ API Calls (Future)
|
|
▼
|
|
┌─────────────┐
|
|
│ Backend │ ← Netdata Integration
|
|
│ APIs │ ← System APIs
|
|
└─────────────┘ ← Service Discovery
|
|
```
|
|
|
|
### Data Flow Architecture
|
|
|
|
#### Current Implementation
|
|
|
|
- **Mock Data**: Demo system info and service status for development
|
|
- **Local Storage**: Authentication state persistence
|
|
- **Reactive State**: Real-time UI updates via Pinia stores
|
|
- **Route Guards**: Authentication-based navigation protection
|
|
|
|
#### Planned API Integration Strategy
|
|
|
|
- **Netdata API**: Primary data source for system metrics (port 19999)
|
|
- **System APIs**: Direct integration with home lab services
|
|
- **WebSocket/SSE**: Real-time updates for dynamic metrics (future)
|
|
- **Service Discovery**: Automatic detection of running services
|
|
- **Caching Strategy**: Browser and application-level caching
|
|
|
|
#### State Management Pattern
|
|
|
|
```typescript
|
|
// Implemented Store Pattern (authStore example)
|
|
export const useAuthStore = defineStore('auth', () => {
|
|
// State (reactive refs)
|
|
const user = ref<User | null>(null)
|
|
const isAuthenticated = ref<boolean>(false)
|
|
const isLoading = ref<boolean>(false)
|
|
const error = ref<string | null>(null)
|
|
|
|
// Getters (computed properties)
|
|
const currentUser = computed(() => user.value)
|
|
const isLoggedIn = computed(() => isAuthenticated.value && user.value !== null)
|
|
|
|
// Actions (methods)
|
|
const login = async (username: string, password: string) => {
|
|
isLoading.value = true
|
|
error.value = null
|
|
|
|
try {
|
|
// Authentication logic with error handling
|
|
const result = await authenticateUser(username, password)
|
|
if (result.success) {
|
|
user.value = result.user
|
|
isAuthenticated.value = true
|
|
localStorage.setItem('isAuthenticated', 'true')
|
|
localStorage.setItem('user', JSON.stringify(user.value))
|
|
}
|
|
return result
|
|
} catch (err) {
|
|
error.value = err.message
|
|
return { success: false, error: error.value }
|
|
} finally {
|
|
isLoading.value = false
|
|
}
|
|
}
|
|
|
|
const logout = () => {
|
|
user.value = null
|
|
isAuthenticated.value = false
|
|
error.value = null
|
|
localStorage.removeItem('isAuthenticated')
|
|
localStorage.removeItem('user')
|
|
}
|
|
|
|
return {
|
|
// Readonly state exposure
|
|
user: readonly(user),
|
|
isAuthenticated: readonly(isAuthenticated),
|
|
isLoading: readonly(isLoading),
|
|
error: readonly(error),
|
|
|
|
// Computed getters
|
|
currentUser,
|
|
isLoggedIn,
|
|
|
|
// Actions
|
|
login,
|
|
logout,
|
|
initializeAuth,
|
|
clearError
|
|
}
|
|
})
|
|
```
|
|
|
|
### Build & Deployment Configuration
|
|
|
|
#### Vite Configuration
|
|
|
|
```typescript
|
|
// vite.config.ts - Optimized for Tailwind CSS v4
|
|
import { defineConfig } from 'vite'
|
|
import vue from '@vitejs/plugin-vue'
|
|
import vueDevTools from 'vite-plugin-vue-devtools'
|
|
import tailwindcss from '@tailwindcss/vite'
|
|
|
|
export default defineConfig({
|
|
plugins: [
|
|
vue(),
|
|
vueDevTools(),
|
|
tailwindcss(), // New Tailwind CSS v4 Vite plugin
|
|
],
|
|
resolve: {
|
|
alias: {
|
|
'@': fileURLToPath(new URL('./src', import.meta.url))
|
|
},
|
|
},
|
|
})
|
|
```
|
|
|
|
#### Tailwind CSS v4 Integration
|
|
|
|
```css
|
|
/* src/assets/main.css - New v4 syntax */
|
|
@import "tailwindcss";
|
|
|
|
#app {
|
|
height: 100vh;
|
|
}
|
|
|
|
/* Future: Custom design tokens with @theme directive */
|
|
/*
|
|
@theme {
|
|
--color-homelab-primary: oklch(0.5 0.2 250);
|
|
--color-homelab-secondary: oklch(0.7 0.15 180);
|
|
--font-display: "Inter", sans-serif;
|
|
}
|
|
*/
|
|
```
|
|
|
|
## User Interface Design
|
|
|
|
### Design Principles
|
|
|
|
#### Clarity Over Complexity
|
|
|
|
- **Information Hierarchy**: Most critical data prominently displayed
|
|
- **Visual Hierarchy**: Size, color, and position indicate importance
|
|
- **Reduced Cognitive Load**: Group related information together
|
|
- **Progressive Disclosure**: Summary first, details on demand
|
|
|
|
#### Consistency & Standards
|
|
|
|
- **Component Library**: Reusable UI components with consistent styling
|
|
- **Color System**: Semantic colors for status indication
|
|
- **Typography**: Clear typography hierarchy
|
|
- **Spacing**: Consistent spacing system using Tailwind utilities
|
|
|
|
#### Performance & Accessibility
|
|
|
|
- **Fast Rendering**: Optimized for quick loading and updates
|
|
- **Keyboard Navigation**: Full keyboard accessibility
|
|
- **Screen Reader Support**: Proper ARIA labels and semantic HTML
|
|
- **Color Contrast**: WCAG 2.1 AA compliance
|
|
|
|
### Page Layouts
|
|
|
|
#### Login Page
|
|
|
|
```vue
|
|
<template>
|
|
<div class="min-h-screen flex items-center justify-center bg-gray-50">
|
|
<div class="max-w-md w-full space-y-8">
|
|
<!-- Logo/Title -->
|
|
<div class="text-center">
|
|
<h2 class="text-3xl font-bold text-gray-900">
|
|
Home Lab Dashboard
|
|
</h2>
|
|
<p class="text-gray-600 mt-2">
|
|
Monitor your infrastructure at a glance
|
|
</p>
|
|
</div>
|
|
|
|
<!-- Login Component -->
|
|
<LoginComponent @login="handleLogin" :loading="isLoading" />
|
|
</div>
|
|
</div>
|
|
</template>
|
|
```
|
|
|
|
#### Dashboard Page
|
|
|
|
```vue
|
|
<template>
|
|
<div class="min-h-screen bg-gray-100">
|
|
<!-- Header -->
|
|
<HeaderComponent
|
|
:user="currentUser"
|
|
@logout="handleLogout"
|
|
@refresh="handleRefresh"
|
|
/>
|
|
|
|
<div class="flex">
|
|
<!-- Sidebar -->
|
|
<AsideComponent
|
|
:active-section="activeSection"
|
|
@section-change="handleSectionChange"
|
|
/>
|
|
|
|
<!-- Main Content -->
|
|
<MainComponent class="flex-1">
|
|
<!-- Widget Grid -->
|
|
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 p-6">
|
|
<!-- System Overview -->
|
|
<SystemOverviewWidget
|
|
:system-health="systemHealth"
|
|
:loading="systemLoading"
|
|
class="col-span-1 md:col-span-2 lg:col-span-1"
|
|
/>
|
|
|
|
<!-- Infrastructure Status -->
|
|
<InfrastructureStatusWidget
|
|
:hosts="infrastructure"
|
|
:loading="infraLoading"
|
|
class="col-span-1 md:col-span-2 lg:col-span-2"
|
|
/>
|
|
|
|
<!-- Service Health Matrix -->
|
|
<ServiceHealthMatrix
|
|
:services="services"
|
|
:loading="servicesLoading"
|
|
@service-click="handleServiceClick"
|
|
class="col-span-1 md:col-span-2 lg:col-span-3"
|
|
/>
|
|
|
|
<!-- Additional widgets... -->
|
|
</div>
|
|
</MainComponent>
|
|
</div>
|
|
</div>
|
|
</template>
|
|
```
|
|
|
|
### Widget Design Specifications
|
|
|
|
#### System Overview Widget
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ 🟢 System Health GOOD │
|
|
├─────────────────────────────────────┤
|
|
│ Services Running 24/25 │
|
|
│ Critical Alerts 0 │
|
|
│ Last Update 2 min ago │
|
|
│ │
|
|
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
|
│ │CPU 45% │ │RAM 67% │ │Net ✓ │ │
|
|
│ └─────────┘ └─────────┘ └─────────┘ │
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
#### Service Health Matrix
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ Service Health Matrix │
|
|
├─────────────────────────────────────┤
|
|
│ 🟢 nginx-proxy ⏱ 25d 14h │
|
|
│ 🟢 homeassistant ⏱ 12d 6h │
|
|
│ 🟡 jellyfin ⏱ 2h 15m │
|
|
│ 🔴 grafana ❌ Down │
|
|
│ 🟢 pihole ⏱ 45d 3h │
|
|
│ 🟢 nextcloud ⏱ 8d 11h │
|
|
│ │
|
|
│ [View All Services] │
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
### Color System
|
|
|
|
#### Status Colors
|
|
|
|
- **Green (#10B981)**: Healthy, operational, success
|
|
- **Yellow (#F59E0B)**: Warning, degraded performance, attention needed
|
|
- **Red (#EF4444)**: Critical, error, down, immediate action required
|
|
- **Blue (#3B82F6)**: Information, in progress, neutral status
|
|
- **Gray (#6B7280)**: Unknown, disabled, inactive
|
|
|
|
#### Interface Colors
|
|
|
|
- **Background**: Gray-50 to Gray-100 gradient
|
|
- **Cards**: White with subtle shadow
|
|
- **Text**: Gray-900 (primary), Gray-600 (secondary)
|
|
- **Borders**: Gray-200 for subtle separation
|
|
- **Accents**: Blue-600 for interactive elements
|
|
|
|
## Data Requirements
|
|
|
|
### Data Sources & APIs
|
|
|
|
#### System Metrics API
|
|
|
|
```typescript
|
|
interface SystemHealth {
|
|
status: 'healthy' | 'degraded' | 'critical'
|
|
uptime: number // seconds
|
|
lastUpdate: Date
|
|
cpu: ResourceUsage
|
|
memory: ResourceUsage
|
|
disk: ResourceUsage
|
|
network: NetworkStatus
|
|
}
|
|
|
|
interface ResourceUsage {
|
|
used: number
|
|
total: number
|
|
percentage: number
|
|
trend: 'increasing' | 'stable' | 'decreasing'
|
|
}
|
|
```
|
|
|
|
#### Service Status API
|
|
|
|
```typescript
|
|
interface ServiceStatus {
|
|
id: string
|
|
name: string
|
|
status: 'running' | 'stopped' | 'error' | 'unknown'
|
|
uptime: number
|
|
lastCheck: Date
|
|
healthCheck: HealthCheck
|
|
metrics: ServiceMetrics
|
|
}
|
|
|
|
interface HealthCheck {
|
|
url?: string
|
|
status: number
|
|
responseTime: number
|
|
message?: string
|
|
}
|
|
```
|
|
|
|
#### Infrastructure Data
|
|
|
|
```typescript
|
|
interface Host {
|
|
id: string
|
|
name: string
|
|
type: 'physical' | 'vm' | 'container'
|
|
status: 'online' | 'offline' | 'maintenance'
|
|
resources: ResourceUsage
|
|
services: string[] // Service IDs running on this host
|
|
lastSeen: Date
|
|
}
|
|
```
|
|
|
|
### Data Update Strategies
|
|
|
|
#### Real-time Updates
|
|
|
|
- **High Frequency (10-30s)**: System health, service status
|
|
- **Medium Frequency (1-5min)**: Resource usage, network status
|
|
- **Low Frequency (5-15min)**: Storage status, event logs
|
|
- **On-demand**: Detailed service information, logs
|
|
|
|
#### Caching Strategy
|
|
|
|
- **Browser Cache**: Static resources (6 hours)
|
|
- **Application Cache**: API responses (30 seconds to 5 minutes)
|
|
- **Local Storage**: User preferences, dashboard layout
|
|
- **Memory Cache**: Frequently accessed computed values
|
|
|
|
### Error Handling & Resilience
|
|
|
|
#### API Error Scenarios
|
|
|
|
- **Network Timeout**: Retry with exponential backoff
|
|
- **Service Unavailable**: Show cached data with staleness indicator
|
|
- **Authentication Failure**: Redirect to login page
|
|
- **Data Corruption**: Validate and sanitize all incoming data
|
|
|
|
#### Graceful Degradation
|
|
|
|
- **Partial Data**: Show available information, indicate missing data
|
|
- **Real-time Failure**: Fall back to polling mechanism
|
|
- **Critical Service Down**: Maintain basic functionality with reduced features
|
|
|
|
## Performance Requirements
|
|
|
|
### Load Time Requirements
|
|
|
|
- **Initial Page Load**: < 2 seconds on typical home network
|
|
- **Dashboard Transition**: < 500ms from login to dashboard
|
|
- **Widget Updates**: < 200ms per widget refresh
|
|
- **API Response Time**: < 1 second for most endpoints
|
|
|
|
### Scalability Considerations
|
|
|
|
- **Concurrent Users**: Support 5-10 simultaneous sessions
|
|
- **Data Volume**: Handle 100+ services and 10+ hosts efficiently
|
|
- **Update Frequency**: Support sub-30-second refresh intervals
|
|
- **Browser Performance**: Maintain 60fps scrolling and interactions
|
|
|
|
### Optimization Strategies
|
|
|
|
- **Code Splitting**: Lazy load non-critical components
|
|
- **Asset Optimization**: Minimize bundle size, compress images
|
|
- **API Efficiency**: Batch requests, implement pagination
|
|
- **Rendering Optimization**: Virtual scrolling for large lists
|
|
|
|
## Security Requirements
|
|
|
|
### Authentication Security
|
|
|
|
- **Password Policy**: Minimum 8 characters, complexity requirements
|
|
- **Session Management**: Secure tokens, automatic timeout
|
|
- **CSRF Protection**: Token-based request validation
|
|
- **XSS Prevention**: Content Security Policy, input sanitization
|
|
|
|
### Network Security
|
|
|
|
- **HTTPS Only**: Force secure connections in production
|
|
- **API Security**: API keys, rate limiting, input validation
|
|
- **CORS Policy**: Restrict cross-origin requests appropriately
|
|
- **Security Headers**: Implement security headers (HSTS, etc.)
|
|
|
|
### Data Protection
|
|
|
|
- **Sensitive Data**: No passwords or API keys in client storage
|
|
- **Local Storage**: Only non-sensitive configuration data
|
|
- **API Communication**: Encrypt all API communications
|
|
- **Error Handling**: No sensitive information in error messages
|
|
|
|
## Implementation Roadmap
|
|
|
|
### ✅ Phase 1: Foundation (COMPLETED - December 2024)
|
|
|
|
**Goal**: Basic application structure and authentication
|
|
|
|
#### ✅ Week 1: Project Setup (COMPLETED)
|
|
|
|
- [x] Initialize Vue 3.5.13 + TypeScript 5.8 + Vite 6.2.4 project
|
|
- [x] Configure Tailwind CSS v4 with @tailwindcss/vite plugin
|
|
- [x] Set up ESLint 9.22, Prettier 3.5.3, and development tools
|
|
- [x] Create optimized project structure and build pipeline
|
|
- [x] Implement routing with Vue Router 4 and authentication guards
|
|
|
|
#### ✅ Week 2: Authentication & Layout (COMPLETED)
|
|
|
|
- [x] Create LoginView.vue with LoginForm.vue component
|
|
- [x] Implement authentication store (authStore.ts) with Pinia 3.0.1
|
|
- [x] Build DashboardLayout.vue with DashboardHeader.vue and DashboardSidebar.vue
|
|
- [x] Add navigation, session management, and localStorage persistence
|
|
- [x] Create complete component templates with TypeScript interfaces
|
|
|
|
**✅ DELIVERED**: Fully functional SPA with authentication, responsive layout, and modern tooling. Live development server running at <http://localhost:5173>
|
|
|
|
### 🚧 Phase 2: Core Widgets (IN PROGRESS - January 2025)
|
|
|
|
**Goal**: Essential dashboard functionality
|
|
|
|
#### ✅ Week 3: System & Infrastructure Widgets (COMPLETED)
|
|
|
|
- [x] Implement SystemCard.vue for system information display
|
|
- [x] Create ServiceStatusCard.vue for service health summary
|
|
- [x] Build ServicesTable.vue component for detailed service status
|
|
- [x] Add UptimeCard.vue and LoadAverageCard.vue for system metrics
|
|
- [x] Create dashboardStore.ts with mock data and reactive state management
|
|
- [x] Implement real-time UI updates via Pinia stores
|
|
|
|
#### 🚧 Week 4: Additional Widgets & Polish (IN PROGRESS)
|
|
|
|
- [x] Create QuickActions.vue component grid
|
|
- [x] Implement ErrorAlert.vue and LoadingSpinner.vue
|
|
- [x] Add comprehensive error handling and loading states
|
|
- [x] Build responsive design with Tailwind CSS v4 utilities
|
|
- [ ] **NEXT**: Integrate with Netdata API (localhost:19999)
|
|
- [ ] **NEXT**: Add real service discovery and health checks
|
|
- [ ] **NEXT**: Implement WebSocket/SSE for real-time updates
|
|
|
|
**🎯 CURRENT STATUS**: Basic UI complete with mock data. Ready for backend integration.
|
|
|
|
### 📋 Phase 3: Data Integration (Weeks 5-6)
|
|
|
|
**Goal**: Real data sources and live monitoring
|
|
|
|
#### Week 5: Netdata Integration
|
|
|
|
- [ ] Connect to existing Netdata instance (port 19999)
|
|
- [ ] Implement system metrics API calls
|
|
- [ ] Add real-time performance data
|
|
- [ ] Create data transformation layer
|
|
- [ ] Implement caching strategy
|
|
|
|
#### Week 6: Service Discovery & Management
|
|
|
|
- [ ] Build service discovery mechanism
|
|
- [ ] Integrate with system services (SSH, NFS, etc.)
|
|
- [ ] Add Ollama monitoring integration
|
|
- [ ] Implement service health endpoints
|
|
- [ ] Create service management actions
|
|
|
|
### 📊 Phase 4: Advanced Features (Weeks 7-8)
|
|
|
|
**Goal**: Enhanced monitoring and management capabilities
|
|
|
|
#### Week 7: Advanced Monitoring
|
|
|
|
- [ ] Historical data visualization
|
|
- [ ] Alert management system
|
|
- [ ] Custom dashboard configuration
|
|
- [ ] Export/import functionality
|
|
- [ ] Advanced filtering and search
|
|
|
|
#### Week 8: Performance & Polish
|
|
|
|
- [ ] Performance optimization
|
|
- [ ] Accessibility improvements
|
|
- [ ] Mobile responsiveness enhancements
|
|
- [ ] Documentation and user guide
|
|
- [ ] Production deployment configuration
|
|
|
|
### 🚀 Current Development Environment
|
|
|
|
**Running Services**:
|
|
|
|
- **Development Server**: <http://localhost:5173> (Vite dev server)
|
|
- **Vue DevTools**: Available for debugging
|
|
- **Hot Module Replacement**: Active for instant updates
|
|
|
|
**Available Scripts**:
|
|
|
|
```bash
|
|
npm run dev # Start development server
|
|
npm run build # Production build
|
|
npm run preview # Preview production build
|
|
npm run test:unit # Run unit tests
|
|
npm run lint # Code linting
|
|
npm run format # Code formatting
|
|
npm run type-check # TypeScript checking
|
|
```
|
|
|
|
**Next Immediate Tasks**:
|
|
|
|
1. **Netdata Integration**: Connect to existing Netdata instance
|
|
2. **Real Data Flow**: Replace mock data with live system metrics
|
|
3. **Service Health**: Implement actual service status checking
|
|
4. **WebSocket Updates**: Add real-time data streaming
|
|
|
|
### Phase 3: Integration & Data (Weeks 5-6)
|
|
|
|
**Goal**: Connect to real data sources
|
|
|
|
#### Week 5: API Integration
|
|
|
|
- [ ] Connect to actual system monitoring APIs
|
|
- [ ] Implement WebSocket/SSE for real-time updates
|
|
- [ ] Add data caching and offline support
|
|
- [ ] Create API error handling and retry logic
|
|
- [ ] Implement data validation and sanitization
|
|
|
|
#### Week 6: Advanced Features
|
|
|
|
- [ ] Add user preferences and customization
|
|
- [ ] Implement advanced filtering and sorting
|
|
- [ ] Create detailed drill-down views
|
|
- [ ] Add export and sharing capabilities
|
|
- [ ] Optimize performance and bundle size
|
|
|
|
### Phase 4: Testing & Production (Weeks 7-8)
|
|
|
|
**Goal**: Production-ready application
|
|
|
|
#### Week 7: Testing & Quality
|
|
|
|
- [ ] Write comprehensive unit tests with Vitest
|
|
- [ ] Implement integration tests for critical paths
|
|
- [ ] Add accessibility testing and improvements
|
|
- [ ] Perform security audit and vulnerability testing
|
|
- [ ] Optimize for mobile devices and various screen sizes
|
|
|
|
#### Week 8: Deployment & Documentation
|
|
|
|
- [ ] Set up production build and deployment pipeline
|
|
- [ ] Create user documentation and help system
|
|
- [ ] Implement monitoring and analytics
|
|
- [ ] Conduct user acceptance testing
|
|
- [ ] Prepare for production deployment
|
|
|
|
## Acceptance Criteria
|
|
|
|
### Functional Acceptance
|
|
|
|
- [ ] User can log in securely and session persists appropriately
|
|
- [ ] Dashboard loads and displays all widgets within 3 seconds
|
|
- [ ] Real-time data updates work correctly across all widgets
|
|
- [ ] All system components are accurately represented
|
|
- [ ] Error states are handled gracefully with user feedback
|
|
|
|
### Technical Acceptance
|
|
|
|
- [ ] Code follows Vue 3 Composition API best practices
|
|
- [ ] TypeScript strict mode passes without errors
|
|
- [ ] All components are properly typed and documented
|
|
- [ ] Bundle size is optimized for fast loading
|
|
- [ ] Application works correctly on desktop and tablet devices
|
|
|
|
### User Experience Acceptance
|
|
|
|
- [ ] Interface is intuitive and requires minimal learning
|
|
- [ ] Information hierarchy is clear and logical
|
|
- [ ] Visual design is consistent and professional
|
|
- [ ] Accessibility requirements are met (WCAG 2.1 AA)
|
|
- [ ] Performance meets specified requirements
|
|
|
|
## Future Enhancements
|
|
|
|
### Short-term (3-6 months)
|
|
|
|
- **Mobile App**: Native mobile application for on-the-go monitoring
|
|
- **Advanced Analytics**: Historical data analysis and trending
|
|
- **Custom Dashboards**: User-configurable widget layouts
|
|
- **Alert Management**: Advanced alerting with escalation rules
|
|
- **API Integration**: Connect to additional monitoring tools
|
|
|
|
### Long-term (6-12 months)
|
|
|
|
- **Multi-tenancy**: Support for multiple home lab environments
|
|
- **Machine Learning**: Predictive analytics for capacity planning
|
|
- **Automation**: Integration with home automation systems
|
|
- **Advanced Visualization**: 3D network topology and service maps
|
|
- **Collaborative Features**: Multi-user support with role-based access
|
|
|
|
## Conclusion
|
|
|
|
The Home Lab Dashboard represents a focused solution for home lab monitoring that prioritizes clarity, performance, and ease of use. By following Vue 3 best practices and implementing a clean, component-based architecture, the dashboard will provide operators with the instant visibility they need to effectively manage their infrastructure.
|
|
|
|
The emphasis on introspection "at a glance" drives every design decision, ensuring that the most critical information is immediately accessible while maintaining the flexibility to drill down into details when needed. The SPA architecture with centralized state management will provide a smooth, responsive user experience that scales with the complexity of the underlying infrastructure.
|
|
|
|
This PRD serves as the foundation for building a tool that transforms the complexity of home lab operations into clear, actionable insights, ultimately making infrastructure management more efficient and enjoyable.
|