Case study 04 · In use

Link service

A self-hosted short-link service that passes campaign parameters on to the destination, keeps click analytics for every link and has a token-protected API that other tools can call to create links. It runs on several domains: adding a domain sets up DNS, SSL, cache rules and a certificate in one step, and redirects are served from the edge cache. The admin console has roles, an audit log and two-factor sign-in.

1 actionadds a domain with DNS, SSL, cache rules and a certificate

2 cache layersbetween a visitor and the app: Cloudflare's edge and nginx

25 server actionsbehind the console, each re-checking the signed-in user's rights

RoleDesigned and built with AI coding agents. I wrote the specs, reviewed and gated every release, and run it.

PeriodVersion history from April to October 2026

StackNext.js 15, TypeScript, Tailwind CSS, Auth.js, Prisma, PostgreSQL, Docker, nginx

IntegrationsCloudflare API (DNS, SSL, Cache Rules, purge), Let's Encrypt certificates, a token-protected API for creating links

01

Problem

The team needed short links on several domains, with campaign parameters passed on to the destination and click numbers for each link.

Setting up a domain by hand means a Cloudflare zone, a DNS record, an SSL mode, cache rules, a TLS certificate and a web server config. And a redirect should be cached to be fast, yet a link that was edited, archived or has expired must not keep sending visitors to its old destination.

02

What I built

A Next.js 15 app in Docker with PostgreSQL through Prisma. It decides by hostname: the admin hostnames open the console, and every other hostname is a link domain served by the redirect handler. Operators manage domains and links in the console, and other tools can call a token-protected API to create links.

A short-link request passes two caches before it reaches the app:

Illustration. Simplified request path of a short link.

03

Key parts

Links, lifecycle rules and click analytics

Each link has an alias on one of the domains, a destination and an owner. Links can be edited, archived, restored or deleted for good; archiving frees the alias for reuse.

Links list with 12 short links on three demo domains, each with its destination, click count and creation date, expiry and click-cap badges on some rows, and row actions for stats, preview, copy, edit, cache purge and archive — Demo data. Links with expiry and click-cap badges and a cache purge action on every row.

A link can expire on a date or after a set number of clicks. After that it answers 410 instead of redirecting.
Campaign parameters on the short link, such as UTM tags or click IDs, are passed on to the destination; a parameter on the short link replaces one with the same name in the destination.
Bulk import from CSV with a preview and an error for each invalid row; duplicates are skipped.
Search, a page size selector and a separate view of archived links.

Analytics dialog for one demo link: 5,264 all-time clicks against 3,708 in the last 30 days, clicks by day as a bar chart, and top countries, devices and referrers with their counts — Demo data. Click analytics for one link over the last 30 days.

For each link: clicks by day, top countries, device type and referrer, all-time against a 7, 30 or 90-day window.
Clicks are stored without the visitor's IP address, and referrers are cut to 200 characters.
Clicks are written in batches, every 5 seconds or every 500 events, so recording a click does not hold up the redirect.
Redirects answered from a cache never reach the app, so cached clicks are not counted. This is a deliberate trade for speed: the numbers are a lower bound.

Redirects served from cache, purged when a link changes

A link lookup ends in one of three answers, and each carries its own Cache-Control header.

302redirect to the destination, cached for up to one hour

404unknown or archived link, never cached

410expired link or click cap reached, never cached

Two cache layers sit in front of the app: Cloudflare's edge cache and an nginx cache on the server. Cloudflare's cache rules make the edge follow the app's own Cache-Control headers, and a cached redirect is answered without reaching the app.
The cache lifetime is at most one hour and shrinks to the time left before a link expires. When fewer than 50 clicks remain under a click cap, the redirect is not cached at all, so every click near the cap reaches the app and the link stops at its cap.
Link domains never go through sign-in, so redirect responses set no cookie that would stop the caches from storing them.
Editing, archiving, restoring or deleting a link purges it from both caches: the matching nginx cache file and the URL in Cloudflare. Each link also has a manual purge button, and a script can purge a whole domain.

Domain setup through the Cloudflare API

Adding a domain is one action in the console. The app creates the Cloudflare zone, the DNS record, the SSL mode and the cache rules through the Cloudflare API; then a small service on the server issues a TLS certificate from Let's Encrypt and writes the nginx config for the domain.

Domains page for managing custom domains with automatic Cloudflare setup, listing three active demo domains with their link counts, creation dates and a delete action — Demo data. Domains, each set up in one step.

A new domain is saved as pending and marked active when the Cloudflare steps are done. If the zone, DNS or SSL step fails, the app removes the new zone and the domain record again, so the operator can simply retry; a problem with the cache rules is logged and does not block the domain.
Subdomains of an existing domain reuse its zone and need only a new DNS record. A domain cannot be deleted while subdomains depend on it.
The service on the server tests the new nginx config before reloading and restores the previous config if the test fails. Certificates that are still pending are retried by a scheduled script.
Cloudflare is called only from server code, and the API token never leaves the server.

Admin console, roles, audit log and API

Operators work in the console, where roles decide what each user can see and change. The API is token-protected, and both the console and the API write to the audit log.

Audit log table with 25 actions by two demo users, including link creation through the API, link updates, archive and restore, a CSV import, a domain creation and enabling two-factor sign-in, each with time, entity, detail and a documentation-range IP address — Demo data. Audit log with who did what, when and from where.

Two roles: admins manage domains and see all links; users see and edit only their own links. There are 25 server actions behind the console, each re-checking the signed-in user's rights.
Two-factor sign-in with an authenticator app, set up by scanning a QR code. Sign-in is limited to 5 attempts per 15 minutes.
The audit log records link and domain changes, imports, failed sign-ins and rate-limit hits with the user, the time and the IP address. Usernames stay readable after a user is deleted, and a failed log write never blocks the user's action.
A token-protected API that other tools can call to create links. Asking again for the same destination returns the existing link instead of a duplicate.
The console can move to a new hostname without downtime: admin hostnames are kept in the database, and a fixed fallback hostname always works.

04

Reliability and guardrails

Admin hostnames are looked up with a 30-second cache, and concurrent lookups share one request. On an error the last known list is kept and the lookup retries after 5 seconds; the fallback hostname always works. 11 tests cover this lookup and the validation of domain input, with a simulated clock.
Adding a domain or a subdomain undoes its own partial work when a step fails: the new zone, DNS record or database row.
Redirects are limited to 100 requests a minute per IP address, and sign-in to 5 attempts per 15 minutes.
Deploys save a snapshot of the current source, rebuild the container and wait up to 60 seconds for it to report healthy. The app and PostgreSQL both have health checks, and the image is a multi-stage Docker build.
CI on GitHub Actions runs the lint and the build. Tokens and passwords are read from the server's environment and are not in the repository.

05

Results

The service runs on one Docker host: the app and PostgreSQL in containers, nginx and the certificates on the host. Operators add domains and links in the console without opening Cloudflare or the server, and links can also be created through the API. On 9 October 2026 the admin-hostname and subdomain features went from two written specs and a plan to working code: 18 of the 24 commits in the history landed that day.

06

What's next

Run the 11 tests in CI as well, so they gate every change, not only the lint and the build.
Add tests for the redirect handler (status codes, cache headers, parameter forwarding) and for the Cloudflare client.
Bring the setup docs up to date: some still describe features that were removed.
Replace the schema sync at start-up with versioned database migrations.

← Back to all work