Architecture

How the open-source client, hosted watchtower, and alert pipeline fit together.

Five-layer map

Contract reliability stacks five layers — detection, status, policy, remediation, and agent MCP surface. Full diagram and adoption paths: Five-layer map →

System overview

DriftGuard uses a free client, paid monitoring split: developers run local schema comparison and MCP tools in CI and IDEs; the hosted service owns snapshot scheduling, storage, classification, and notifications.

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│ OSS CLI/MCP │────▶│ driftguard.org   │────▶│ Slack / PD  │
│ (CI, Cursor)│     │ snapshots + diff │     │ alerts      │
└─────────────┘     └──────────────────┘     └─────────────┘
       │                      │
       │ offline diff         │ console + API
       ▼                      ▼
 compare_json            /api/watches/*

Snapshot loop

  1. Watch stores target URL, type (REST OpenAPI, MCP tools/list, raw JSON schema).
  2. Scheduler fetches on interval (plan-dependent) and normalizes to a canonical schema.
  3. Diff engine compares to previous snapshot; emits classified changes[].
  4. Alert router sends breaking-only notifications per watch policy.

CI funnel

CI integration is designed as hook → preview → trial → gate. See CI coverage how-to and OSS docs/CI.md on GitHub.

Data stores

Hosted service runs on Cloudflare Workers with D1/SQLite for watches and drift history, R2 for large snapshots, and KV for rate limits. Exact topology is internal — public contract is the REST API and console.

Agent integration

Agents should read /agents.md and call explain_drift with structured changes[] to receive agentAction remediation strings.