BAZARTY.COM (PAYLOAD + MONGODB)

Extending someone else's mature base is a different discipline from writing greenfield: any change of mine could silently break a convention I didn't know existed. Before adding a single line I reverse-engineered the base into .planning/codebase/* — ARCHITECTURE, CONVENTIONS, INTEGRATIONS — and sealed the patterns (a Payload collection, a tRPC router) into custom Claude skills that generate new code already in the house style. Conventions stopped being tribal knowledge — they became enforceable.

For handmade goods, stock is often exactly 1 — and two buyers clicking 'buy' at the same moment can't both get it. The Payload local API does read-modify-write (find → check stock → update), a classic TOCTOU race: both sessions read stock: 1, both pass validation, both decrement. Instead of fighting the framework, in this one spot I deliberately dropped below the ORM to the raw Mongo driver: a conditional atomic decrement where the $gte condition and $inc execute as one indivisible operation — modifiedCount === 1 means 'reserved', zero overselling. The reservation hooks in before the Stripe session is created, and a rollback restores stock when the session expires. It's the only place in the whole app that bypasses Payload — and the code explains why.

I built the escrow twice in one day. The first version used Stripe's delay_days — a payout hold counted from payment. It worked, but protected the wrong thing: the window runs from payment, not actual delivery, so with slow shipping the funds could reach the seller before the buyer ever saw the parcel. I threw it out after a few hours and rebuilt the model: seller accounts switch to payouts=manual, and my own sweeper releases the payout — exactly 2 days after the buyer confirms delivery, with an idempotency guard on stripePayoutId and the amount computed as a mirror of the checkout math so it never exceeds the balance by a cent. The readiness to discard working code when the risk model is wrong — and to record why — is this project's most valuable lesson.

Integrating Furgonetka (a courier aggregator) taught me humility before under-documented APIs: package creation broke on the address format (street as one field vs split street + building_number) and the API version, and the user-facing symptom was '0 delivery options' at checkout. Two successive fixes the same day made things worse — both broke package creation — so the third commit was a revert to the known-working version from main, with the reasoning spelled out in the message. Only then came the real fix: migrating to the calculate-price endpoint, hard parcel-dimension limits and — most importantly — replacing the silent zero with a message saying exactly what's missing (e.g. a two-part recipient name, minimum dimensions). The 'revert to known-good instead of stacking fixes' discipline stayed with me for good.