Synthetics Architecture

Synthetics is the synthetic-monitoring capability of Divinux — uptime monitoring and alerting for HTTP/HTTPS endpoints and TCP services.

Folded into Divinux

Synthetics was a standalone product API (apps/synthetics/, port 3002) until the D5 fold (May 2026), when it was absorbed into the single Divinux API. The standalone synthetics-api.statux.io host is now NXDOMAIN. The capability now lives in apps/divinux/src/modules/synthetics/ and serves under the synthetics route prefix.

Overview

The synthetics surface is part of the Divinux API (apps/divinux/), which runs on port 3003 and is served at divinux-api.statux.io. Synthetics endpoints mount under /api/v1/synthetics/organizations/:orgId/....

Core Concepts

Checks

A Check defines what to monitor and how:

• Check Types: HTTP, HTTPS, TCP
• Targets: URLs for HTTP/HTTPS, host:port for TCP
• Intervals: 30 seconds to 30 minutes
• Regions: AWS regions for distributed checks
• Relays: Private agents for internal network monitoring

Relays

Relays are private agents that can be deployed inside your network to monitor internal services:

• Connect to the API via secure token authentication
• Poll for assigned checks on a schedule
• Submit results back to the API
• Support heartbeat monitoring for connectivity status

Results

Check Results capture execution outcomes:

• Response time (ms)
• HTTP status codes
• TLS certificate info
• Error messages for failures
• Execution timestamps

Module Structure

apps/divinux/src/modules/synthetics/
├── checks/           # Check CRUD and querying
├── results/          # Check result storage and queries
├── relays/           # Private relay management
├── execution/        # Public check execution engine
├── aggregation/      # Metrics aggregation and S3 archival
├── webhooks/         # Webhook notifications
└── analytics/        # Usage analytics

Entities and migrations live in the shared apps/divinux/src/entities/ and apps/divinux/src/migrations/ directories alongside the other Divinux surfaces.

Key Entities

Check Entity

@Entity({ schema: 'divinux', name: 'checks' })
export class Check extends BaseEntity {
  organizationId: string;
  name: string;
  checkType: CheckType;        // http, https, tcp
  target: string;              // URL or host:port
  httpMethod: HttpMethod;      // GET, POST, HEAD
  expectedStatusCode: number;
  intervalSeconds: number;
  timeoutMs: number;
  regions: string[];           // AWS region codes
  relayId: string | null;      // Private relay assignment
  currentStatus: CheckStatus;  // up, down, degraded, unknown
  consecutiveFailures: number;
  failureThreshold: number;
  recoveryThreshold: number;
}

Relay Entity

@Entity({ schema: 'divinux', name: 'relays' })
export class Relay extends BaseEntity {
  organizationId: string;
  name: string;
  authToken: string;           // Hashed token
  authTokenPrefix: string;     // First 12 chars for identification
  status: RelayStatus;         // active, inactive, disconnected
  relayVersion: string;
  lastHeartbeatAt: Date;
}

API Patterns

Check Lifecycle

1. Create Check: Validate target format, set default regions
2. Execution: Either via public regions or private relay
3. Result Processing: Update check state based on thresholds
4. Alerting: Fire webhooks on status changes

Relay Authentication

Relays authenticate using bearer tokens:

// Token format: stx_relay_{64_char_hex}
// Stored as SHA-256 hash in database
const rawToken = `stx_relay_${randomBytes(32).toString('hex')}`;
const tokenHash = createHash('sha256').update(rawToken).digest('hex');

The RelayAuthGuard validates tokens and attaches the relay to the request.

Status State Machine

UNKNOWN → UP (on first successful check)
UP → DOWN (after failureThreshold consecutive failures)
DOWN → UP (after recoveryThreshold consecutive successes)
UP/DOWN → DEGRADED (on slow response or partial failure)

Testing

Run tests with (the synthetics specs run as part of the Divinux suite):

npm run test:divinux

Test files are located alongside service files:

• checks.service.spec.ts
• relays.service.spec.ts
• results.service.spec.ts

Database

Uses the divinux schema in PostgreSQL (the standalone synthetics schema was absorbed in Phase D.5). All entities follow the snake_case naming convention for database columns.

Key Tables

Table	Purpose
checks	Check definitions
check_results	Execution results
relays	Private relay agents
webhook_subscriptions	Notification webhooks
users	Organization user access