How AIVIS ships JSON-LD to customer websites without touching their CMS — updated in seconds, measured at the edge, and safe even if AIVIS itself were compromised.
A small Cloudflare Worker, deployed into each customer's own Cloudflare account, pulls that customer's approved JSON-LD from the live AIVIS Public API, caches it at the edge, and injects it into every HTML page just before </head>. No CMS access, no customer code changes. Updates go live in seconds via targeted cache purge. The worker treats AIVIS itself as untrusted input — a hacked AIVIS could never execute code on a customer site. Crawler analytics is a per-customer setting; off means zero data leaves their account. And the connector itself is an open-source project — every security team that must approve it can read the exact code.
§ 1 · The problem
AIVIS already generates and validates one Schema.org @graph document per URL. Getting it onto the page is where it stalls: today a strategist downloads a zip (implementation brief, manifest, llms.txt) and the customer's engineers paste snippets into their CMS. That takes days to weeks per change, and pages where the CMS is locked (is_editable = false) get no JSON-LD at all — by design (ADR-0004).
The connector replaces that hand-off with injection at the CDN edge. Publication latency drops from weeks to seconds, and the locked-CMS restriction disappears entirely — the worker rewrites the response, not the CMS.
§ 2 · Architecture
Three trust zones. The worker lives in the customer's Cloudflare account and is the only new thing in the serving path. AIVIS stays a pull origin behind a cache — if it is slow or down, pages serve exactly as before. The ops CLI is AIVIS's management plane, talking only to the Cloudflare API with a scoped token — including targeted cache purges, so a regeneration in AIVIS is live on the page in seconds (§3).
§ 3 · Runtime behaviour
GET /api/public/v1/jsonld?url=… with the bearer token. Every payload passes the zero-trust pipeline (§4 D9) before it may be cached. Over budget: skip this request, warm the cache in the background. 404s are negative-cached; API errors serve last-known-good.200 · text/html: HTMLRewriter streams the body through and inserts one <script type="application/ld+json" data-aivis> before </head>. Everything else in the page is byte-identical.waitUntil() flushes batched events. Cache refreshes also happen here — never on the visitor's clock.Schema entries are cached under synthetic URLs on the customer's own zone, which makes them addressable by Cloudflare's global purge API (propagates in seconds, all data centers). The worker's local cache.delete() is deliberately not used — it only clears one data center.
| Event | Live on site within | Mechanism |
|---|---|---|
| JSON-LD regenerated in AIVIS | Seconds | Auto purge hook: regenerate → single-file purge of that URL's cache key (spec V-03) |
| Manual per-URL invalidation | Seconds | ops invalidate --url · later a dashboard button |
| Manual per-domain invalidation | Seconds–minute | Batched purge over the business's URL inventory (AIVIS already has it) — never purge_everything |
| Retract a bad JSON-LD ("unpublish", no replacement) | Seconds | Unpublish in AIVIS ⇒ API returns 404 + auto-purge; a confirmed 404 also clears last-known-good, so a retracted block can never resurrect during an API outage (spec C-10 / V-08) |
| No purge rights (self-managed) | ≤ 5 min | TTL expiry; epoch-bump redeploy as the manual lever |
§ 4 · Decisions
Six calls are locked from our sessions; four more are recommended defaults — challenge those in the deep-dive specs, not during the build.
AIVIS operates it via a scoped API token; traffic never routes through AIVIS infrastructure. A self-managed sub-mode (their platform team deploys the same package) covers strict enterprises — see §6.
a CNAME proxy through an AIVIS-owned zone — serving-path liability and an enterprise-procurement wall.
The worker pulls GET /jsonld?url=… from the live Public API and caches at the edge. Targeted purges (per URL, per domain) make updates live in seconds despite the cache.
a KV-push pipeline — needs publish-state models and a Cloudflare write path that don't exist yet; revisit later as an optimization.
Analytics feeds the Monitoring subscription — the recurring-revenue layer — with data nobody can collect from outside. llms.txt serving and visible FAQ injection stay fenced out (§10).
a broader v1 — each extra surface adds a different risk class.
Deploy-time flag, default off (enterprise) and on for SMB. When off, the classifier never runs and no request-derived byte leaves their account toward AIVIS — a contractual statement, verifiable in their own Workers logs (invariant I8).
always-on telemetry — an instant no from enterprise privacy teams.
Every payload is strictly parsed, re-serialized with angle brackets escaped (script-breakout XSS becomes structurally impossible), shape/size-checked, bound to the business and domain, and optionally signature-verified against a key pinned in the customer's account. A hacked AIVIS can at worst serve wrong data, never code (invariant I7, spec §07).
trusting the API because "we control it" — the assumption every supply-chain attack feeds on.
The connector repo is public on GitHub (Apache-2.0 recommended), with signed releases and provenance. It runs in customer accounts anyway — public code turns the enterprise security review into an audit invitation, and self-managed deployment becomes normal OSS consumption. The AIVIS platform behind it stays private (spec §12).
gating the connector as proprietary — protects nothing that isn't already in customer hands, and costs the trust asset.
Bot-only injection is textbook cloaking risk, and it contradicts AIVIS's own Content-Parity doctrine (Methodenpapier). Everyone gets the same page.
injecting only for AI crawlers to "save" latency for humans.
Any internal error returns the origin response untouched. The kill switch is removing the worker route via the Cloudflare API — instant, and it involves zero connector code.
fail-closed or "maintenance" behaviour — a schema vendor must never be able to take a customer site down.
The worker inserts exactly one tagged script element. It never edits or removes existing markup; pre-existing on-page schema stays untouched, with conflicts reported through analytics. Withdrawing our own injected block needs no markup surgery — unpublish + purge stops injection in seconds (§3).
replacing or merging on-page JSON-LD — powerful, but a v2 conversation (spec §03).
v1 provisioning is an internal CLI run by the AIVIS team per customer — which matches the managed-service positioning. No self-serve dashboard yet.
building a customer-facing "Connect Cloudflare" flow before there's a fleet to justify it.
§ 5 · Components
</head>connect — validate the customer CF token + zonedeploy · verify (synthetic check of live pages)invalidate --url | --domain — the purge surfacepause / resume — the route kill switchuninstall · staged fleet upgradewaitUntil; loss-tolerant by designPOST /api/public/v1/events — ingest (new)EdgeConnection model (spec V-03)§ 6 · Delivery & handover
The worker always runs in the customer's Cloudflare account — in both modes. The only variable is who holds deployment rights. That's why the Allianz handover is a permissions change, not a migration: "it was always in your account" is the strongest sentence in the security review.
wrangler.toml + Terraform templates, runbook, changelog, checksumsProving ground: everything is developed and demonstrated on an AIVIS-owned Cloudflare zone with a demo site before it ever touches a customer account (spec §10, M1).
§ 7 · Analytics (opt-in)
When enabled, the worker sees what no external tool can: which AI systems fetch which pages, how often, and whether they got the enriched version. Per-URL, per-bot counts flow into AIVIS and become the evidence layer of the Monitoring subscription. When disabled — the enterprise default — none of this code runs and nothing is sent (D8).
| User agent | Operator | Purpose | Why it matters |
|---|---|---|---|
| GPTBot | OpenAI | training | Model training corpus — long-term brand memory |
| OAI-SearchBot | OpenAI | search index | ChatGPT search citations |
| ChatGPT-User | OpenAI | live fetch | A user is asking about this page right now |
| ClaudeBot | Anthropic | training | Model training corpus |
| Claude-SearchBot · Claude-User | Anthropic | search live fetch | Claude search + live citations |
| PerplexityBot | Perplexity | search index | Answer-engine index |
| Perplexity-User | Perplexity | live fetch | Real-time answers with citations |
| Googlebot (+ Google-Extended) | search + AI | AI Overviews / Gemini grounding. Google-Extended is a robots directive, not a separate crawler. | |
| Bingbot | Microsoft | search + AI | Copilot answers |
| CCBot | Common Crawl | training | Feeds many labs' training sets |
| Bytespider · Amazonbot · Applebot · meta-externalagent · MistralAI-User · DuckAssistBot | various | registry | Shipped as a config registry — extended without code changes |
Event shape (no IPs, no raw UA strings, no humans), batching, and registry maintenance: spec §05. A v1.1 middle path is spec'd for enterprises that want insight without egress: events written to a Workers Analytics Engine dataset inside their own account, read by AIVIS via the token it already holds.
§ 8 · Scope of work
The biggest de-risking fact of this project: the hard half already exists. The Public API v1 is deployed on the dev instance with exactly the endpoint the worker needs — documented in its live reference and OpenAPI spec — so the builder can develop against reality from day one. It returns the latest available artifact per URL.
Authorization: Bearer aivis_… · tokens from the profile pageGET /jsonld?url=… — permalink lookupplus /me · /businesses · /chains/{id}/urls · /urls/{id}/jsonldworker/ — the edge workerincl. zero-trust ingestion + purgeable cacheops/ — provisioning CLIconnect · deploy · verify · invalidate · pause · uninstall · upgrade§ 9 · Guarantees
These are acceptance criteria, referenceable by ID in every spec section and code review. Each maps to at least one automated test (spec §09).
Fail-open. Any internal error — API down, malformed schema, worker exception — yields the origin response, unmodified. There is no failure mode that alters or blocks the page.
Bounded latency. Added latency is ≈ 1 ms warm and hard-capped (~150 ms) cold; over budget means skip-and-warm, never wait. Non-HTML traffic is untouched entirely.
Parity. Identical HTML for every user agent. No bot-conditional content, ever — this is a cloaking and trust question, not a performance one.
Additive only. Exactly one <script type="application/ld+json" data-aivis> is inserted. Existing markup, including pre-existing schema, is never modified or removed.
Secret containment. The AIVIS bearer token lives only as a Worker secret — never in the page, logs, or analytics events.
Reversibility. Pause or uninstall restores the exact pre-connector serving path in under a minute, via route removal — no connector code involved.
Zero-trust ingestion. AIVIS output is untrusted input: strict parse, sanitizing re-serialization, shape/size checks, business + domain binding, optional pinned-key signatures. A fully compromised AIVIS can never achieve script execution on a customer site — worst case is wrong data, bounded by purge-all + pause runbooks.
Analytics off = zero egress. With analytics disabled, no request-derived byte leaves the customer's account toward AIVIS — verifiable by the customer in their own logs.
§ 10 · Scope fence
/llms.txt is cheap once the worker exists.ANALYTICS=local mode — events kept in the customer's own Workers Analytics Engine; spec'd as v1.1 (§7 note).§ 11 · The documentation set
This overview is the map. The build detail lives in the companion Full Specification 📘 — requirement IDs, config contracts, endpoint specs, threat model, test plan, milestones M1–M6, and the open-questions register (Q-1…Q-7) that should be resolved before the build starts.