Architectural Decisions

Purpose: keep a concise durable rationale log for technical decisions, tradeoffs, and reusable lessons that should survive beyond one task.

Instructions:

Append entries to the bottom of this file.
Record decisions that are likely to matter again.
Include the context, the decision, and the consequences or tradeoffs.
Use this file for durable reasoning, not temporary task notes.
Promote non-obvious lessons here when they are too important to leave only in planning files.
Do not log technical details that belong in git commit messages.

Format each ADR as four concise lines:

## YYYY-MM-DD – Short decision title
Context: what problem or constraint existed
Decision: what was chosen
Consequences: tradeoffs, risks, or follow-on effects

2026-04-22 – Use a Cloudflare Worker between Jekyll and Square

Context: GitHub Pages is static, but the books page needs live catalog data and server-side checkout creation without exposing Square credentials. Decision: Keep the site static and add a repo-owned Cloudflare Worker as the only component allowed to talk to Square. Consequences: The worker adds one deploy target and one secret store, but it keeps secrets out of git and avoids adding a full custom backend.

2026-04-22 – Use Square-hosted checkout for the first online purchase flow

Context: The site needs a secure payment flow with the least custom payment surface and should ideally support buying more than one book at a time. Decision: Create Square-hosted payment links from the worker using a validated multi-item order and redirect buyers to Square for payment. Consequences: Checkout UX lives partly off-site on Square, but the implementation is simpler, more secure, and supports carts without handling card fields locally.

2026-04-22 – Publish only single-variation items with tracked stock

Context: The first version should avoid ambiguous pricing and availability while still supporting one-of-a-kind books and low-volume stock. Decision: Show only items that have exactly one sellable variation, a positive price, and positive tracked inventory at one configured Square location. Consequences: Sellers must keep inventory tracking enabled for books they want online, and multi-variation items are intentionally excluded until a later revision.

2026-04-23 – Keep cart continuity client-side and disposable

Context: The books page needed a more forgiving shopping flow, but this site remains a static Jekyll frontend with a tiny low-volume catalog and no appetite for extra backend state. Decision: Persist the cart only in browser localStorage, reconcile it against the latest live catalog on load, and silently discard invalid saved lines instead of introducing server-side cart storage or elaborate recovery flows. Consequences: Buyers keep their place across reloads with minimal implementation complexity, but cart state remains device-local and should always be treated as convenience state rather than authoritative inventory state.

2026-07-10 – Use flat-rate shipping and Square fulfillment

Context: Physical books need a paid shipping charge and deliverable address, but the catalog has no reliable package weights and a carrier-rate integration would add credentials and operational failure modes. Decision: Charge a configurable $5.00 USD flat rate for US orders, disclose the country limitation on Hermeticus, require buyer confirmation and address collection on Square, and use Square Orders Manager as the fulfillment source of truth. Consequences: Checkout remains simple and customer addresses stay out of Hermeticus, but Square cannot enforce a country allowlist. The shop must verify the destination, refund out-of-scope orders, absorb domestic rate differences, keep disclosures synchronized with Worker configuration, and complete paid fulfillments manually.

2026-07-10 – Replace flat shipping with catalog-aware rules

Context: The flat rate overcharges postcards and undercharges unusually heavy products, while Square’s public Catalog API does not expose the native Dashboard shipping-weight field or Dashboard shipping profiles. Decision: Supersede the flat-rate decision with a validated JSON rate table and a seller-visible Shipping weight (lb) catalog custom attribute. Use per-item defaults when weight is absent, weight pricing when present, free shipping through weights at or below 0.1 lb, and the higher candidate for mixed carts. Consequences: Typical books work without item setup and rate changes stay in one file. Sellers must use the custom attribute rather than Square’s native weight for this checkout, fractional calculated cents round up, and non-US orders still require cancellation because hosted checkout accepts all countries.