Use this architecture map to locate a request, choose the right trust boundary, or follow a change into storage. Energon runs as one Cloudflare Worker with three request surfaces because humans, agents, and public-link readers carry different authority. One Worker coordinates those surfaces against the same D1 catalog and R2 object store.

Architecture

System map

Three surfaces, one domain model

The hub origin (PUBLIC_ORIGIN) serves the hub and /v1, but those paths do not share authentication. Cloudflare Access establishes a production human identity for setup, tokens, and account operations. /v1 bypasses Access and calls the same site and file domain functions with an actor created from an instance-issued API token. The content origin (CONTENT_ORIGIN) is a distinct production hostname that serves only /{handle}/s/... and /{handle}/f/... content paths.

The router handles health, runtime docs, and host separation before normal schema-backed dispatch. Most other requests call ensureSchema first. Supported older databases can gain additive columns before indexes are created. Append-only migrations still carry deployment history, and operators must apply them before deploying the Worker.

You can observe the public edge without a credential:

ENERGON_ORIGIN="https://energon.your-company.example"
curl -fsS "$ENERGON_ORIGIN/v1/health"
curl -fsS "$ENERGON_ORIGIN/v1/help" | jq '{hub, content_origin, identity, retention, limits}'

D1 coordinates; R2 holds bytes

D1 stores users, token hashes, object identities, ownership and write policy, expiry, share-password hashes, mutation claims, and the platform quota ledger. R2 stores the actual site and loose-file bytes. Cloudflare does not provide one transaction across both services, so domain mutations use conditional D1 commits plus storage snapshots or staged backups. A failure restores the prior state when possible; a failed compensation becomes an explicit recovery error.

Public responses without a password may be cached at the edge. Their shared-cache lifetime is bounded by remaining content retention, and successful writes, policy changes, deletes, and expiry purges invalidate the object’s path prefix. Password-protected responses and rendered Markdown are private and not stored in the shared cache.

Expiry has two enforcement paths

The scheduled handler bootstraps schema and sweeps bounded batches of expired sites and loose files. Reads and writes also check expiry and return 410 Gone immediately, scheduling targeted cleanup when appropriate. A D1 purge claim prevents cleanup from racing a TTL reset or replacement; the purge removes R2 bytes and catalog rows, invalidates cache, and releases quota.

Follow one object through these components in Data flow. Operators should pair this map with Deploy an Energon host and Set safe instance boundaries; contributors can go deeper in Architecture and integrity.