Ventora Platform

The decision

Python code in Ventora sent email by posting a signed payload to a small Cloudflare Worker, email-renderer, which rendered the real React Email templates and returned HTML and text. The alternative was a second template set in Python that would have drifted within a month.

Half of Ventora’s consumers were TypeScript and half were Python, and most of the cross-language contract (analytics event names, PII redaction rules) was solved by generating both languages from one JSON schema and byte-comparing the output in the verify gate, so the two runtimes could not drift apart quietly. React Email templates are React, so email rendering used a different solve for the same problem: the Worker above let the Python client call the real templates directly, over an HMAC-signed bridge, keeping both languages rendering from one source.

The parity that mattered on the email path was byte parity of the string that gets signed. The Python client serialized timestamp, nonce, method, path, and body in exactly the key order the Worker used to rebuild the same string, so json.dumps(separators=(",", ":")) and JSON.stringify had to agree byte for byte or the HMAC failed.

An end-to-end test booted the real Worker under wrangler dev and drove the real Python client against it, so that agreement was proven rather than asserted. The cost was a network hop and a Worker kept alive for a single template render, in exchange for a signature scheme proven correct across both languages before it shipped.

Architecture

Everything in the repository except five packages was published as a versioned package and consumed as a private dependency by other products; nothing else here was a deployment target in its own right.

The five exceptions were the deployed Cloudflare Workers. email-renderer let Python render React Email templates without a JS runtime, over the HMAC-signed bridge above. ai-sdr-worker held anonymous marketing-assistant session state in a Durable Object, with a durable outbox and an alarm-driven retry ladder (0s, 30s, 2m, 10m, 1h) so a streaming reply never waited on a lead push to a product’s CRM.

ai-cs-worker served the authenticated in-app support assistant, fetching a signed per-app context from the product and still treating the payload as untrusted, sanitized and length-capped before it reached a prompt. package-registry and python-registry were a private npm registry and a private PEP 503/691 Python index, both implemented from scratch on R2, so every other package in the monorepo had somewhere to publish to and install from without a third-party registry in the loop.

Two widgets, two rules for model output

The hosted AI-CS client, the vanilla-JS build every product embedded on its own marketing pages, rendered every assistant reply through textContent, never innerHTML (packages/ai-cs-worker/src/hosted-client.ts). There was no markdown parser in that path at all, by design: model output landed on a page the widget did not control, so the safest rule was to never interpret it as markup.

@ventora/ai-cs, the React package a product could embed inside its own authenticated app, took the other side of that choice and rendered markdown, through a closed whitelist parser (packages/ai-cs/src/react/markdown.tsx) whose own docstring stated it was “XSS-safe by construction” and never called dangerouslySetInnerHTML. The parser’s behavior under partial input was asserted in the package’s own tests: its inline pattern only recognized a **bold** span once both delimiters had arrived, so a reply captured mid-stream, before the closing ** streamed in, showed literal asterisks for a moment, exactly as the tests expected. One client stripped formatting on purpose, the other rendered it once it could prove it was safe to.

Verification

pnpm verify chained nine steps: a schema check, a metrics check, a secret scan, script tests, lint, typecheck, coverage enforced per file across 19 vitest configs and 6 Python packages, and two smoke suites that installed the built TypeScript and Python artifacts and imported them the way a product would. The in-process Worker E2E tier and the Playwright browser E2E tier were split out as their own commands, run on demand, so the fast local gate stayed fast.