Architecture on vanityURLs

Architecture decisions belong with the code

Tue, 26 May 2026 00:00:00 +0000

A setup page should tell an operator what to do.

It should not carry the full history of why the Worker, installer, schema, release automation, and runtime security rules have their current shape. That history still matters. It belongs beside the implementation.

vanityURLs keeps product-level decisions as architecture decision records in the code repository. The public docs stay operational. The code repo keeps the rationale that future maintainers will need when the next change looks obvious but is not.

From redirect file to Worker runtime

Fri, 15 May 2026 00:00:00 +0000

vanityURLs started with a deliberately small idea: a short domain, a text file, and redirects that could be reviewed in Git.

That first version mattered because it proved the core principle. A link shortener does not need to be a platform you rent from somebody else. It can be infrastructure you own.

The early shape

The earliest implementation leaned on Cloudflare Pages and static redirect behavior. That was enough for simple aliases, but it also exposed the first limits:

The current v8s architecture

Fri, 15 May 2026 00:00:00 +0000

The current v8s release is built around a small contract: keep the runtime simple, keep the source of truth in Git, and push abuse filtering as close to the edge as possible.

The instance model

An instance has two kinds of files:

defaults/ contains the product defaults, public operational pages, blocklist defaults, robots and LLM crawler guidance, and scripts that should be updated from upstream
custom/ contains the instance-owned links, schedules, policy replacement, branding, legal pages, and any intentionally local public files

That split is the upgrade story. If instance owners keep their work in custom/, future releases can refresh defaults/ and scripts/ without trampling local content.