Architecture Views

Does serving a click touch the authoritative link table, or a derived copy of it that the click path cannot modify?

Context

The tutorial architecture is one service and one database: look up the code, increment a counter, return a redirect. At a 500:1 read-to-write ratio it means the write store must be provisioned for the read rate, the redirect's availability becomes the availability of the click pipeline, and a bulk import competing for the same store slows down everybody's clicks. Every softer variant has the same defect in a smaller form — a click that writes anything synchronously, even asynchronously flushed from the same process, makes a printed link's behaviour depend on the health of a system it has no reason to depend on. And the failure is not graceful: the codes people are clicking most are exactly the ones whose writes are hottest.

Decision

The link table is written only by the management plane. The redirect plane reads a projection of it — an edge response cache, a regional hot set, an in-region read replica — plus a separately propagated deny-set, and holds no credential that could write anything. A click produces no synchronous write of any kind. The redirect plane must be able to serve for at least four hours with the entire management plane unavailable, learning nothing new but losing nothing already known.

How it is realised on Google Cloud

Cosmos DB with a single write region, read replicas in all twelve read regions, and the change feed as the only route from authoritative state into derived state. Resolvers run on Container Apps with a workload identity holding read-only data-plane permissions; there is no connection string and no write role to steal. Front Door caches the redirect for 30 seconds and forwards misses over Private Link to the nearest regional origin group.

Options weighed

• ChosenRead-only redirect plane fed by one-way propagation: Makes redirect availability independent of the writer, caps the write store's provisioning at the real write rate, and makes the whole read tier disposable. Costs eventual consistency, which is why ADR-15 publishes the bounds.
• RejectedOne service reading and writing the link table on the click path: Correct in every steady-state diagram and wrong at the first hot key or bulk import. Also makes the click path a write path, which is a security property nobody intended to give away.
• RejectedRead from the authoritative store, write nothing: Removes the write but keeps the coupling: a write-region incident or an RU exhaustion from a campaign import becomes a global redirect incident.
• Right elsewhereStrongly consistent reads in the redirect path: Right for a system where a stale read is a correctness violation — a payment authorisation, a feature entitlement. Here a stale read means a link points at last week's page for up to five minutes, which is a published property rather than a bug.

Consequences

What it buys

• A total management-plane outage costs zero redirects; creation fails visibly and clicks continue.
• The entire read tier is disposable and rebuildable in 30 minutes, so a regional incident is a capacity event rather than a data event.
• Provisioning the write store for the write rate rather than the read rate is the single largest cost saving in the design.

What it costs

• Two propagation channels to build, operate and reason about, with two published staleness bounds.
• A code exists authoritatively before it is resolvable everywhere, which is why a creation response carries a resolvable-within figure.
• Debugging is harder: the question 'why did this link resolve to that?' has to be asked of a projection first and the record second.

Choose differently when

Collapse the planes when read and write rates are comparable, the whole system fits in one region, and nobody has printed anything — an internal `go/` link service for a single company is in that category and should be built as one service with one table.

Why it holds up over time

This is the decision least tied to Azure and most likely to be eroded by a feature request. Nothing here depends on Front Door, Cosmos DB or Container Apps. What would break it is real-time click counts on the redirect response, or a 'resolve the latest destination, guaranteed' option sold to one large customer — which is why the boundary is drawn in views 08 and 14 rather than left as a convention.

Does 'stop serving this code' use the same propagation path as 'this code now points somewhere else'?

Context

Both are changes to a link, so one mechanism is the obvious answer. But they have different deadlines by a factor of five and different payloads by orders of magnitude. An edit carries a full record and can take five minutes; a kill carries an identifier and cannot. Sizing a single channel for the tighter deadline means paying that cost on every routine edit, and at 1.2 million creations a day that is not a rounding error. Worse, the urgent case is the one with a legal and reputational clock attached: a phishing link that keeps resolving for five minutes after an analyst pressed block is the platform's worst day, and 'we propagate all changes the same way' is not a defence anyone accepts.

Decision

Revocation is a separate, aggressively propagated channel carrying a compact set of codes that must stop resolving — killed, expired early, or blocked for abuse. Regional deny-sets pull deltas every 5 seconds and are matched before any cache layer, so a region with the delta stops serving regardless of what its hot set holds. Routine changes ride the change feed with a five-minute bound. Both bounds are published. A change classifier decides which channel a write takes, and misclassification is treated as a safety defect, not a latency one.

How it is realised on Google Cloud

Event Grid topic per region for the revocation delta, consumed into an in-process set in each resolver with a 5-second refresh and an age metric. The projection path is the Cosmos DB change feed into a per-region projection worker that upserts the Redis hot set. The 30-second Front Door cache TTL is what bounds the end-to-end worst case at 60 seconds, and a synthetic probe kills a real link every minute and measures when the last PoP stops serving it.

Options weighed

• ChosenA separate fast channel for stop instructions: Buys urgency where it is needed and nowhere else. The payload is small enough to push everywhere in seconds, and the deny-set check is cheap enough to run before the lookup.
• RejectedOne channel sized for the 60-second deadline: Simpler to build and operate, and pays the urgent cost on all 1.2 million daily creations. It also couples the safety promise to the throughput of the routine path — a change-feed backlog becomes a safety incident.
• DeferredCache purge per code at the edge on every revocation: A real option for tightening the bound below 30 seconds, and a slower, less predictable fan-out than an expiry. Worth adding when a customer or a regulator needs a bound the TTL cannot give.
• RejectedDelete the link record and let the negative cache take over: Destroys the evidence, the appeal path and the click history, and makes an accidental block unrecoverable. A blocked link must remain a link.

Consequences

What it buys

