Architecture & Documentation

Overview

Monix works as a direct inspection and monitoring utility. Scan any public URL instantly — no login wall, no account required. For registered targets stored in Postgres, Monix runs scheduled uptime checks, tracks TLS certificate expiry, discovers subdomains (authenticated routes), and sends webhook alerts when configured on a target.

Public Inspection Engine

The public scanner endpoint is available at POST /api/scan. It accepts a JSON body with a url parameter:

curl -X POST https://monix.dineshkorukonda.online/api/scan \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Upon completion, the engine returns a JSON payload containing the diagnostic scores and a 12-character URL-safe nanoid slug for permanent public viewing at /r/[slug].

Inspection Pipeline

• Security Lens: TLS certificate validity, expiration date, issuer verification, and security headers (HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy).
• SEO Lens: Title tag length and presence, meta descriptions, Open Graph preview tags, robots.txt accessibility, XML sitemap discovery, and heading hierarchy.
• Performance Lens: Largest Contentful Paint (LCP), Cumulative Layout Shift (CLS), Total Blocking Time, and Google PageSpeed Insights lab metrics.

Rate Limiting

Public scanning is protected by a sliding 1-hour window rate limiter allowing up to 5 scans per hour per IP address. Requests beyond this threshold receive an HTTP 429 Too Many Requests response with a Retry-After header in seconds.

Reports & Persistence

All scans are stored in PostgreSQL table public.monix_scans and retrieved via GET /api/r/[slug]. Reports remain permanently accessible through their dedicated slug URL.

Local Development

Uptime Monitoring

Registered targets are pinged via POST /api/cron/uptime. Production uses the GitHub Actions workflow .github/workflows/uptime-cron.yml on schedule */5 * * * * (every 5 minutes). Set the repo variable MONIX_SITE_URL to your deployed origin.

• 2 consecutive failure threshold: A single failed check does not trigger an incident. Two back-to-back failures open a new incident record.
• Auto-resolution: When a target returns healthy, the active incident is automatically closed with a duration timestamp.
• Data is stored in public.uptime_checks and public.incidents — apply migration 003_uptime_and_incidents.sql.

Public Status Pages

Each target can have a public status page at /status/[slug]. Enable it by sending a PATCH request:

PATCH /api/targets/<target-id>
Authorization: Bearer <token>
Content-Type: application/json

{
  "public_status_page": true,
  "status_slug": "my-api"
}

The status page is publicly accessible — no login required. Setting public_status_page: false returns a 404 to all visitors. Requires migration 004_status_page_toggle.sql.

Certificate Tracking

A nightly cron at POST /api/cron/certificates (schedule: 0 2 * * *) inspects TLS certificates for all HTTPS targets. It records the expiry date, issuer name, and fires a webhook alert when within the warning window.

• Default warning threshold: 14 days before expiry. Configurable per target via cert_warning_days.
• Requires migration 005_certificate_expiry.sql.

Webhook Alerting

Set a webhook URL on any target and Monix will POST a JSON payload when critical events occur. Configure via PATCH /api/targets/<id> with { "webhook_url": "https://..." }.

• incident.started — fired when 2 consecutive checks fail.
• incident.resolved — fired when a downed target returns healthy.
• certificate.expiry_warning — fired when cert enters the expiry warning window.
• 5-second timeout, automatic 1× retry on non-2xx or connection failure. Full payload reference at /docs/webhooks.

Requires migration 006_webhook_alerts.sql.

Subdomain Enumeration

Monix discovers subdomains for any target using a native TypeScript pipeline — no external binaries required.

• Passive CT log lookup: Queries crt.sh Certificate Transparency logs to find all registered subdomains.
• Wildcard DNS detection: Tests a random non-existent subdomain to detect wildcard DNS, preventing false positives.
• Active liveness probing: Resolves IPv4 via node:dns and issues HTTP HEAD requests to determine live status and HTTP status code.

# Trigger a scan
POST /api/targets/<target-id>/subdomains
Authorization: Bearer <token>

# List stored results
GET /api/targets/<target-id>/subdomains
Authorization: Bearer <token>

Results are displayed on the public report page at /r/[slug] with live/DNS badges, IP addresses, and HTTP status codes. Requires migration 007_subdomains.sql.

Database Setup

Monix uses PostgreSQL for all persistence. Run the following migrations in order via your Supabase SQL Editor or psql:

psql $DATABASE_URL -f web/sql/init.sql
psql $DATABASE_URL -f web/sql/003_uptime_and_incidents.sql
psql $DATABASE_URL -f web/sql/004_status_page_toggle.sql
psql $DATABASE_URL -f web/sql/005_certificate_expiry.sql
psql $DATABASE_URL -f web/sql/006_webhook_alerts.sql
psql $DATABASE_URL -f web/sql/007_subdomains.sql

All migrations use IF NOT EXISTS guards — safe to re-run.