URL Shortener & Link Management Service  ·  View 15 of 23  ·  Runtime

Critical Flow — Claiming a Code

The only strongly consistent operation in the architecture, and the one place the platform refuses to be helpful.

Editable source SVG draw.io All views
Campaign owner Link API Screening Reservation index Link table Projection publisher Hot set 1. POST /links alias=spring, domain=go.acme.com 2. idempotency key seen in last 24h? 3. validate scheme, length, host; check reserved list 4. destination reputation 5. clean (blocked verdicts refuse creation) 6. conditional create (domain, code) — If-None-Match 7. 409 if claimed or retired 8. 201 claimed — exactly one writer wins 9. write link record, RPO 0 10. committed in the write region 11. 201 with the short link (p99 ≤ 250 ms) 12. change feed 13. pre-warm in the creating region ≤ 1 s 14. pre-warm elsewhere ≤ 10 s p99 Critical Flow — Claiming a Code Nobody Else Can Have The conflict is returned, never worked around: the platform will not substitute a generated code for an alias a customer asked for. Reservation is the only strongly consistent step in the whole architecture. v 1.0 · owner Platform Architecture · date 2026-09

Why a conditional create

  • Two clients asking for the same alias in the same millisecond must produce exactly one winner. A read-then-write cannot guarantee that; a conditional create against a single write region can (ADR-05).
  • The loser receives a 409 naming the collision. The platform never substitutes a generated code for a requested alias — that link would be printed and then be wrong.
  • The reservation is checked against retired codes too, so a code that once existed can never be claimed again (ADR-04).

The order of operations

  • Idempotency check → validation → screening → claim → write → respond. Screening precedes the claim so a blocked destination never consumes a code.
  • Creation p99 ≤ 250 ms including the claim; bulk import of 10,000 links p99 ≤ 60 s as an asynchronous job.
  • Pre-warming starts from the change feed immediately: resolvable in the creating region within 1 s p99, globally within 10 s p99.

Risks

  • A single write region means creation is unavailable during a regional failover (RTO ≤ 5 min). The requirement accepts refusing creation over risking two winners.
  • Random 7-character codes need a collision retry as the table fills. At 12 billion links in a 3.5 × 10¹² space the retry rate is negligible; at 500 billion it is not, and lengthening is the planned answer (ADR-03).
◀  Critical Flow — One Click, Resolved All views Critical Flow — Stopping a Link in Under a Minute  ▶
Solution Architecture v1.0 · Microsoft Azure · Platform Architecture · 2026-09 · 23 views · 16 architecture decision records15-creation-and-alias-reservation