• The safety promise is met by a mechanism sized for it, and can be stated as a number: 30 s p95, 60 s p99.
• Routine edits stay cheap, so the platform is not paying urgency tax on every campaign import.
• The deny-set is small enough to hold in process, which makes the check free relative to the lookup it precedes.

What it costs

• Two sources of truth on the read path, which must never disagree in the wrong direction. The deny-set therefore always wins and is checked first.
• A classifier that can mislabel a kill as an edit, which is a silent failure — hence the synthetic probe rather than a component health check.
• One more thing to rebuild after a regional restart, and the one whose absence is dangerous rather than merely slow.

Choose differently when

One channel is right when the urgent bound and the routine bound are the same, or when the write rate is low enough that paying urgency tax on everything is free. A platform doing a thousand creations a day should not build two channels.

Why it holds up over time

The two-bound structure should outlive the transport. Event Grid, the change feed and even the 5-second pull are implementation; what must survive is that stop instructions do not queue behind content updates, and that both bounds are numbers the platform says out loud.

Does the platform tell customers how long a change takes to take effect, or let them assume it is instant?

Context

Every eventually consistent path in this design has a real bound: 60 seconds for a revocation, five minutes for a destination edit, ten seconds for a new link to be resolvable everywhere, one second in the creating region. A platform that says nothing is assumed to be instant, and then every support conversation is a negotiation, every abuse response is unaccountable, and every customer's expectation is set by whichever anecdote they heard first. Publishing a number invites arguments about the number, which is exactly the point: a number can be measured, challenged and improved, and a vague promise cannot.

Decision

Every eventual path states its bound in the product documentation, in the API response where relevant, and in the SLO set. Revocation 30 s p95 / 60 s p99; destination edit 5 minutes p99; new link resolvable globally 10 s p99, in-region 1 s p99; scheduled expiry effective within 60 s of the stated instant. Each bound has a synthetic probe measuring it end to end from outside, and a change to any bound is a product change with a release note, not a tuning adjustment.

How it is realised on Google Cloud

Probes run continuously and land in Azure Data Explorer: a synthetic link is killed every 60 seconds and its last-serving PoP measured, an edit is made and its global visibility timed, a new link's resolvability is sampled across regions. Alarms fire on the published promise rather than on component health, because every failure this platform fears looks healthy at the component level.

Options weighed

• ChosenPublish every bound, probe every bound: Makes the design's central trade-off legible and auditable, and turns support answers into one sentence.
• RejectedState nothing and aim to be fast: Customers assume instant, the platform is judged against that, and no internal argument about caching can be settled.
• RejectedPublish a single conservative number for everything: Simplifies the documentation and discards the distinction that the whole two-channel design exists to create.
• Right elsewhereOffer strong consistency as a premium tier: Coherent for a configuration or entitlement service where staleness is a correctness bug. Here it would require the read path to coordinate globally, undoing ADR-01 for the customers who pay most.

Consequences

What it buys

• Support, sales and abuse response all use the same sentence, and it is checkable.
• Alarms test what is sold rather than what is running, which catches the silent failures.
• The 30-second cache TTL becomes a visible, arguable trade instead of a hidden setting.

What it costs

• Published numbers can be missed publicly, and a missed bound is now a breach rather than an anecdote.
• Probe infrastructure to build and keep honest, including synthetic links that must never be mistaken for customer data.
• Tightening a bound later is a product commitment, so the initial numbers need to be defensible rather than optimistic.

Choose differently when

Skip publication only where no external party can observe the staleness — an internal cache with a single consumer that is also the writer.

Why it holds up over time

The numbers will change and the practice should not. Publishing bounds is what keeps an eventually consistent system honest over a decade of staff turnover, because the next team inherits a contract rather than a folk belief.

Where does a generated code come from: a random draw, an encoded counter, a pre-allocated block, or a hash of the destination?

Context

A counter encoded to base62 is the efficient answer: dense, collision-free, no read before write. It is also enumerable, and enumerability is a disclosure vulnerability rather than an aesthetic complaint — walking the space reveals every tenant's destinations, including the unlisted document, the internal deck and the pre-announcement landing page. A globally monotonic counter is also a coordination point on the write path, which is exactly the thing a multi-region creation story cannot afford. Hashing the destination deduplicates identical links for free, which some customers want and others consider a privacy breach: two tenants shortening the same URL must not be able to detect each other. A random draw needs a uniqueness check and a retry loop that gets worse as the table fills.

Decision

Generated codes are drawn at random from a base62 alphabet with a default length of 7 characters, giving roughly 3.5 × 10¹² codes against an assumed 12 billion stored and 1.2 million created per day. Allocation is a conditional create against the reservation index, retried on conflict. Sequential or otherwise enumerable codes are never issued on shared domains. Lengthening the default is the planned response to density, and the code length is therefore a per-domain configuration rather than a constant in the code.

How it is realised on Google Cloud

A cryptographically seeded random draw in the management plane, then a conditional create (`If-None-Match: *`) against the reservation container in Cosmos DB, keyed by `(domain, code)`. At the assumed density the expected retry rate is negligible; the retry count is a metric precisely because it is the leading indicator that 7 characters have stopped being enough.

Options weighed

• ChosenRandom base62, 7 characters, conditional create: Unguessable, no write-path coordination, and the retry cost is a function of density that can be monitored and answered by lengthening.
• RejectedEncoded global counter: Dense and cheap, enumerable, and a coordination point. Enumerability alone disqualifies it on a shared domain.
• DeferredPre-allocated per-region blocks: Removes coordination entirely and is the right answer if creation must survive a regional partition. Deferred because ADR-05 already accepts refusing creation during failover, and blocks add per-region accounting for a case that has not been asked for.
• RejectedHash of the destination: Free deduplication and a cross-tenant information leak: two tenants shortening the same URL would collide into one code and learn something about each other.

