​
Architecture overview

KV Cache Store is made of three components: the kvcdn CLI, the portal, and the Worker.

​
Components

​
kvcdn CLI

An open-source Rust command-line tool for x86-64 Linux that customers run locally. It supports:
  • login — open the dashboard in the default browser.
  • api-key — set, verify, or clear the API key used for API requests.
  • verify — verify a local .kv artifact against a context file.
  • quant — quantize a .kv artifact to a lower-precision dtype.
  • benchmark — measure throughput or memory of a .kv artifact.
  • plot — generate visualizations from benchmark output.
  • upload — send a .kv artifact to the hosted service via a presigned URL.
  • list — query the hosted API for artifacts in the active project.
The CLI authenticates with a project-scoped API key passed in KVCDN_API_KEY. It talks to the portal at KVCDN_API_URL (default https://api.kvcachestore.com).

​
Portal

The Rust web service at api.kvcachestore.com (also kvcachestore.com) that handles:
  • OIDC sign-in via Pocket-ID (/auth/*).
  • Customer, organization, and project management.
  • API key creation and verification (/api/v1/api-keys).
  • Artifact metadata, presigned upload URLs, and visibility (/api/v1/artifacts).
  • Billing and Stripe webhooks (/api/v1/billing).
  • Static frontend assets served from frontend/dist/ (the frontend seam).
The portal is the source of truth for artifact metadata, visibility, and access control.

​
Worker

A Cloudflare Worker that runs at the edge and serves artifacts from R2 object storage. It exposes:
  • GET /v1/artifacts/:id — downloads a public artifact.
  • POST /v1/artifacts/:id/visibility — updates object metadata visibility.
  • POST /v1/artifacts/upload-url — alternative upload-url path (not used by the current CLI).
Public downloads are enforced by the Worker’s object metadata: private artifacts return 403 Forbidden.

​
Upload flow

┌─────────────┐     POST /api/v1/artifacts/upload-url     ┌─────────┐
│   kvcdn     │ ─────────────────────────────────────────>│ Portal  │
│   CLI       │                                           │         │
│             │ <─────────────────────────────────────────│         │
└─────────────┘         { artifact_id, url, method }      └─────────┘
        │                                                        │
        │ PUT presigned URL                                       │
        ▼                                                        ▼
┌───────────────────────────────────────────────────────────────────┐
│                         R2 object storage                           │
└───────────────────────────────────────────────────────────────────┘
        │                                                        │
        │ POST /api/v1/artifacts/{id}/confirm-upload              │
        ▼                                                        ▼
   ┌─────────┐                                            ┌─────────┐
   │  kvcdn  │                                            │ Portal  │
   └─────────┘                                            └─────────┘
  1. The CLI infers artifact metadata from the .kv filename and the user-supplied --name.
  2. The CLI calls POST /api/v1/artifacts/upload-url on the portal with the metadata, size, and SHA-256 checksum.
  3. The portal checks the organization’s artifact quota, creates a pending artifact record, and returns a presigned URL.
  4. The CLI PUTs the file bytes directly to the presigned URL.
  5. The CLI calls POST /api/v1/artifacts/{id}/confirm-upload to finalize the upload.

​
Download flow

  1. A customer requests an artifact through the dashboard or the portal’s GET /api/v1/artifacts/{id} endpoint.
  2. The portal verifies the customer has access, then returns a presigned download URL.
  3. For public artifacts, the Worker can also serve the object directly from R2 using the artifact ID.

​
Frontend seam

The portal serves the frontend website from frontend/dist/. The frontend consumes only the portal’s /api/v1/* JSON API. This boundary keeps the website separate from the Rust service while both run on the same public URL.

​
Environment boundaries

  • CLI ↔ Portal: KVCDN_API_URL + KVCDN_API_KEY.
  • Portal ↔ Postgres: DATABASE_URL.
  • Portal ↔ R2: R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET_NAME.
  • Portal ↔ Worker: The Worker calls the portal’s /api/v1/api-keys/verify endpoint to authenticate requests.
  • Portal ↔ Stripe: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET.

​
Next steps