Tinycrate

Tinycrate is a multi-tenant e-commerce platform that runs entirely on Cloudflare Workers and D1. Each merchant gets a storefront on a subdomain (or a custom domain), an admin interface, Stripe-powered checkout with subscriptions and refunds, UPS shipping labels, and passwordless magic-link authentication. A native macOS merchant app talks to the same backend through a versioned REST API described by a single OpenAPI contract (openapi.yaml).

Architecture

One Worker (src/index.js, built on Hono) routes by hostname:

• tinycrate.net — landing page and waitlist (src/routes/home.js)
• admin.tinycrate.net — merchant admin interface (src/routes/admin/)
• api.tinycrate.net — Stripe webhooks, storefront APIs, and the versioned /v1 REST API (src/routes/api.js, src/routes/api/v1/)
• <shop>.tinycrate.net and custom domains — tenant storefronts (src/routes/tenant.js)

Layout of src/

• routes/ — HTTP handlers, grouped by host. routes/admin/orders/ splits the order workflows (detail, fulfillments, refunds, receipts, shipping labels, subscriptions). routes/api/v1/ is the bearer-token API consumed by the macOS app: reads, writes, order operations, media ingest, pagination, and auth middleware.
• services/ — business logic with no HTTP concerns: order, refund, fulfillment, inventory, and subscription services; Stripe Connect; UPS shipping (rates, labels, international, billing safeguards); Cloudflare API client for custom-domain provisioning; event logging.
• middleware/ — CORS (separate policies per host class), CSRF, customer auth, order validation.
• views/ — server-rendered HTML for the admin, tenant storefronts, customer subscription pages, and transactional emails. HTMX drives interactivity; there is no client-side framework.
• utils/ — shared helpers: currency, dates, HTML escaping, markdown, encryption at rest, refund math, inventory claims, magic links, Stripe subscription sync.

Data and infrastructure

• D1 (SQLite) — the primary database. Schema in schema.sql, incremental migrations in migrations/ and migrations-wrangler/.
• R2 — media storage (SITES bucket).
• KV — revocable merchant sessions (SESSIONS namespace).
• Email — Cloudflare send_email binding for magic links, receipts, and subscription notifications.
• Stripe — checkout, webhooks (platform and Connect), recurring subscriptions, and refunds. Merchants onboard through Stripe Connect.
• UPS — shipping rates and label generation, with billing safeguards and international shipment support.

Payments

Checkout, subscription, and refund flows are driven by Stripe webhooks handled on the API host. Inventory deduction is exactly-once (claim and release, so webhook retries no-op), and refund IDs are deterministic so concurrent submissions collide into an atomic no-op.

Authentication

Passwordless magic links for merchants and customers. Merchant sessions are opaque revocable tokens in KV; the /v1 API uses bearer tokens.

Setup

1. Install dependencies: npm install
2. Copy .dev.vars.example to .dev.vars and fill in your Stripe, UPS, and Cloudflare values.
3. Replace the REPLACE_ME placeholders in wrangler.toml with your own Cloudflare account, D1 database, and KV namespace IDs.
4. Set up the database: bash scripts/setup-db.sh (or apply schema.sql and a seed file with wrangler d1 execute).
5. Run locally: npm run dev (starts wrangler dev plus a Stripe webhook listener).
6. Deploy: npm run deploy. Production secrets are set with wrangler secret put (see scripts/setup-secrets.sh).

Tests: npm test. Type checking: npm run typecheck.

Further documentation lives in docs/.