Consequences

What it buys

• A code discloses nothing about when it was created, who created it, or what exists next to it.
• Creation needs no global sequence, so the write path has one fewer coordination point than the counter design.
• Density is a monitored, answerable condition rather than a cliff.

What it costs

• A read-modify-write on allocation, which is why the uniqueness authority has to be strongly consistent (ADR-05).
• Seven characters are longer than a counter would need for the same population — the price of unguessability.
• Retry rates climb with density, so the code length is a parameter somebody must eventually change.

Choose differently when

Use a counter when the codes are not secret and never shared outside a trust boundary — an internal short-link service, or a system where every destination is already public by construction. Use a content hash when deduplication is an explicit product feature and single-tenant.

Why it holds up over time

The alphabet and the length will change; the property must not. 'A code reveals nothing about its neighbours' is what makes shortening safe for unlisted destinations, and it is the kind of property that is quietly lost when somebody adds sequential vanity codes for a launch.

When a link is deleted or expires, may its code be issued again to someone else?

Context

Reuse is tempting for exactly one reason: short, memorable aliases are scarce, and a customer who abandons `/spring` is holding an asset somebody else wants. But a short code's lifetime is not the platform's to decide. It is on a poster, in a printed programme, in an email thread from two years ago, in a QR code etched into a product. Reissuing it means that artefact now resolves to a stranger's destination — the worst outcome this platform can produce, worse than a dead link, because the clicker has no way to know it happened. The address space makes the trade absurd: at 7 characters there are roughly 3.5 × 10¹² codes and an assumed 12 billion in use, so reclamation recovers nothing that matters.

Decision

A code, once issued, is never reassigned to a different link and never reissued after deletion or expiry. The reservation record outlives the link record and carries a retired flag, so a claim against a retired code fails exactly as a claim against a live one does. A tenant deleting a link releases their quota, not the code. Destinations are mutable; codes are not.

How it is realised on Google Cloud

The reservation container is never deleted from. Link deletion marks the reservation retired and removes the link record; a subsequent conditional create fails against the retained reservation. Retired codes resolve to 404 through the negative cache rather than being absent from every store, so an enumerating client cannot distinguish 'never existed' from 'retired'.

Options weighed

• ChosenPermanent retirement, reservation outlives the link: Makes the catastrophic outcome structurally impossible rather than unlikely, at a storage cost of a few tens of bytes per retired code.
• RejectedReuse after a quarantine period: Any finite quarantine is shorter than a printed poster's life. It converts a structural guarantee into a bet on how long paper lasts.
• RejectedReuse only for codes that never received a click: Superficially safe and wrong: a code printed for a campaign that has not launched yet has no clicks and is the most dangerous possible candidate for reuse.
• RejectedLet the tenant decide: The risk is borne by the clicker, who is not party to the decision. This is not a tenant-configurable property.

Consequences

What it buys

• A printed code can never resolve to somebody else's destination. The platform's worst failure mode is removed by construction.
• The uniqueness check has one rule, not one rule plus an age exception, which is what keeps the race test in view 19 simple enough to trust.
• Deletion becomes cheap and reversible in the only way that matters: the identity is still held.

What it costs

• The reservation store grows monotonically and is never compacted — an accepted, small, unbounded cost.
• Desirable aliases are permanently consumed, including by tenants who have left, and the platform must be willing to say no.
• Support will be asked for exceptions, and the answer has to be no every time, which only holds if the mechanism makes it impossible rather than discouraged.

Choose differently when

Reuse is defensible when every link is short-lived by contract and never leaves a digital channel the platform controls — a one-time password link, a session share expiring in an hour. The moment a code can be printed, retirement is the only safe answer.

Why it holds up over time

This is the promise that ages best and is most likely to be attacked by a future team looking at a table of valuable retired aliases with a revenue number next to it. It costs almost nothing to keep and cannot be recovered once broken, because the evidence arrives years later as somebody else's QR code.

How is `(domain, code)` guaranteed unique when creation happens concurrently, and what consistency does the rest of the system get?

Context

Two clients asking for `go.acme.com/spring` in the same millisecond must produce exactly one winner and one clear conflict. A read-then-write cannot guarantee it. An eventually consistent store with last-write-wins conflict resolution actively hides the problem: both writers succeed, both are told they own the alias, and one of them silently loses their link later — which is worse than a rejection, because they have already sent the artwork to print. Meanwhile the read path needs the opposite property: a globally strongly consistent read on every redirect would turn a 40 ms budget into a cross-region coordination problem.

Decision

The reservation index is the single strongly consistent component in the architecture, written by conditional create in one write region. Exactly one writer wins; the loser receives a 409 naming the collision and is never given a substituted code. Everything else — the projection, the hot set, the edge cache, expiry by TTL — is eventually consistent, with its staleness published (ADR-15). Multi-region writes are refused: during a write-region failover, creation is unavailable for up to five minutes rather than risking two winners.

How it is realised on Google Cloud

A Cosmos DB container keyed by `(domain, code)` in a single-write-region account, written with `If-None-Match: *` so the insert is a genuine compare-and-set. The link record is written after the claim succeeds. Failover to the standby write region is explicit, and the management API returns a retryable error for creation throughout.

Options weighed

• ChosenConditional create against a single-writer index: A real compare-and-set with no coordination protocol to build. Costs creation availability during failover, which the requirement accepts in exchange for zero duplicate claims.
• RejectedMulti-region writes with conflict resolution: Keeps creation available everywhere and makes uniqueness probabilistic: last-write-wins picks a winner after both clients were told they had succeeded.
• RejectedRead-then-write with a uniqueness index: Works until two requests interleave, which at 1.2 million creations a day is daily rather than theoretical.
• Right elsewhereA dedicated consensus service for allocation: Right when allocation must survive a regional partition and cannot wait — a payment identifier mint, for instance. Here it is a whole distributed system added to avoid a five-minute creation outage.

