Skip to main content
zolotoy.dev

Service case study

URL Shortener

A redirect service engineered around its hot path: PostgreSQL storage, Redis cache-aside with bounded fallback, per-instance singleflight and reproducible latency benchmarks.

PlannedBackend runtime: No deployed runtime — specification stageDemo data source: Mock

Scope
A backend engineering case study of a redirect hot path, caching strategy and bounded analytics for the zolotoy.dev demo environment.
Not in scope
  • Not a Bitly clone.
  • Not a sharded analytics platform.
  • Not a general-purpose link management product.
Engineering focus
Redis cache-aside, singleflight, hot path, bounded analytics.

Engineering Focus

Redis cache-aside, singleflight, hot path, bounded analytics.

Current Implementation

Backend implementation is not present yet. The demo module renders the planned flows with deterministic mock data; the content below is the proposed boundary, not a shipped system.

  • Current

    No backend implementation exists yet: the demo renders deterministic MSW scenarios of link management and analytics.

    • URL shortener specification (target contract)docs/backend-specs/04_url_shortener.mdzolotoy-dev-frontend (this repository)reviewed 2026-09-17

Target Architecture

  • Target

    A redirect hot path that serves from Redis cache-aside, falls back to PostgreSQL with bounded concurrency, and returns 404/410 according to link state.

    • URL shortener specification (target contract)docs/backend-specs/04_url_shortener.mdzolotoy-dev-frontend (this repository)reviewed 2026-09-17
  • Target

    Cache invalidation on link mutation, negative caching for missing keys, and TTL bounds that cap staleness after invalidation races.

    • URL shortener specification (target contract)docs/backend-specs/04_url_shortener.mdzolotoy-dev-frontend (this repository)reviewed 2026-09-17
  • Target

    Per-instance singleflight collapses concurrent misses for the same key into one database read; it does not coordinate across service instances.

    • URL shortener specification (target contract)docs/backend-specs/04_url_shortener.mdzolotoy-dev-frontend (this repository)reviewed 2026-09-17
  • Target

    Reproducible latency/throughput benchmarks with published methodology — a measurement, not a marketing number.

    • URL shortener specification (target contract)docs/backend-specs/04_url_shortener.mdzolotoy-dev-frontend (this repository)reviewed 2026-09-17
    • Shortener performance milestone: measurements and bounded analytics (future)docs/roadmap.mdzolotoy-dev-backende36b1025reviewed 2026-09-17

Architecture / Core Flow

Target
  • Visitor browserGET /{alias} redirect
  • Shortener serviceHot path: cache → fallback → redirect
  • RedisCache-aside + negative caching
  • PostgreSQLLinks, state, bounded analytics
  • GET alias: browser → svc
  • cache-aside lookup: svc → redis (planned)
  • bounded fallback + singleflight: svc → db (planned)
Target redirect hot path with cache-aside and bounded fallback.

Engineering Decisions

Negative caching bounds the missing-key stampede

Target design: repeated lookups of a nonexistent alias cache a short-lived negative result so attackers or hot dead links cannot bypass the cache to the database.

Singleflight is per-instance by design

Target design: in-flight request coalescing removes same-instance duplicate misses. Cross-instance coordination would add a distributed lock to a hot path — rejected; bounded fallback concurrency does that job instead.

Analytics are best-effort and bounded

Target design: click counts are incremented asynchronously and may lose data under failure; correctness of the redirect never depends on analytics.

Reliability / Failure Modes

Unique-key collision
Generated alias collides on insert: retry with a new key under a uniqueness constraint; user-chosen aliases surface a 409-style conflict instead of overwriting.
Redis outage and bounded database fallback
Redis unavailable: redirects continue through PostgreSQL with concurrency limits (and probably degraded latency) instead of failing closed or stampeding unprotected.
Invalidation/refill races
A read refills a stale value after an invalidation delete; TTL bounds how long the stale entry can mislead. Invalidation is not presented as race-free.
Expired/disabled link policy
Expired links answer 410 Gone, disabled or deleted links answer 404 — the distinction is part of the API contract, not a UI detail.
Best-effort analytics loss
Under load or failure, analytics increments can be dropped; dashboards label the numbers as bounded estimates rather than exact counts.

Evidence

  • URL shortener specification (target contract)docs/backend-specs/04_url_shortener.mdzolotoy-dev-frontend (this repository)reviewed 2026-09-17
  • Shortener performance milestone: measurements and bounded analytics (future)docs/roadmap.mdzolotoy-dev-backende36b1025reviewed 2026-09-17

Interactive Demo

Next Milestone: Shortener performance

Database/redirect hot path, Redis fallback, per-instance singleflight, reproducible measurements and bounded analytics.

Acceptance evidence (planned):

  • Benchmark methodology and artifacts published
  • Redis outage path bounded and measured