Skip to content

Architecture

Jump to bottom
Kritarth-Dandapat edited this page Jul 19, 2026 · 1 revision

Architecture

 dkraft-publish (CLI)              Cloudflare Worker                 Workers KV
 ────────────────────              ──────────────────                 ─────────
 reads local .html file    POST    POST /upload                 put   HTML_DRAFTS
 sends {html, pin}  ─────────────▶ handleUpload()          ────────▶  key: 8-char id
                                   verifies Bearer token             value: {html, pin, createdAt}
                    ◀───────────── { url: /d/<id> }

 Browser                           GET /d/<id>
 visits published URL ───────────▶ resolveAndRenderDraft()   get    HTML_DRAFTS
                                   checks pin (if set)   ◀────────── {html, pin, createdAt}
                    ◀───────────── raw draft.html, or lock screen

Components

src/index.js — the Worker

Single fetch handler, two routes:

  • POST /upload — handleUpload(). Requires Authorization: Bearer <SECRET_API_KEY> (constant-time compared via timingSafeEqual). Body is { html: string, pin?: string }. Generates an 8-hex-char ID (crypto.randomUUID() truncated, retried up to 5x on collision), stores {html, pin, createdAt} as a JSON string in HTML_DRAFTS KV, returns { url }.
  • GET /d/:id — resolveAndRenderDraft(). Looks up the ID in KV, parses the JSON. If pin was set at upload time, compares it (constant-time) against the ?key= query param; on mismatch, serves an inline lock-screen HTML page. On match, serves draft.html directly as text/html.

No routing framework, no bundler — it's one file, deployed as-is by wrangler deploy.

Workers KV — HTML_DRAFTS

Key-value store, one namespace. Key = short draft ID, value = JSON string { html, pin, createdAt }. No expiry is currently set on writes (see Security) and no other tables/state exist.

cli/index.js — dkraft-publish

Commander-based CLI. Reads DK_PUBLISH_KEY / DK_PUBLISH_URL from the environment, reads the target file as UTF-8, POSTs it to <DK_PUBLISH_URL>/upload with the bearer token, prints the returned URL.

.claude/skills/freeflow-publish/SKILL.md

Plain-language runbook for coding agents (Claude Code or otherwise) describing how to invoke the CLI, what credentials it needs, and how to interpret its error output. Not code — a skill file any agent can read as instructions.

Data flow summary

  1. Agent/user generates a self-contained HTML file locally.
  2. dkraft-publish uploads it to the Worker over HTTPS with a bearer token.
  3. Worker mints a short ID, writes the draft to KV.
  4. Worker returns a public URL (https://<domain>/d/<id>).
  5. Anyone with that URL (and the PIN, if set) can view the rendered HTML — served byte-for-byte, no transformation.

See Security for what this trust model does not currently protect against.

Clone this wiki locally