Consequences

What it buys

• Duplicate ownership of a code is impossible, which is the platform's one zero-tolerance guarantee.
• The conflict is honest and immediate, so a customer discovers it before the artwork goes to print rather than after.
• Exactly one component needs strong consistency, so the other twenty-two views can be designed around eventual consistency without hedging.

What it costs

• Creation is unavailable during a write-region failover, for an assumed RTO of up to five minutes.
• Creation latency includes a cross-region round trip for clients far from the write region, which is why the 250 ms p99 is a creation figure and not a redirect figure.
• Bulk imports must be resumable, because a failover mid-import is a normal event rather than an exception.

Choose differently when

Multi-region writes become correct as soon as uniqueness stops being global — per-region namespaces, or codes that embed their origin region. If the product can accept `eu/spring` and `us/spring` as different links, this decision dissolves.

Why it holds up over time

The technology will change; the rule should not. 'Exactly one thing is strongly consistent, and it is named' is what keeps a distributed system arguable. Systems decay when the list of strongly consistent things grows quietly, one convenience at a time.

Is `spring` one alias across the whole platform, or one per domain?

Context

A global namespace is simpler: one key, one index, one uniqueness rule. It also means the first customer to claim `sale` takes it from every other customer forever, which is indefensible when 12,000 of those customers are paying for their own branded domain. Per-domain namespacing is what a branded-domain customer already assumes — they bought `go.acme.com` precisely so that its paths are theirs — and it multiplies the reservation index's key space by the number of domains, which is a scale question rather than a correctness one. The shared domain is the interesting case, because there the namespace really is contested and brand-adjacent aliases are a trust problem rather than a first-come-first-served one.

Decision

The namespace key is `(domain, code)`. Two tenants may each own `spring` on their own domains. On the shared domain a reserved-name deny-list applies — operational paths, single characters, profanity, and strings resembling well-known brands — and generated codes are always unguessable (ADR-03). Branded domains are first-class: same latency objective, same availability objective, same code space semantics.

How it is realised on Google Cloud

Reservation and link containers are both partitioned on domain with code as the row key, so a branded domain's claims and lookups are local to its partition, and a new domain adds partitions rather than contending for an existing one. Front Door serves all domains from the same anycast address set with per-domain managed certificates.

Options weighed

• ChosenPer-domain namespace: Matches what a branded-domain customer already believes, and turns namespace scarcity into a shared-domain question only.
• RejectedGlobal namespace: Simpler index, unsellable product: a customer on their own domain cannot be told their alias is taken by a stranger.
• RejectedPer-tenant namespace with domains as a display concern: Breaks as soon as one tenant has two domains and wants the same alias on both — routine for a company running regional sites.

Consequences

What it buys

• Branded domains are genuinely first-class rather than a premium veneer over a shared namespace.
• Partitioning by domain keeps each customer's claims and reads local, which also bounds the blast radius of a hot domain.
• Namespace policy can differ between the shared domain and customer domains, which is where the real difference in risk is.

What it costs

• The reservation index is larger and its key is compound, which every component must handle consistently.
• Cache keys, metrics and quotas all carry the domain, so a bug that drops it becomes a cross-tenant defect rather than a miss.
• Domain deletion has to be handled explicitly: its codes retire with it and cannot be freed.

Choose differently when

A global namespace is right for a single-domain product — a social network's own link wrapper, where there is exactly one host and the operator owns every alias.

Why it holds up over time

Compound keys are hard to add later and easy to keep. A platform that starts global and grows branded domains has to migrate its uniqueness authority under live traffic, which is the kind of migration that produces exactly the duplicate-ownership defect ADR-05 exists to prevent.

Does the lookup run at the edge against a replicated dataset, or in a regional service the edge forwards to?

Context

The fastest design puts the whole link table at every PoP: no origin hop, uniform tail latency, and revocation as a data push. Twelve billion records at roughly 1 KB is around 12 TB, which is not a PoP-resident dataset, so in practice this means a hot subset at the edge — and that needs a programmable edge with a replicated key-value store. Azure does not offer one for general-purpose use: Front Door runs rules and caching, not arbitrary code against a replicated store. The honest options are therefore an edge response cache in front of regional resolvers, or origin-only resolution with CDN caching of the redirects themselves, which is cheapest and hardest to revoke.

Decision

Resolution runs in twelve stateless read regions. Front Door terminates TLS at the nearest PoP, applies WAF and bot rules, serves the 30-second response cache, and forwards a miss over Private Link to the nearest regional origin group. Each resolver walks an in-process LRU, a regional Redis hot set and an in-region Cosmos replica. Region count and placement are sized to hold the 40 ms p99 for the assumed traffic distribution, and are expected to change with real geography.

How it is realised on Google Cloud

Front Door Premium with latency-based origin selection across twelve Container Apps environments, each with a zone-redundant Azure Cache for Redis and an in-region Cosmos DB read replica. The 97% assumed edge hit rate means the regional tier is sized for the miss traffic, not the full rate — which is what makes twelve regions affordable.

Options weighed

• ChosenEdge response cache plus regional resolvers: Uses what the platform actually offers, keeps the lookup in one place that can be reasoned about, and puts the cache where the traffic is. Costs a PoP-to-region hop on every miss.
• RejectedFull link table replicated to every edge location: Fastest and uniform, and a 12 TB distribution and consistency problem of its own. Not available on this platform in any case.
• DeferredHot subset in a programmable edge KV store: The right answer the moment the platform offers a replicated edge store at a sane price, and the first place the architecture should move. Nothing above the read path needs to change when it does.
• RejectedOrigin-only with long-lived CDN caching of redirects: Cheapest per redirect and incompatible with a 60-second revocation bound: the cache becomes the authority and cannot be corrected quickly.

