Architecture Overview

Core Components

• Hub (Control Plane) — The central service responsible for API routing, monitor configuration, result aggregation, alert evaluation, incident management, and the agent registry. Runs as a Node.js/Express server backed by PostgreSQL.
• Agents (Data Plane) — Lightweight Node.js processes deployed to your servers, containers, or cloud functions. Agents have zero npm dependencies — they use only Node.js built-in modules. Each agent fetches its assigned monitors, executes health checks, and pushes results back to the hub.
• Dashboard — A Vue 3 SPA that connects to the hub via WebSocket (Socket.IO) for real-time status updates. Displays the connectivity matrix, monitor details, incidents, and agent health.
• Database — PostgreSQL stores all configuration (users, monitors, agents, alert rules) and operational data (check results, incidents, heartbeats). Managed via Knex migrations.

Monitoring Model

Every monitor defines a relationship between a source and a destination:

• Source — The agent (or location) where the check originates. Represents a network vantage point.
• Destination — The endpoint being checked (a URL, host:port, DNS name, Redis instance, etc.).
• Monitor — Binds a source to a destination with a check type (HTTP, TCP, DNS, etc.), interval, timeout, and expected result criteria.

This model creates a connectivity matrix — sources on one axis, destinations on the other — giving you a complete view of reachability across your infrastructure.

Data Flow

1. Registration — An agent starts, authenticates with its API key, and registers with the hub via Socket.IO.
2. Assignment — The hub pushes the agent's assigned monitors (filtered by source) to the agent.
3. Execution — The agent runs checks on the configured schedule (default: every 60 seconds). Supported protocols include HTTP, TCP, DNS, Redis, and Azure Service Bus.
4. Result Push — After each check, the agent pushes the result (status, latency, response details) to the hub.
5. Auto-Diagnostics — If a check fails, the agent automatically runs DNS resolution, ping, and port connectivity tests, then pushes diagnostic data alongside the failure.
6. Aggregation — The hub stores results in PostgreSQL, updates the real-time dashboard via WebSocket, and evaluates alert rules.
7. Alerting — When alert conditions are met (e.g., 3 consecutive failures), the hub creates an incident and dispatches notifications through configured providers.

Real-Time Updates

The hub uses Socket.IO for bidirectional communication:

• Hub → Agent — Pushes monitor configuration changes, schedule updates, and control commands.
• Agent → Hub — Sends check results, heartbeats, and diagnostic reports.
• Hub → Dashboard — Broadcasts status changes, new incidents, and agent connectivity events to all connected dashboard clients.

Scalability Roadmap

• Phase 1 (Current) — Single hub instance + PostgreSQL. Handles hundreds of monitors and agents efficiently with connection pooling.
• Phase 2 — Redis queue for decoupling result ingestion from alert evaluation. Worker processes for parallel alert processing.
• Phase 3 — Dedicated metrics storage (TimescaleDB or ClickHouse) for long-term result retention and analytics. Horizontal hub scaling behind a load balancer.

Security Model

• Agent Authentication — Each agent authenticates with a unique API key issued at registration. Keys are hashed and stored server-side.
• Transport Encryption — All agent-hub communication uses TLS (HTTPS/WSS). No plaintext traffic.
• Tenant Isolation — Multi-tenant design with row-level filtering. Agents and monitors are scoped to their owning user.
• Outbound-Only Agents — Agents initiate connections to the hub. No inbound ports need to be opened on your infrastructure.

Deployment Topology

A typical production deployment consists of:

┌─────────────────┐     ┌─────────────────┐
│  Agent (VPC-A)  │────▶│                 │
└─────────────────┘     │                 │
                        │   Hub / API     │──▶ PostgreSQL
┌─────────────────┐     │                 │
│  Agent (VPC-B)  │────▶│                 │
└─────────────────┘     └────────┬────────┘
                                 │
┌─────────────────┐              ▼
│  Agent (On-Prem) │────▶  Dashboard (SPA)
└─────────────────┘

Agents can be deployed anywhere — cloud VMs, Docker containers, Kubernetes pods, serverless functions (AWS Lambda, Azure Functions, GCP Cloud Functions), or bare-metal servers. The only requirement is outbound HTTPS connectivity to the hub.