Architecture Overview

Alokai CMS is a full-stack application running entirely on Cloudflare’s edge infrastructure. It combines a Hono HTTP server (Worker) with a React SPA (served as static assets from the same Worker).

High-level architecture

                    Browser
                       │
              ┌────────▼────────┐
              │  Cloudflare CDN  │
              └────────┬────────┘
                       │
              ┌────────▼────────────────────────┐
              │     Cloudflare Worker (Hono)     │
              │                                  │
              │  ┌──────────┐  ┌──────────────┐  │
              │  │ /api/*   │  │ Static Assets│  │
              │  │ REST API │  │ (React SPA)  │  │
              │  └─────┬────┘  └──────────────┘  │
              └────────┼────────────────────────┘
                       │
          ┌────────────┼────────────┐
          │            │            │
     ┌────▼───┐  ┌─────▼──┐  ┌─────▼──┐
     │   D1   │  │   R2   │  │   KV   │
     │ SQLite │  │ Assets │  │ Cache  │
     └────────┘  └────────┘  └────────┘

Packages

Package	Version	Purpose
Hono	4.7.x	HTTP framework for the Worker
React	19	Frontend UI
React Router	7.x	Client-side routing (SPA)
Vite	6.x	Frontend build tool
Tailwind CSS	4.x	Styling
Zustand	5.x	Frontend state management
Tiptap	2.x	Rich text editor
@dnd-kit	—	Drag-and-drop for component reordering
Zod	3.x	Schema validation
@hono/zod-openapi	0.19.x	OpenAPI route definitions

Request flow

Management API (authenticated)

Request
  → Hono router matches /api/*
  → Auth middleware (JWT session or API key)
  → Space/Env context middleware (reads X-Alokai CMS-* headers)
  → Route handler
  → D1 query
  → Response

Delivery API (public, read-heavy)

Request GET /api/v1/pages/by-path/{path}
  → Check KV cache
  → Cache HIT → return cached JSON immediately
  → Cache MISS → query D1 → write to KV → return JSON

Static assets (React SPA)

Request for non-/api/* path
  → Cloudflare Assets binding serves dist/
  → SPA index.html for any unmatched path (single-page app mode)

Key design decisions

Cloudflare-only — No external databases or services. D1, R2, and KV are all native Cloudflare products, keeping latency low and ops complexity minimal.

Single Worker — The API and the static UI are served from the same Worker. No separate deployment for the frontend.

KV for delivery caching — Published pages are materialized into KV on publish. Reads are O(1) key lookups with global replication.

Immutable versions — Page versions are append-only. Restoring a version creates a new version, never overwrites history.