System Architecture

This page describes how Host Monitor is structured, how data flows through the system, and the key runtime behaviors.

High‑Level Components

Class Diagram — Key Components & Data

What’s shown: Angular UI, WebSocket server, Go services (MonitorService, MetricsStore), persistence (PostgreSQL), and core data models. The Angular UI is embedded into the Go binary using go:embed and served by the backend (no separate backend/web directory).

Detailed Domain & Services

Class Diagram — Domain & Services (Detailed)

What’s shown: Method‑level view of domain models (HostMetrics, DTO), services (MonitorService, MetricsStore), settings/threshold API, and relationships.

Runtime Flows

Real‑Time Host Monitoring (Host 1 … Host N)

Sequence Diagram — Real‑Time Host Monitoring – Host

Flow: Browser → Angular Dashboard → WebSocket → Backend → Pingers → DB → WebSocket → UI.

Metrics Push Loop

Sequence Diagram — Real‑Time Metrics Push

Flow: Pingers report → MetricsService aggregates → DB upsert → broadcast JSON over /ws → UI renders.

Update Latency Threshold

Sequence Diagram — Update Latency Threshold

Flow: UI slider (debounced) → send { setThreshold } over /ws → backend acks and applies → UI toast.

Connection Behavior

WebSocket Reconnect & Backoff

Flowchart — WebSocket Reconnect & Backoff

Strategy: Exponential backoff (1s, 2s, 4s … max 30s). On reconnect, UI resubscribes and resumes live updates.

Host Status State Machine

State Diagram — Host Status

Rules:

First success → Up
Fail or latency > threshold → Down
Success with latency ≤ threshold → Up

Embedded UI (no `backend/web`)

The production Angular build is embedded in the Go binary. At build time we copy the UI artifacts into the backend and embed them via go:embed:

ui/dist/host-monitor-ui/browser/  →  backend/internal/handlers/dist/browser/

Example (in internal/handlers/static.go):

//go:embed dist/browser/*
var uiFS embed.FS
var staticFS, _ = fs.Sub(uiFS, "dist/browser")
// mux.Handle("/", http.FileServer(http.FS(staticFS)))

Why:

Single self‑contained binary (simpler deploys: systemd/Docker/K8s).
No drift between filesystem and served assets.
Safer defaults (read‑only embedded FS).

Project Structure

The Host Monitor repository is organized into the following main components:

host-monitor
.
├── backend                 # Go backend service
│   ├── cmd                 # Entry points (CLI / main)
│   ├── deployments         # systemd, Docker, Kubernetes manifests
│   ├── internal            # Core app modules (config, services, handlers, models, utils)
│   │   ├── handlers
│   │   │   └── dist
│   │   │       └── browser # Embedded Angular UI (copied from ui/dist/host-monitor-ui/browser)
│   ├── migrations          # SQL migrations for PostgreSQL
│   ├── pkg                 # Reusable packages (ping, websocket, etc.)
│   ├── scripts             # Helper scripts (e.g., ping-many.sh)
│   ├── Dockerfile          # Backend container build
│   ├── go.mod / go.sum     # Go dependencies
│   ├── host-monitor        # Compiled binary (after build; git-ignored)
│   ├── Makefile            # Build/install tasks
│   └── README.md
├── docs                    # Documentation site
│   ├── diagrams            # Architecture, sequence, and flow diagrams
│   ├── images              # Screenshots and visuals for docs
│   ├── architecture.md     # This page
│   ├── future_improvements.md
│   ├── index.md
│   ├── maintenance.md
│   ├── overview.md
│   ├── setup.md
│   ├── tech.md
│   └── usage.md
├── ui                      # Angular frontend
│   ├── dist                # Production build output
│   ├── node_modules        # Frontend dependencies
│   ├── public              # Static assets
│   ├── src                 # Angular components, services, styles
│   ├── angular.json        # Angular CLI config
│   ├── Dockerfile          # UI container build
│   ├── package*.json       # NPM dependencies
│   ├── proxy.conf.json     # Dev proxy settings
│   ├── README.md
│   └── tsconfig*.json      # TypeScript configs
├── docker-compose.dev.yml  # Multi-container dev environment
└── README.md               # Root project overview

Key conventions:

backend/ contains the Go services, WebSocket server, metrics logic, and optional DB integration.
ui/ is the Angular SPA, served separately in dev and embedded into the backend in production at backend/internal/handlers/dist/browser.
docs/ is a MkDocs-style documentation site (the .md files you’re reading now).
scripts/ has helper and deployment scripts (kept untracked in some cases for local overrides).
deployments/ contains systemd, Docker Compose, and Kubernetes specs for easy deployment.

Notes on Persistence

Each check is written to public.checks (host, up, latency_ms, packet_loss, checked_at).
DB connectivity is optional for local/dev; when configured, events are persisted asynchronously.