Synesthesia

Input

• Command: /synesthesia
• Target: The checkout service at Meridian Commerce — a Node.js monolith handling cart validation, coupon resolution, payment orchestration, and order creation in a single 2,400-line checkout.service.ts file
• Context: The team is seeing intermittent double-charges in production (roughly 1 in 800 orders), a p99 latency of 4.2s on the payment step, and onboarding takes new engineers ~3 weeks before they feel safe touching this file
• Mode: Debugging + Performance

Output (abbreviated)

Literal read

• checkout.service.ts is a single class with 34 public and semi-public methods; cart validation, coupon resolution, Stripe API calls, inventory reservation, and order persistence all share the same instance state
• Payment is orchestrated inline: chargeCard() → reserveInventory() → createOrder() with no saga, outbox, or compensating transaction — failure at step 3 leaves a charged card with no order
• Coupon resolution calls a Redis cache, but on cache miss falls through to a Postgres query inside a loop over cart line items — no batching
• Three separate locations call Stripe.charges.create() conditionally; one is inside a retry block that does not check for idempotency key collisions
• No distributed lock guards the critical section between charge and order creation; the only concurrency protection is an optimistic Postgres update that is bypassed when the retry fires
• Test coverage is 41% by line, concentrated almost entirely in coupon math; payment and order paths have no integration tests

Synesthetic render

Visual: The file opens as a saturated, warm amber — the coupon logic has real cohesion and emits clean, stable color. But halfway through, the hue bleeds into orange-brown, then into a murky, stained red around the payment block. The charge/reserve/create triplet looks like three spotlights aimed at the same wall from different angles, casting overlapping shadows that shift depending on which code path was taken last. The retry block is a small, very bright white flare — almost overexposed — sitting inside an otherwise dim corridor.

Auditory: The service has the rhythm of a competent solo pianist playing a composed piece — until bar 34, where a second pianist enters playing the same melody half a beat behind. The result is a phase clash: two nearly identical note sequences interfering with each other. The Stripe retry is the second pianist. On most runs they resolve in unison. On 1 in 800, they don't.

Spatial / tactile: The overall shape is a long, narrow corridor with a sharp bottleneck at the payment step — high traffic, hot walls, pressured airflow. Branching off the main corridor are several doors that look closed but open inward on retry. The coupon-resolution loop is a section of corridor lined with speed bumps: smooth if cache is warm, suddenly rough and dragging when it isn't.

Dissonances

1. Phase clash at payment (the double-charge signal): The retry path and the primary path can both reach Stripe.charges.create() without a shared idempotency key derived from a stable order ID. This is the interference pattern — two identical signals slightly out of sync.

2. Hot corridor with no pressure release (the p99 signal): The cache-miss path in coupon resolution issues N sequential Postgres queries inside the same synchronous chain that holds the payment lock. This is the speed-bump drag compounding with the bottleneck heat.

3. Murky interior hiding the compensation gap: The file looks structured (classes, JSDoc, consistent naming) but the absence of any compensating transaction means the interior is folded — complexity hidden behind a polished surface. The stain spreads only when things go wrong, which is exactly when you most need clarity.

Engineering translation

Recommended changes

1. Assign idempotency keys before calling Stripe (fix double-charge, high leverage) Generate a stable orderId (UUID) at the start of checkout, before any Stripe call. Pass it as the idempotency key on every charges.create() call site. Remove the retry block's independent key generation. This collapses the phase clash.

2. Batch coupon resolution (fix p99, immediate) Replace the per-item cache-miss loop with a single WHERE coupon_code = ANY($1) Postgres query and a multi-key Redis MGET. Wrap in Promise.all if calls remain independent. Expected p99 improvement: 800ms–1.5s based on typical cart sizes.

3. Instrument the charge→reserve→create triplet now (reduce blindness) Add structured logs with a shared checkoutSessionId at each step and emit a checkout.charge_without_order metric when Stripe charge exists but no order was created within 30s. This makes the compensation gap visible before you restructure it.

4. Introduce a minimal outbox or idempotent order-creation guard (prevent revenue loss, medium effort) Store a pending_orders row with the orderId and Stripe charge ID before calling Stripe. On order creation, upsert on orderId. This converts the three-step cliff into a recoverable ledger.

5. Decompose checkout.service.ts into three bounded modules (fix onboarding friction, refactoring mode) Split into CouponService, PaymentOrchestrator, and OrderWriter. Each file should have one clear responsibility and one color — the amber of the coupon logic, properly isolated, is already clean. The goal is three separate rooms with defined doorways, not one overheated corridor.