Consequences

What it buys

• One lookup implementation, in one kind of place, with one set of metrics — rather than logic split between edge rules and a service.
• The regional tier is sized for misses, so the 97% hit rate converts directly into fleet size and cost.
• A read region is disposable: no unique state, so losing one is a capacity event.

What it costs

• A cold code pays the PoP-to-region hop, which is the click a customer tests with and complains about — hence pre-warming at creation.
• Twelve regions is twelve caches to warm and twelve deny-sets to keep fresh.
• The p99 depends on region placement assumptions that only real traffic can validate.

Choose differently when

Move the lookup to the edge as soon as a replicated edge key-value store is available and affordable, or if measured traffic turns out to be concentrated enough that the hot subset is small. Move it the other way — fewer, larger regions — if the miss rate is far below the assumption and placement is buying nothing.

Why it holds up over time

This is the decision in the package most tied to 2026 rather than to architecture, and it is designed to be replaced. What must survive the replacement is the boundary: whatever serves the lookup reads a projection and holds no write credential (ADR-01).

What status code does a redirect carry, and how long may a browser or intermediary remember it?

Context

A permanent redirect is the fastest thing the platform could possibly return: the browser never asks again, the platform never pays for the second click, and the destination inherits the link's search ranking — which is why SEO advice recommends it. It also makes the link uneditable and unkillable for every client that cached it, for as long as that client chooses to remember, which can be indefinitely. Since editing and killing are the product, and since clicks are a billing input, the fast answer is the wrong one. The real design space is the cache lifetime, and it is a single dial with safety on one side and cost on the other.

Decision

The redirect is a 302 with an explicit cache lifetime of 30 seconds at shared caches and no-store semantics for the terminal states. The 30 seconds is a design parameter, not a tuning knob: it is simultaneously the hot-key absorber, the dominant lever on cost per million redirects, and the outer bound on the revocation promise in ADR-02. Any proposal to change it must restate the revocation bound in the same sentence.

How it is realised on Google Cloud

Front Door caches the 302 for 30 seconds keyed on host plus code; the response carries `Cache-Control: max-age=30`. Blocked, expired and unknown responses are marked no-store so a terminal state is never held by a client. Clicks are still counted, because they are taken from the edge access log rather than from application code (ADR-10) — which is the only reason caching and analytics can coexist here.

Options weighed

• Chosen302 with a 30-second shared-cache lifetime: Keeps every link editable and killable within a stated bound, absorbs hot keys at the edge, and keeps counting exact because the count comes from the log.
• Rejected301 permanent redirect: Fastest and cheapest, and it permanently forfeits both revocation and per-click counting for cached clients. A link platform that cannot kill a link is not a link platform.
• Rejected302 with no caching at all: Tightest possible revocation and the loss of the mechanism that absorbs a viral code. Every click becomes an origin request at 150,000 per second.
• Right elsewhere301 for links the customer marks permanent: Defensible for a pure site-migration tool, where SEO transfer is the product and nobody will ever repoint the link. It does not belong in a platform whose value is that the destination can change.

Consequences

What it buys

• Every link stays editable and killable within a published bound, for every client.
• The edge cache absorbs hot keys and carries the assumed 97% of traffic, which is what makes the cost target reachable.
• Terminal states are never cached, so a blocked or expired link cannot be resurrected by a stale client.

What it costs

• Every 30 seconds, a popular code costs an origin resolution — the price of remaining changeable.
• No SEO ranking transfer, which has to be explained to customers who have read otherwise and will ask for a 301.
• One number now carries three concerns at once, so it can only be changed by someone who understands all three.

Choose differently when

A permanent redirect is correct when the mapping genuinely cannot change and nobody needs per-click data — a retired domain's canonical move, or a published DOI-style identifier with a permanence policy.

Why it holds up over time

Status codes and cache directives are the most stable technology in the design; HTTP semantics have outlived every platform they ran on. The pressure on this decision will come from cost reviews looking at the cheapest line on the bill, which is why the 30 seconds is documented as three coupled promises rather than as a cache setting.

What is the partition key of the link table: the tenant, or the code itself?

Context

Partitioning by tenant is the instinct of anyone who has built a multi-tenant system, and it makes tenant-scoped operations — list my links, export my campaign, delete my account — cheap. It also guarantees a hot partition, because tenants are not uniform: an assumed p99 tenant holds two million links, and the largest holds far more, while the redirect path reads by code and never by tenant. The read path's requirement and the management path's requirement point in opposite directions, and the read path outnumbers the other by 500:1.

Decision

The link table is keyed and partitioned on `(domain, code)`, so a point read by code hits exactly one partition and the distribution follows the hash rather than the customer. Tenant-scoped listing and search are served by a separate index built from the same change feed. Redirect-path cost and latency are never a function of how many links a tenant owns.

How it is realised on Google Cloud

Cosmos DB containers partitioned on domain with code as the row key; the by-tenant index is a separate container maintained by a change-feed consumer. A tenant with two million links therefore spreads across many physical partitions and cannot become a hot one.

Options weighed

• ChosenPartition by code within domain: Makes the hot path a single-partition point read and the distribution independent of tenant size. Costs a second index for listing.
• RejectedPartition by tenant: Cheap listing, guaranteed hot partitions, and a redirect latency that varies with which customer owns the code.
• RejectedPartition by tenant with a global secondary index by code: Puts an index lookup on the 150,000-per-second path to avoid one on the 14-per-second path.

