CDN, Edge Caching, and Anycast

Edge vs origin

A CDN (Content Delivery Network) is a geographically distributed cache that stores copies of content close to users. Instead of every receipt PDF request traveling from Singapore to Virginia, the CDN serves it from a PoP (Point of Presence) in Singapore — cutting latency from 200ms to 15ms and reducing origin load by 90%+.

ShardPay's transfer APIs (POST /v1/transfers) always hit origin — they are dynamic, consistency-sensitive, and non-cacheable. Receipt PDFs, merchant logos, and compliance documents are static or semi-static, perfect for edge caching with appropriate TTL and cache keys.

What to cache and what not to cache

The rule is simple: cache immutable or eventually-consistent reads; never cache writes or strongly-consistent reads. ShardPay's caching policy:

Caching a balance lookup would serve stale data — a user sees $100 after transferring $50. Caching a receipt PDF is safe: the PDF content is immutable once generated.

Walkthrough: receipt download during peak

A merchant downloads 10,000 receipt PDFs for tax filing. Without CDN, 10,000 requests hit ShardPay's origin API, adding load during an already-busy period. With CDN: the first request per unique PDF fetches from origin and caches at the edge PoP. The next 9,999 requests for the same PDFs serve from cache at 15ms instead of 200ms. Origin load: ~500 unique PDFs (not 10,000).

// ShardPay receipt service — cache-friendly response headers
@GetMapping("/v1/receipts/{transferId}")
public ResponseEntity<byte[]> getReceipt(@PathVariable String transferId,
                                          @RequestHeader("Authorization") String token) {
    Receipt receipt = receiptService.generateIfAbsent(transferId);  // immutable once created

    return ResponseEntity.ok()
        .header("Cache-Control", "public, max-age=300, stale-while-revalidate=60")
        .header("ETag", receipt.etag())
        .header("Vary", "Authorization")  // different merchants see different receipts
        .contentType(MediaType.APPLICATION_PDF)
        .body(receipt.pdfBytes());
}

Cache invalidation strategies

Cache invalidation is notoriously hard. ShardPay uses three strategies depending on content type:

TTL-based expiry — simplest; let the cache expire after max-age. Works for logos and compliance docs that change rarely. A logo update takes up to 24 hours to propagate — acceptable for non-critical assets.

Active purging — call the CDN's purge API when content changes. ShardPay purges a merchant's logo cache immediately after upload, so the new logo appears within 30 seconds globally.

Versioned URLs — include a content hash or version in the URL (/logos/merchant-42/v3.png). New version = new URL = automatic cache miss. ShardPay uses versioned URLs for API JSON schemas so clients always fetch the latest contract.

CDN for dynamic content

Some "dynamic" content benefits from edge caching with short TTL. ShardPay's merchant dashboard status page (GET /v1/merchants/{id}/status) returns semi-static data (account verified, limits configured) that changes at most once per hour. A 60-second CDN TTL reduces origin load by 80% without meaningful staleness.

True dynamic content — transfer processing, balance queries, fraud checks — must never be CDN-cached. The cost of serving a stale balance far exceeds the latency savings. When in doubt, mark it Cache-Control: private, no-store.