Caching Strategy

Alokai CMS uses Cloudflare KV as a materialized cache layer for the delivery API. Published pages are written to KV at publish time so reads never hit D1.

Cache keys

Pattern	Used for
delivery:path:{spaceId}:{envId}:{path}:{locale}	Path-based delivery lookups
delivery:id:{spaceId}:{envId}:{pageId}:{locale}	ID-based delivery lookups
preview:{token}	Preview token validation

Write-on-publish

When a page is published:

1. D1 is updated (status = 'published', published_version = N)
2. The full page JSON is serialized and written to both KV keys (path and ID)

This is a synchronous write — the publish API response returns only after KV is written.

Read-through

On a delivery API request:

KV.get(key)
  → hit:  return cached value immediately
  → miss: query D1, serialize, KV.put(key), return value

KV reads are served from Cloudflare’s global edge with typical p99 latencies under 5ms.

Cache invalidation

KV keys are deleted when:

• A page is unpublished — delete both path and ID keys
• A page is re-published (new version) — overwrite both keys with new content

There is no TTL on delivery cache keys — they are invalidated explicitly on mutation.

Preview tokens

Preview tokens are stored in KV with a TTL (default: 3600 seconds):

KV.put(`preview:${token}`, JSON.stringify(pageId), { expirationTtl: 3600 })

They expire automatically. No explicit cleanup needed except for early revocation via DELETE /api/preview/:token.

Scheduled publishing

The cron handler (runs every 5 minutes) queries D1 for pages with status = 'scheduled' and scheduled_at <= now. For each:

1. Updates status = 'published' in D1
2. Writes the page data to KV

This means scheduled pages can become live up to 5 minutes after their scheduled time.