Consequences

What it buys

• Redirect cost and latency are independent of tenant size, so onboarding a very large customer is not a read-path event.
• Hot partitions can only come from genuinely hot codes, which the caches are designed to absorb.
• The write path spreads naturally across partitions during a bulk import.

What it costs

• A second index to build, maintain and reconcile, with its own lag.
• Tenant-scoped deletion is a fan-out rather than a partition drop.
• Per-tenant RU accounting is derived rather than physical, which makes cost attribution a calculation.

Choose differently when

Partition by tenant when the dominant access pattern is tenant-scoped — an analytics warehouse, a per-customer export service — or when tenants are small and uniform enough that no partition can get hot.

Why it holds up over time

Partition keys are the hardest thing in a data platform to change later, because changing one is a full migration under live traffic. Choosing it for the dominant read pattern rather than the convenient administrative one is a decision that pays for a decade.

What records a click: the resolver that served it, or the edge that logged it?

Context

Once the redirect is cached for 30 seconds (ADR-08), the resolver simply does not see most clicks — an assumed 97% of them never reach application code. Counting in the resolver would therefore make the click count a function of the cache hit rate, which is both wrong and invisible: the dashboard would look healthy and the numbers customers are billed on would silently drop as caching improved. The alternative is to treat the edge's own request log as the source of the count, which also removes the last reason for the redirect path to write anything.

Decision

One click event per redirect served is derived from the edge access log, emitted after the response has left the PoP, durably buffered before processing. The resolver's own log is a second, smaller stream used for cache-miss analysis and never for counting — one authority per number. A failure anywhere in the click path can never surface as a failed or slowed redirect.

How it is realised on Google Cloud

Front Door diagnostic logs stream to Event Hubs with seven-day retention as the durable buffer, giving an assumed 30-second RPO on click data. Processing classifies traffic, enriches, drops identifiers and appends to Azure Data Explorer. Daily reconciliation compares landed events against the edge's own request counters within ±0.5%.

Options weighed

• ChosenCount from the edge access log: The only option compatible with caching the redirect. It also makes the redirect path genuinely write-free, which is the security property in ADR-01.
• RejectedCount in the resolver: Makes the count a function of the cache hit rate, and the error is invisible and moves in the direction that looks like success.
• RejectedCount in the resolver and disable caching: Exact counting at 150,000 origin requests per second, and the loss of the mechanism that absorbs a viral code.
• RejectedCount client-side with a beacon: A redirect has no page to run script on, and a platform that inserts an interstitial to count clicks has changed the product to suit its telemetry.

Consequences

What it buys

• Caching and accurate counting stop being in conflict, which is what makes the 30-second TTL affordable.
• The redirect path holds no write credential at all (ADR-01), because nothing on it needs one.
• An analytics outage is invisible to clickers and bounded by the buffer's retention rather than by anyone's reaction time.

What it costs

• The count depends on the edge log being complete and timely; a sampled or truncated log is a billing dispute rather than a monitoring gap.
• Click detail is limited to what the edge sees, so anything richer requires an enrichment step rather than an application field.
• Two log streams to keep straight, with a standing rule about which one counts.

Choose differently when

Count in the application when responses are not cacheable and the application is on the path for every request anyway — a signed download URL issuer, an authenticated API. There, the application log is the edge log.

Why it holds up over time

This will still be the right answer on any edge platform that produces a request log, and it is the reason two other decisions hold. The fragile version — counting in application code — looks identical on a dashboard, which is precisely why it needs to be written down as a decision rather than left as an implementation detail.

Does the platform ship one event per click, or aggregate counters at the edge and ship rollups?

Context

Edge aggregation is dramatically cheaper: a counter per code per minute instead of 150,000 rows per second. It also forecloses every question nobody thought to ask at design time — the fraud investigation that needs individual events, the customer dispute that needs a timeline, the bot reclassification that needs to be replayed over history. Sampling above a per-code threshold bounds cost on viral links, which is exactly where the customer is watching most closely and least willing to accept an estimate. And click data is a billing input here, which raises the bar on what can be reconstructed later.

Decision

One event per click is shipped and retained at full fidelity for 90 days, rolled up into daily aggregates for 25 months and monthly for 5 years. Totals and breakdowns are exact; unique-visitor figures are estimates with a stated ≤ 2% relative error and are labelled as estimates everywhere they appear. Adaptive sampling above a per-code threshold is deferred to Phase 3 and, if enabled, must restate the accuracy contract rather than quietly degrading it.

How it is realised on Google Cloud

Event Hubs to Azure Data Explorer, with rollups as materialised views rather than a separate batch pipeline. Traffic class is stored on the raw event, so a reclassification is a replay over retained data rather than a request to re-collect it. Raw retention is capped at 90 days because it is the dominant analytics cost line.

Options weighed

• ChosenFull events for 90 days, then rollups: Keeps later questions answerable — fraud, disputes, reclassification — and caps the cost with retention rather than with fidelity.
• RejectedEdge-aggregated counters only: A fraction of the cost and no way to answer any question that was not anticipated, including the ones that arrive as legal requests.
• DeferredSampling above a per-code threshold from day one: The right lever if viral codes turn out to dominate cost, and the wrong default: it degrades accuracy exactly where customers are looking hardest.
• RejectedFull events retained indefinitely: Storage grows without bound for questions that are almost never asked beyond a quarter, and increases the privacy surface for no product gain.

Consequences

What it buys

• Fraud, dispute and reclassification questions remain answerable for a quarter without re-collecting anything.
• Exact and estimated figures are separated and labelled, so a customer is never told an estimate is a count.
• Rollups make the common query cheap while the raw data stays available.

