Architecture

Architecture

Purpose: describe the current stable technical map of the system.

Instructions:

  • Document the system as it currently exists in stable form.
  • Focus on major components, boundaries, interfaces, data flow, storage, external dependencies, and invariants.
  • Update this file when implemented changes alter the stable technical shape of the system.
  • Keep this file descriptive of current reality, not speculative.
  • Do not use this file as a task log, scratchpad, or decision diary.
  • Additional documents may be created when describing the details of major components. For example, the documentation for an API may be linked to an OpenAPI specification at docs/api.yaml.

System Overview

Hermeticus is a static Jekyll site deployed on GitHub Pages at https://hermeticus.org. Most pages are fully static, but the /books/ page now depends on a separate Cloudflare Worker to read live book data from Square and create hosted checkout sessions. The site itself never stores Square secrets and never handles payment card entry.

Major Components and Boundaries

  • GitHub Pages Jekyll site Stores page content, layouts, styles, and browser-side catalog code. It renders the page shell for /books/, loads assets/js/main.js, and points that code at the deployed worker URL through _config.yml.
  • Cloudflare Worker Lives in integrations/square-catalog-worker/. It exposes:
    • GET /catalog for public catalog reads
    • POST /checkout for server-validated cart checkout creation The worker is the only component that talks to Square APIs.
  • Square Catalog API Source of item, category, image, variation, and seller-visible custom-attribute data. A number custom attribute named Shipping weight (lb) bridges product weights into the Worker because Square does not expose its native Dashboard shipping-weight field through this API.
  • Square Inventory API Source of the current stock count for each published book at one configured Square location.
  • Square Checkout API Creates Square-hosted payment links for validated multi-item carts.

Interfaces and Data Flow

  1. A visitor opens /books/ on hermeticus.org.
  2. The static page shell from pages/books.md and _includes/square-catalog.html loads.
  3. assets/js/main.js reads square_catalog_api_base from _config.yml, restores any previously saved cart lines from browser localStorage, and requests GET <worker>/catalog.
  4. The worker checks Cloudflare edge cache.
  5. On a cache miss, the worker:
    • paginates through Square ListCatalog for ITEM, CATEGORY, IMAGE, and CUSTOM_ATTRIBUTE_DEFINITION
    • extracts items that are publishable for v1
    • retrieves inventory counts for candidate variation IDs at SQUARE_LOCATION_ID
    • returns a compact JSON array with short keys
    • caches that response at Cloudflare
  6. The browser renders cards with category, image links, Square description content, price, stock count, browse controls, and add-to-cart controls.
  7. Client-side search, category filtering, and sorting run entirely against the already loaded catalog array without further network requests.
  8. The browser persists cart lines in localStorage, reconciles them against the freshly loaded catalog on page load, and silently drops lines that are no longer valid.
  9. When the buyer checks out, assets/js/main.js sends POST <worker>/checkout with variation IDs and requested quantities.
  10. The worker bypasses the cached public payload, rebuilds current live availability from Square, validates the cart, calculates shipping from the trusted quantities and weights using shipping-rates.json, and creates a Square-hosted payment link with required address collection.
  11. The browser redirects the buyer to Square’s checkout page. Square stores the paid buyer’s address in a SHIPMENT fulfillment. On a ?checkout=success return, the client clears the saved cart and shows a payment-complete message.
  12. The shop ships the books and manually completes the paid fulfillment in Square Orders Manager.

The public catalog payload uses these keys:

  • i item ID
  • v variation ID
  • n name
  • p price in minor units
  • d description. This contains Square description_html when available, otherwise Square plaintext description data.
  • c category name
  • m image URL list
  • w shipping weight in pounds, or null when no valid custom weight is specified
  • q quantity available

The checkout payload returns { "u": "<square-checkout-url>" } on success.

Storage and External Dependencies

  • No database is used by the site or worker.
  • Catalog browse results are cached at Cloudflare edge with a short TTL.
  • Shipping rules are bundled from integrations/square-catalog-worker/shipping-rates.json; no rate environment variable or database is used.
  • The /books/ page stores cart state in browser localStorage under a repo-owned key. This storage is client-side only and is treated as disposable convenience state, not a source of truth.
  • Secrets are stored only in Cloudflare Worker secrets:
    • SQUARE_ACCESS_TOKEN
  • Non-secret worker configuration currently includes:
    • ALLOWED_ORIGINS
    • SQUARE_ENV
    • SQUARE_LOCATION_ID
    • CATALOG_TTL_SECONDS
    • SQUARE_VERSION
  • Site-side worker location is configured in _config.yml through square_catalog_api_base.
  • External runtime dependencies:
    • GitHub Pages / Jekyll
    • Cloudflare Workers
    • Square Catalog, Inventory, and Checkout APIs

Invariants

  • The public Git repository contains no Square or Cloudflare secrets.
  • Payment card entry never happens on hermeticus.org; buyers complete payment on Square-hosted checkout.
  • Customer shipping addresses remain in Square and are not stored by Hermeticus.
  • Shipping configuration must pass structural and currency validation when the Worker module loads.
  • Missing, negative, or malformed catalog weights become null and use per-item shipping; weights from 0 through 0.1 lb are excluded from shipping.
  • Null-weight-only carts use the configured quantity table. Weighted-only carts use the rounded-up per-pound result with its free and minimum thresholds. Mixed carts use the higher of the weight result and the quantity-table result for all non-free items.
  • The current quantity table charges $5 for one qualifying item, adds $1 per item through $28 for 24, and charges $30 for 25 or more. Weight pricing is $2 per pound, calculated amounts below $1 are free, and amounts from $1 through $5 use a $5 minimum.
  • Square collects any shipping country and no custom confirmation field is used. The shop cancels and refunds non-US orders during fulfillment review.
  • Only items with exactly one sellable variation and positive tracked inventory at the configured Square location are published on /books/.
  • Items with zero inventory or archived state disappear from the public catalog after cache refresh.
  • GET /catalog is cacheable; POST /checkout must validate against fresh Square data before creating a checkout link.
  • Browser code must sanitize Square description HTML before rendering it. Other catalog fields are rendered as text.
  • Browser-stored cart lines must be reconciled against the latest live catalog payload before rendering or checkout.