Design principles

These are the rules that settle arguments when two designs both look reasonable. They explain why the system is shaped the way it is.

1. The URL is the product

The entire integration surface is a URL shape. Anything that would force a user to sign up, fetch a key, install an SDK, or read documentation before getting their first thumbnail is a regression. New capabilities should be reachable by changing the path or a query parameter, not by adopting an API.

2. Fail open, never blank

A thumbnail that fails should degrade to a clean image or a small fallback graphic — never an HTTP 500 or a broken <img>. The watermark transform fails open to the clean image; unknown and blocked videos fall back to a shared error.jpg / locked.jpg; provider failures are cached as negative results so they don’t repeat. A visitor should always see something reasonable.

3. Monetize without breaking free usage

Free traffic is never cut off with an error or a quota wall. The lever is the watermark: over-threshold free sites keep working, just with a visible mark that prompts a subscription. Conversion pressure comes from the image, not from downtime. Paying customers must never see a watermark, so the clean path is the safe default whenever the entitlement signal is ambiguous.

4. Cost discipline is a feature

Vumbnail runs on metered Cloudflare primitives, and the operator treats spend as a first-class constraint:

• Any change likely to add $1/month or more of Cloudflare spend requires a written cost estimate saved in docs/ before it ships.
• The cheapest layer that can answer a request should answer it. That’s why a free edge Snippet short-circuits hot watermarked traffic before the metered Worker runs, and why hot config values are hardcoded out of the KV read path.
• Hot-path KV reads, Worker invocations, and subrequests are measured and actively reduced.

5. Edge-first, resolve once

Resolving a video’s poster from the provider is the expensive, fragile step, so it happens as rarely as possible. A resolved thumbnail is persisted to R2 and served from cache thereafter; successful and failed resolutions are both memoized. The provider is the source of last resort, not the hot path.

6. Trunk-based and always deployable

Work lands on main. Incomplete features hide behind flags or branch-by-abstraction (KV-driven modes, rollout percentages, *-test subdomains) rather than long-lived branches, so a half-finished change never blocks deploying the rest. Rollouts ramp by percentage with health checks at each step, and risky edge changes ship with a rollback snapshot.

7. Observe before optimizing

Optimizations are driven by sampled production attribution, not hunches. The Worker emits cache-layer hit/miss counters on a small request sample; the operator ranks error buckets and miss paths before deciding what to fix. A plan without a measured baseline doesn’t ship.