Skip to content

SwissHD: Architecture & Overview

A fast, lightweight homelab dashboard built with React and TypeScript for the frontend, and Node.js for the backend. Designed to run on Kubernetes (K3s) using Docker and ArgoCD.

1. Overview

SwissHD functions as a centralized, grid-based administrative command center for on-premise infrastructure and self-hosted services. It bridges aesthetic precision with operational utility by providing real-time telemetry, service availability monitoring, and unified command navigation without cluttering the interface or exposing API credentials to the client.

  • Status: Active
  • Target Environment: Kubernetes (K3s) / Proxmox Virtualization Environment / Docker
  • Aesthetic Philosophy: International Typographic Style (Swiss Style)

2. Core Architecture

The system is structured into a three-tier architecture that enforces strict separation between visual configuration, server-side data control, and client-side presentation:

graph TD
    Config["Configuration Layer<br>(public/config.yaml)<br>Single source of truth for visible settings & layout"]
    Config --> Backend["Backend Control Layer<br>(backend/)<br>Node.js / Express server on port 3001<br>Polls 25 external APIs, caches data, isolates API secrets"]
    Backend --> Frontend["Frontend View Layer<br>(src/)<br>React + Vite SPA polling /api/dashboard every 5 seconds<br>Contains zero embedded API keys or passwords"]
    Backend --> Logs["Activity Journal<br>(SQLite)<br>Status changes, collector events, and dashboard logs"]
Component Path Function
Configuration public/config.yaml Single source of truth for visible UI settings (service declarations, theme colors, typography, links).
Backend Control backend/ Connects to external APIs, executes status checks, aggregates metrics, and caches responses. Isolates all secret tokens.
Frontend View src/ Displays real-time status and telemetry grids. Polls the backend /api/dashboard endpoint every 5 seconds.

Security and credential isolation are enforced by design. No authentication tokens, API keys, or service passwords are compiled into the frontend JavaScript bundle or transmitted to browser clients.

3. Design Standards & Aesthetics

The visual interface adheres strictly to the International Typographic Style, prioritizing mathematical grid alignment, high contrast, and functional minimalism:

  • Grid Architecture: All service cards, metrics panels, and quick links are organized within a strict modular grid to maximize visual scanning efficiency.
  • Dynamic Typography:
  • Display: Bricolage Grotesque is utilized for bold hierarchy and auto-scaling headers via container dimension calculation (useTextFit).
  • Body: Inter provides clean sans-serif legibility across all viewport resolutions.
  • Monospace: Self-hosted Maple Mono (.woff2) is assigned to numeric telemetry, status badges, and footer elements via custom CSS variables (--font-mono).
  • Asymmetric Composition: A black-and-white architectural photograph (/bw.jpg) is anchored to the left 35% viewport width at reduced opacity, transitioning into the solid slate background (#202124) via a smooth horizontal gradient fade.
  • Interactive Micro-Animations: Subtle hover accents, horizontal line drawing transitions, and a 60fps cursor-following glow effect (CursorGlow) enhance interactivity without inducing rendering lag.
  • Command Palette (Ctrl+K / Cmd+K): Administrative shortcuts, direct external queries (Google, GitHub, YouTube), and quick links are unified under a keyboard-driven search overlay.
  • Activity Feed / Logs: Recent operational events render as a sortable, paginated journal with expandable details for backups, ArgoCD sync/health events, service incidents, and generic metadata.

4. Supported Modules

The backend server automatically initializes modular integration handlers to poll external APIs and aggregate live telemetry. A total of 28 modules are supported natively across five operational domains:

  1. System & Network: Proxmox VE, Kubernetes (K3s), AdGuard Home, Nginx Proxy Manager, Traefik, Portainer, Speedtest
  2. Storage & Backup: Proxmox Backup Server (PBS), Longhorn, Backrest, FileBrowser Quantum, Storage
  3. Monitoring & Automation: Grafana, ArgoCD, NetAlertX, n8n, NocoDB, Authentik
  4. Media & Downloads: Jellyfin, Immich, qBittorrent, Sonarr, Radarr, Lidarr, Bazarr, Prowlarr, Navidrome
  5. Calendar & Context: Google Calendar, Media Release Dates (iCals), Open-Meteo Weather

5. Logs & Activity Journal

SwissHD includes an operational logs view backed by SQLite.

  • Collection: Background worker records service state changes and collector events.
  • Storage: activities, service_states, and collector_cursors tables persist journal state.
  • API: GET /api/activity reads logs; DELETE /api/activity clears the visible timeline.
  • Interface: Logs can sort by timestamp, status, or service, paginate 15 rows per page, and expand into typed detail panels.
  • Detail Types: PBS backup summaries, single backup records, ArgoCD sync/health records, service status incidents, and generic metadata events.
  • Delete Flow: DELETE LOGS opens a Swiss-style confirmation modal before purge.

Technical specifications, polled endpoints, required environment variables, and authentication schemas for each service are documented in the respective child pages under the modules reference:

→ Modules Reference