What it costs

• Raw retention is the dominant analytics cost line and must be defended at every cost review.
• A 90-day cliff means an investigation that starts late has less to work with, which has to be stated rather than discovered.
• Full-fidelity events carry a privacy obligation, met by dropping identifiers at ingestion (ADR-12's realisation).

Choose differently when

Aggregate at the edge when click data is a reporting nicety rather than a billing input, and when nobody will ever need to reconstruct an individual request. An internal link service is exactly that case.

Why it holds up over time

The 90-day figure will move. What should not is the separation between exact and estimated numbers, and the rule that enabling sampling means publishing a new accuracy contract. Quiet accuracy degradation is how analytics platforms lose credibility permanently.

What does the platform do with the assumed 18% of traffic that is unfurlers, scanners and prefetchers?

Context

These clients are not attackers. A chat unfurler fetching a link so a user sees a preview, a mail provider scanning for malware, a security tool checking a destination — all of them are doing work the platform's customers actively want done. Blocking them breaks link previews everywhere, which customers experience as the platform being broken. But counting them as human clicks is worse in a subtler way: a campaign owner who sees three clicks before announcing anything concludes the platform is inventing numbers, and every figure loses credibility at once. The third failure mode is the dangerous one: classifying a genuine click as a bot discards it invisibly.

Decision

Bot traffic is classified at the edge, served normally, tagged on the click event, excluded from customer-facing counts and from tenant quotas, and retained in the raw data with its class. Classification tags and never blocks. Because the class is stored rather than applied as a filter at collection time, a reclassification can be replayed over retained history rather than requiring the data to be collected again.

How it is realised on Google Cloud

Front Door bot manager rules produce a classification that is carried into the access log and onto the click event. Customer-facing queries filter on traffic class; cost and billing reports carry the bot share explicitly, so a tenant whose links are hammered by scanners is visible rather than mysterious.

Options weighed

• ChosenClassify, serve, tag, exclude from counts: Keeps previews working, keeps customer numbers credible, and keeps the decision reversible because the class is data rather than a filter.
• RejectedBlock bots at the edge: Breaks the preview behaviour customers depend on, and produces support tickets that look like platform outages.
• RejectedCount everything as a click: Cheapest and destroys trust in every number the platform reports, starting with day-one campaign figures.
• RejectedDrop bot events at collection: Saves storage and makes a misclassification permanent: a genuine click discarded as a bot cannot be recovered.

Consequences

What it buys

• Link previews keep working, which is invisible when right and very visible when wrong.
• Customer-facing numbers survive contact with a launch day dominated by unfurlers.
• A classifier improvement can be applied retroactively, because the class is stored alongside the event.

What it costs

• Bot traffic is served and paid for — an assumed 18% of the redirect bill for traffic nobody is billed for.
• Two sets of numbers exist (with and without bots), and every report has to be explicit about which it shows.
• Classification accuracy becomes a product concern with its own false-positive cost.

Choose differently when

Blocking becomes correct when the traffic is genuinely abusive rather than functional — a scraper enumerating codes is handled by rate limiting in ADR-03's threat model, not by this decision.

Why it holds up over time

The specific classifier will be replaced repeatedly. What must survive is the separation of serving from counting, and the rule that classification is recorded rather than applied destructively. Systems that filter at collection time can never correct a classification error.

Is a destination checked once at creation, continuously, or not by the platform at all?

Context

A short link hides its destination — that is the product, and it is also why phishing campaigns prefer shorteners to bare URLs. A one-time check at creation catches the naive case and misses the standard technique entirely: register a clean page, get it approved, distribute the link widely, then change the page. The destination the platform approved and the destination the clicker reaches are separated by however long the campaign takes to spread. Meanwhile the platform's shared domain is a single shared reputation: once mail providers and browsers blocklist it, every legitimate tenant's links stop working, and recovery takes weeks the business does not have.

Decision

Every destination is screened against multiple reputation feeds before a code is issued, and re-screened periodically thereafter for as long as the link is live. A bad verdict at creation refuses the link; a bad verdict afterwards blocks it through the revocation channel with a platform interstitial. Bulk creation from new or unverified accounts is rate-limited and challenged. Every block and every reinstatement records the feed, the score, the reviewer and the time, retained two years, with an appeal path that runs the same code as the block.

How it is realised on Google Cloud

Azure Functions call three third-party reputation feeds synchronously at creation and on a scheduled fan-out afterwards, prioritised by live click rate so the links actually being clicked are re-screened most often. A block publishes to the revocation channel (ADR-02) so it is effective globally within 60 seconds. Evidence lands in the append-only store with an immutability policy.

Options weighed

• ChosenScreen at creation and re-screen periodically: Addresses the actual attack — approval followed by weaponisation — and makes the platform's response time a number rather than a hope.
• RejectedScreen at creation only: Catches the naive case and misses the standard one. It also gives a false sense of coverage, which is worse than none.
• RejectedScreen at click time: Strongest protection and incompatible with the read path: a synchronous third-party call would dominate the 40 ms budget and make redirects depend on a vendor's uptime.
• RejectedNo screening; respond to reports: Cheapest and ends with the shared domain blocklisted, which takes every legitimate tenant down with it.

Consequences

What it buys

• The platform's domain reputation is defended continuously rather than after an incident.
• Response time to a flipped verdict is bounded by the revocation promise, so it can be stated to a regulator or a customer.
• Every decision is evidenced, which makes an appeal a process rather than an argument.

What it costs

• Three feed subscriptions, a re-screening budget proportional to live links, and false positives that block legitimate customers.
• Creation latency includes a synchronous feed call, which is part of the 250 ms p99.
• A human review queue with a rota — a staffing commitment, not just a component.

Choose differently when

Skip screening only when destinations cannot be attacker-controlled — an internal shortener over an allow-listed set of hosts. As soon as a stranger can supply the URL, screening is a requirement.

Why it holds up over time

Feeds and scores will change completely; the shape will not. Screen before issuance, re-screen while live, block through the fast channel, keep the evidence. A platform that treats abuse as an operational afterthought rediscovers this list under pressure.

What does a code return when it is unknown, expired, deactivated or blocked — and whose page is it?

Context

One 404 for all four is the simplest thing to build and tells the clicker nothing, which means every dead link becomes a support ticket for the customer and a mystery for the person holding the poster. A fully tenant-branded page for all four keeps the customer's experience intact and lets a blocked link masquerade as a working one, which is exactly the outcome an abusive tenant wants. There is also a real tension with enumeration: distinguishing 'never existed' from 'expired' tells a scanner which codes have been used. And a blocked link raises the question of whose reputation is on the page — the platform is making an accusation, so it should be the one making it.

Decision

Four states, four distinct responses: unknown returns 404, expired and deactivated return 410 with a tenant-configurable page, and blocked returns a platform-owned interstitial that names the reason and offers an appeal route to the owner. None is cached. The destination is never taken from the request — only from a stored record — so the platform can never be turned into an open redirect. A blocked link is never a silent 404 and never a silent redirect.

How it is realised on Google Cloud

The resolver's terminal-state selection runs last in the pipeline (view 09) so state can never collapse into a generic error. Unknown codes are negatively cached briefly, which makes enumeration cheap to serve, and retired codes look identical to never-issued ones from outside.

Options weighed

• ChosenFour distinct states, platform interstitial for blocks: The clicker learns what happened, the owner learns why, and an accusation is made by the party making it.
• RejectedOne generic 404 for all four: Simplest, and converts every expiry and every block into a support conversation with no information in it.
• RejectedTenant-branded pages for all four including blocks: Lets a blocked link look alive and makes the platform's safety decision invisible to the person it protects.
• RejectedBlock by removing the record entirely: Destroys the evidence and the appeal path, and makes an accidental block unrecoverable.

Consequences

What it buys

• A dead link is self-diagnosable by both the clicker and the owner.
• Blocked links carry a warning rather than a shrug, which is the difference between protecting someone and confusing them.
• The open-redirect class of vulnerability is structurally excluded, not filtered.

What it costs

• Four responses to build, test and keep consistent across twelve regions.
• Distinguishing states leaks a little existence information, mitigated by unguessable codes and rate limiting rather than by ambiguity.
• The interstitial is a platform-branded page in the middle of a customer's campaign, which some customers will dislike.

Choose differently when

A single generic response is defensible for an internal service where every clicker can ask the owner directly. It is never defensible when the clicker is a stranger who has no way to find out what happened.

Why it holds up over time

Status-code semantics outlive platforms. The pressure here will come from customers wanting full branding on every state, and the answer must remain no for blocks specifically, because the whole value of the interstitial is that it is not the accused party's page.

Who owns verification, certificate issuance and renewal for 12,000 customer-owned domains?

Context

A branded domain is what an enterprise customer is actually buying: `go.acme.com` rather than a shared host nobody trusts. That makes their domain part of the platform's serving path, and its certificate part of the platform's availability. At 12,000 domains, renewal is not an administrative task — it is 12,000 independent expiry dates, each of which takes one customer's entire link estate down when it lapses. Leaving it to the customer means the platform's most valuable tier has the least reliable links, and the outage is discovered by the customer's own users. There is also a trust question at verification: serving a host the platform has not proven the customer controls is an open invitation to hijack somebody else's traffic.

Decision

The platform verifies domain ownership before serving a domain, provisions and auto-renews its certificate, and surfaces verification and renewal state to the customer before expiry becomes an outage. A branded domain carries the same latency and availability objectives as the shared domain; it is not a slower or less reliable path. Customer-supplied certificates remain available for enterprises that insist, with the renewal obligation explicitly transferred and alarmed.

How it is realised on Google Cloud

Azure DNS-based verification of a TXT or CNAME record, then Front Door managed certificates with automatic renewal, all domains served from the same anycast address set. Renewal state is a first-class field with alarms at 30, 14 and 7 days, and a certificate approaching expiry without renewal pages somebody rather than emailing the customer.

Options weighed

• ChosenPlatform-managed verification and certificates: Removes 12,000 expiry dates from customers who will not track them, and keeps the branded path as reliable as the shared one.
• RejectedCustomer-supplied certificates only: Cheaper and transfers an availability risk to the party least equipped to manage it, while the platform still gets the outage.
• RejectedServe branded domains on a separate, simpler path: Makes the premium tier the slower tier, which inverts the value proposition.
• RejectedSkip ownership verification for speed of onboarding: Lets a customer claim a host they do not control, which is traffic hijacking with the platform as the instrument.

Consequences

What it buys

• A customer's links do not stop working because somebody forgot a renewal.
• Branded and shared domains share one serving path, so there is one set of latency and availability numbers rather than two.
• Ownership verification closes a hijacking vector before the first request is served.

What it costs

• Certificate lifecycle at 12,000-domain scale is a subsystem with its own failure modes and its own on-call load.
• Onboarding is slower because verification is a prerequisite, which sales will push back on.
• Customer-supplied certificates remain a supported exception, which means two paths to keep working.

Choose differently when

Leave certificates to the customer when there are tens of domains and each has a named technical owner — a handful of enterprise integrations rather than a self-service tier.

Why it holds up over time

Automated issuance and renewal will get easier, and the obligation will not move. Whoever serves the host owns its availability, regardless of who owns the name, and a platform that pretends otherwise learns this from a customer's incident review.