Recent architectural decisions

Significant decisions of the last 30 days. Read this when picking up where the previous Claude session left off — captures the "why" that git log alone doesn't.

2026-05 · Spread default 0.15 → 0.25

Bumped the default Flip/Pull spread from 15% to 25% across the entire ecosystem. New lots committed via Strategist or Lot Builder land at 25%. Existing lots can be retro-updated via the "Set all lots → 25%" button on Lot Builder, which calls POST /api/admin/normalize-lot-spreads on ToT.

Why: 15% was leaving margin on the table — the buyer's "win" amount felt small, the operator's "lose" margin was thin. 25% is the new floor where the gambling element feels real to buyers + the operator's margin on losses is meaningful.

2026-05 · Auto-publish on ToT ingest webhook

Previously, SlabTrack's Strategist commit pushed cards to ToT's /api/webhook/ingest which only STAGED them in CollectionCard. Operator had to manually go to /collection and click "Bulk-list" to actually create Listings. Now the webhook auto-creates Listings directly during ingest.

File: thisorthat/src/app/api/webhook/ingest/route.ts — see commit 26d7b4f on the ToT repo.

Why: the two-step workflow was confusing operators ("I committed but nothing appeared"). Auto-publish makes commit → live a single action. Idempotency guards prevent double-listing on retries.

2026-05 · Lot cap 10 → 25

Strategist's MAX_CARDS_PER_LOT was 10 — silently dropped any lot bigger than that. Real city lots (Dallas Cowboys + Mavs + Stars + Rangers all years) routinely hit 12-20 cards. Bumped to 25.

File: slabtrack/backend/routes/curator.routes.js bulk-list action.

Why: the IG-carousel-of-10-slides constraint was a marketing concern, not a marketplace listing constraint — /browse handles 20-card lots fine.

2026-05 · ToT Stripe singleton + API version alignment

ToT had 8 inline new Stripe(...) sites with the API version pinned in each. Storefront was on 2026-04-22.dahlia; ToT was a year behind on 2025-04-30.basil. Created thisorthat/src/lib/stripe.ts singleton and bulk-bumped all 8 sites to the current version.

Why: version drift was inevitable with 8 inline instances. Single source of truth = future drifts can't silently happen.

2026-05 · Eligibility filter removed from FilterRail

The "Solo / Pull-only / All cards" eligibility filter was creating the false impression that 85 sub-$15 cards weren't available (the filter showed "99 of 184"). Reframed as "Solo-flip ready" and eventually removed entirely. Every card plays both games via cart-flip or pull stack — the per-card eligibility flag is now operator-side intelligence, not a buyer filter.

Files: thisorthat/src/components/marketplace/FilterRail.tsx + src/components/marketplace/CardDetailDrawer.tsx + ListingCard.tsx.

2026-05 · Singles-everywhere policy

Decision to phase out lots entirely on initial commit and rely on Pull/cart-flip for sub-$15 economics. Backend lot system stays in place for Lot Builder workflow; operators choose lots vs singles per-commit. Default for new commits = singles-only. Lots are now a deliberate "city/team bundle" tool, not a default.

2026-05 · Theme Studio + 9 presets + 12 palettes

Built operator-facing customization layer. Storefront row gained 14 theme fields. resolveStorefrontTheme() merges per-field overrides over the chosen preset's defaults. StorefrontThemeProvider exposes the resolved theme to every component via React context. 9 presets (3 dramatic with signature palettes), 12 curated color palettes.

Files: slabtrack-storefront/src/lib/storefront-theme.ts + app/dashboard/[slug]/theme/ + components/StorefrontThemeProvider.tsx.

2026-05 · Stripe + Shippo audit fixes

Production-readiness audit. Four blockers fixed across both repos:

• ToT ship-from address fallback was silently shipping with blank addresses → getOriginAddress() throws loud now
• Shippo env var inconsistency: ToT used SHIPPO_API_KEY, Storefront used SHIPPO_API_TOKEN → both repos now accept either, prefer SHIPPO_API_TOKEN
• Storefront Checkout Session + Refund creates were missing idempotency keys → added pattern {action}-{stable-id}
• Storefront payment_intent.payment_failed + .canceled webhook events weren't handled → Order stayed pending forever on declined cards. Now collapsed into one handler.

2026-04 · Sale-lock cross-channel coordination

The sale_locks table + service. When a buyer enters checkout on any channel, that channel acquires a lock for each card across the ecosystem. Lock TTL = 10 minutes. Released on cancel/failure; flipped to "sold" + bulk-disengage on success. Prevents double-sale across Storefront + ToT.

Files: slabtrack/backend/services/sale-lock-service.js + per-repo clients.

2026-04 · Multi-tenant Storefront launch

Stood up slabtrack-storefront as the multi-tenant vendor shop platform. Each shop gets a slug at storefront.slabtrack.io/[slug]. Stripe Connect Express onboarding per shop. Per-shop ship-from. Shared JWT auth with SlabTrack.

2026-04 · Provably-fair on-chain anchoring

Solana memo transactions for every Flip/Pull commit. Hash anchored before reveal. Buyers can verify outcomes by recomputing SHA-256 and checking against on-chain memo. Optional but recommended; falls back to SHA-256-only if Solana env vars unset.

How to use this page

• When picking up a session: read top to bottom for ~30 days of context
• When making a significant decision: add a new entry at the top with date + WHY
• When 60+ days old: prune entries that are no longer "recent" — move to a separate archive page if needed