DEV Community: David Bartalos

Replace the Heuristic With a Boundary: Rebuilding a Leave Table as an Append-Only Ledger

David Bartalos — Fri, 14 Aug 2026 10:29:58 +0000

We deleted the reconciliation step from a data migration and replaced it with a single timestamp. Nothing overlaps, so nothing needs matching.

That's the ending. Here's how we got there — and the short version of part 1, for anyone arriving without it:

We were moving short-term leave data from a legacy processor to a new service. To avoid double-counting during the overlap, a step called heal matched a new row against a legacy-seeded one on value shape — (employee_id, date, leave_type, unit, amount), the only columns the two feeds shared — and appended a compensating negative entry. Two days of bug fixing later we measured it: 9 of the 13 compensating rows it had ever written in production were wrong, and 238 of 244 overlapping employee-days reconciled exactly with no compensation at all. Separately, the table's primary key (request_id, date) turned out not to be unique — one correction request can carry four entries across two dates, and our upsert silently published 16 hours where the truth was 8.

Two problems: rows that shouldn't be matched, and rows that shouldn't collide.

	Before	After
Grain	one row per `(request, date)`	one row per entry
Key	`(request_id, date)`	`(request_id, date, amount, seq)`
Conflict	`DO UPDATE … WHERE IS DISTINCT FROM`	`DO NOTHING`
Amount type	`REAL`	`NUMERIC(10,4)`
Overlap handling	match on value shape, compensate	a cutover boundary; no matching at all

Start from the read path

The thing we should have looked at first is what the consumer actually asks for:

SELECT employee_id, date, leave_type, unit, SUM(amount) AS amount
FROM leave_ledger
WHERE (employee_id, date) IN (SELECT * FROM unnest($1::int[], $2::date[]))
GROUP BY employee_id, date, leave_type, unit

That is a ledger read. It sums signed rows and never cares how many there are. It had looked like that from day one. Every problem in part 1 came from the write path underneath it being a mutable table pretending otherwise — and from heal, which existed only to keep that mutable table's arithmetic straight.

Make the write path agree with the read path and both problems dissolve.

One row per entry, keyed on the amount, never updated

INSERT INTO leave_ledger
  (request_id, date, employee_id, leave_type, unit, amount, seq, source)
VALUES ($1, $2, $3, $4, $5, $6, $7, 'new-feed')
ON CONFLICT (request_id, date, amount, seq) DO NOTHING
RETURNING *

Three deliberate choices in five lines.

DO NOTHING, not DO UPDATE. The rolling lookback deliberately re-sends the same request across consecutive syncs, and the transformer derives the same key set from the same payload every time, so a re-send is an exact no-op. Rows are never mutated. This isn't purism — part 1's measurement found that 0 of 1,299 rows had ever been updated across syncs anyway. The update branch existed only to produce the 16h/0h bug.

amount is in the key. Here is the correction from part 1, stored under the new key:

entry	date	amount	seq
1	13/08	`−8`	1
2	13/08	`+8`	1	distinct key — differs on `amount`
3	14/08	`+8`	1
4	14/08	`−8`	1	distinct key — differs on `amount`
				balance: 8 and 8 ✅

Four entries, four rows, nothing overwritten, and the day totals come out right without anyone netting anything by hand.

RETURNING * is the change signal. It yields rows only for genuinely new entries — precisely the "what changed, what should we republish downstream" question the old IS DISTINCT FROM predicate was computing. The change-detection logic didn't need porting to the new model; it fell out of the insert. That was the moment the design felt right rather than merely correct.

`seq`, and why it counts per group

amount in the key separates −8 from +8. It does not separate a shift split as 13/08 - 4 Hours; 13/08 - 4 Hours, where the two entries are genuinely identical:

// Number entries within each (date, amount) group, not across the whole request.
// Because the entries it separates are identical, any ordering of them is equivalent —
// so re-parsing the same payload in any order yields the same key set.
const seqByGroup = new Map<string, number>();

return entries.map(({ date, amount }) => {
  const group = `${date}:${amount}`;
  const seq = (seqByGroup.get(group) ?? 0) + 1;
  seqByGroup.set(group, seq);
  return { requestId, date, amount, seq, employeeId, leaveType, unit };
});

Counting per (date, amount) group rather than per entry matters more than it looks. The correction payload from part 1 proves the source doesn't order entries consistently — −8, +8 on one date and +8, −8 on the other, in the same request. A seq assigned by entry position would change between syncs, produce new keys, and re-insert the same absence forever. Assigned per group, it's a pure function of the payload's contents.

Is it necessary? We can't prove it. A seq > 1 row has never been observed in production. And we can't go and check the history either, because the old upsert overwrote the evidence — the exact rows that would tell us are the ones it destroyed. So seq ships as a column that is either load-bearing or free, and there is no experiment available that distinguishes those. Given the alternative is finding out after the balances are wrong, that's a fine trade.

`NUMERIC`, not `REAL`, once it's in the key

The legacy column was REAL and nobody had minded. Putting the amount in the primary key changes that, because the data is not binary-exact: fractional-day holidays exist, and out of a REAL column they read back as 0.83000004 and 0.66999996, with a booking-plus-correction pair netting to −4.47e-8 instead of 0.

Keying on a type that cannot represent its own values exactly makes luck load-bearing. NUMERIC(10,4).

The boundary that replaced heal

The report we poll is filtered on a completed_on_or_after parameter. Set that boundary to the instant the seed snapshot was taken, and no request in the seed can ever arrive from the new feed. Nothing overlaps, so nothing needs matching. The unanswerable question is never asked.

That's the entire replacement for heal: a parameter we were already passing, given one specific value.

The boundary is completion time, not absence date — an easy thing to get wrong. Corrections to historical absences legitimately arrive after cutover; they're just new ledger entries whose signed amount adjusts the balance. Cutting on absence date would drop them on the floor.

What that deleted

The whole change was 16 files, +1,230 / −1,158. The interesting part is where the deletions landed:

File	Lines
The queries file (heal's five CTEs, the upsert, the change predicate)	+27 / −184
Its repository tests	+96 / −506
Everything under `src/`	+417 / −847

The test file is the number I'd point at. Five hundred lines of tests didn't get deleted so much as become meaningless: they tested ranking, netting, snapshot-bounding and 1:1 capping, none of which are concepts in the new model. All five root causes from part 1 were retired structurally — the code path they lived in no longer exists, so they can't regress rather than merely being fixed. 277 tests pass on the other side.

The assumption we couldn't eliminate

Honest ledgers have honest caveats. Ours: because amount is in the key, a restated amount under an existing request ID would append a second entry rather than conflict with the first, inflating the balance. DO NOTHING cannot catch it — a changed value simply isn't a conflict.

We can't prevent it, so we detect it. The report always sends a request's full entry list, so for any request ID it mentions, the entries we derive should exactly equal what we've stored. A stored entry the report no longer claims means the request was restated rather than corrected:

// Warn-only, deliberately. A false positive must never block a sync.
const stored = await this.repository.findStoredEntryKeys(requestIds);
const identity = (e) => `${e.date}:${e.amount}:${e.seq}`;
// For each request the report mentions, compare its derived identity set against
// the stored one; log a warning for any stored entry the report no longer claims.

It has never fired. If it ever does, we find out from a log line rather than from payroll.

The invariants we run

Three one-line guards, run alongside the parity query. Each maps to a way the model could quietly stop being true:

SELECT 'mutated ledger rows' AS invariant, COUNT(*) AS violations
FROM leave_ledger WHERE updated_at <> created_at
UNION ALL
SELECT 'heal-sourced rows', COUNT(*)
FROM leave_ledger WHERE source = 'heal'
UNION ALL
SELECT 'legacy rows losing precision at NUMERIC(10,4)', COUNT(*)
FROM leave_legacy
WHERE amount IS NOT NULL AND amount::numeric(10,4) <> amount::numeric;

The first says nothing has learned to update a ledger row. The second says nobody has reintroduced compensation — the mechanism is gone, so any row claiming that source is a regression by definition. The third is the one I like: before you migrate REAL into a narrower NUMERIC, make the database tell you whether every existing value survives the round trip.

The cutover is where the risk actually went

Deleting heal didn't remove risk from the migration, it concentrated it into one step: deriving the boundary. Here are six consecutive parity runs, with no code changes between them:

Run	State	Mismatched employee-days	Net hours diff
1	Seeded, narrow catchup window	235	−394.75
2	Catchup window widened	25	−41
3	Widened again	19	+7
4	Both feeds caught up	0	0
5	One new booking mid-run	1	+8
6	Both schedulers live	0	0

Run 1 is the lesson. We derived the boundary from MAX(created_at) on the seeded rows while the legacy processor was still writing. But legacy's write clock lags the platform's completion clock by up to about 7 hours 15 minutes — a 13-hour approval lookback, a 30-minute cadence, and no runs overnight. Any request that completed before the boundary but was written after it landed in neither side. 235 employee-days, ~395 hours, invisible until we widened the catchup window far enough to sweep them back up.

The fix is one step at the top of the seed script: disable and drain the legacy processor before deriving the boundary. That makes the gap empty by construction rather than by luck — the difference between a boundary that's sound and one that happens to work.

Run 5 is the other lesson. A single new booking arrived between runs and showed as a mismatch until the other feed's next cycle. A non-zero parity result is not automatically a regression — and "stable across two runs" doesn't rule out lag either. We had a mismatch set hold steady across two consecutive runs and resolve on the third.

Runs 4 and 6 are both zero with 15+ new rows landing on each side in between, which is what makes it steady-state agreement rather than two feeds happening to line up after a bad snapshot. Both sides: 212,887 rows, 17,808 employees, hours totals identical.

One caveat we wrote down rather than chased: the days column reads −0.0022 forever, because the legacy column is REAL, ours is NUMERIC, and Postgres returns sum(real) -> real. It's documented as expected, with the > 0.0001 tolerance in the comparison queries. Don't let a known float artifact train your team to ignore a red result.

Where this actually stands

Because a war story that ends "and then it was perfect" is a war story that's lying to you:

The real cutover hasn't happened. Everything above is a rehearsal. Parity was reached by convergence — widening the catchup window until both feeds covered the gap — not by a sound boundary. The production run still has to do the drain-first sequence that run 1 taught us.
Nothing reads the ledger yet. The API and the warehouse view still read the legacy table. The parity we're protecting is parity for a table with no consumers.
That's also why the rebuild was affordable. Changing a primary key on ~3M rows was a drop-and-recreate rather than a delicate in-place migration, precisely because no reader would notice. Had this been found a phase later, the same fix would have been an order of magnitude more expensive. The bug was worth finding early far more than it was worth fixing well.

What the design taught us

Prefer a boundary to a heuristic. If you need to decide whether two records describe the same real-world event and they share no identifier, don't build a matcher — find a boundary that makes the overlap empty. Ours already existed as a filter parameter on the source report. We'd just never thought of it as a cutover instant.

Deleting the mechanism moves the risk, it doesn't remove it. Heal was over a thousand lines of continuously-wrong compensation; the boundary is one timestamp that has to be right once. Much better trade — but only if you treat that instant with the seriousness those thousand lines used to absorb. Run 1 is what happens when you don't.

Put the thing you key on in a type that can represent it. REAL was fine as a payload column and unfit as a key column, and nothing about the migration would have told us that if we hadn't gone looking for 0.83000004.

Immutability isn't purism when the data is financial. Leave balances feed payroll. Corrections staying individually queryable, rather than being netted away by an update, is worth the extra rows — and the source was already emitting signed deltas.

Let the write path match the read path. This is the part that stings. The consumer query was SUM(amount) GROUP BY employee, date, type all along. It had been a ledger the whole time. We'd just built a mutable table underneath it and spent two days reconciling the difference.

Nine of Thirteen Corrections Were Wrong: The Fix That Came With a Proof It Couldn't Work

David Bartalos — Fri, 14 Aug 2026 10:29:48 +0000

Nine of the thirteen corrections our migration code had ever written in production were wrong. We found that out by stopping the bug fixes and counting.

Some context. We were migrating short-term leave data — sick days, compassionate leave, the odd half-day — from a legacy processor to a new integration service. Same source system upstream, same consumers downstream, new table in the middle. The kind of migration you scope at a week.

Two days of it went into fixing bugs in a mechanism that could never have worked. This is how we finally noticed. Part 2 is what we replaced it with.

All identifiers are anonymised and the systems described generically. The numbers are real.

The setup

Two feeds write leave data:

The legacy processor — running for years, polls the HR platform every 30 minutes during the day, writes one row per employee-day.
The new service — polls every 15 minutes, 24/7, writes to a new table.

To cut over, we froze a snapshot of the legacy table, copied it into the new table tagged source = 'legacy', and let the new feed take over. The new service would gradually re-report the same absences as its rolling lookback window swept over them.

Which creates the obvious problem: the new feed writes an absence that is already in the table as a legacy row, and the balance double-counts.

Our answer was a step called heal. When the new feed wrote a row that looked like an existing legacy row, heal appended a compensating negative entry cancelling the legacy one out:

source	date	amount
`legacy`	13/08	`+8`	seeded from the snapshot
`new-feed`	13/08	`+8`	re-reported by the new service
`heal`	13/08	`−8`	written by heal to cancel the legacy row
		`8`	what the consumer reads

The balance stays correct, and over time every legacy row gets superseded by a properly-sourced one. The consumer never sees any of this — it reads SUM(amount) per employee-day. Remember that detail; it matters more than anything else in this post.

The catch — and we knew this at design time, we just didn't weigh it properly — is that the two feeds share no identifier. Legacy request IDs are day-level. The new report's are request-level, and one request can span five days. There is no join key.

So heal matched on the only columns both feeds had:

-- "Is this new-feed row a replacement for that legacy row?"
(employee_id, date, leave_type, unit, amount)

Match on value shape. It worked in testing. It worked in the first sync after the snapshot.

The parity check

Everything that follows came out of one query. Sum both tables per employee-day, full outer join, show me anything that differs:

WITH legacy AS (
  SELECT employee_id, date, SUM(amount::numeric(10,4)) AS total
  FROM leave_legacy
  WHERE date BETWEEN :from AND :to
  GROUP BY employee_id, date
),
ledger AS (
  SELECT employee_id, date, SUM(amount) AS total
  FROM leave_ledger
  WHERE date BETWEEN :from AND :to
  GROUP BY employee_id, date
)
SELECT COALESCE(l.employee_id, r.employee_id) AS employee_id,
       COALESCE(l.date, r.date)               AS date,
       COALESCE(l.total, 0)                   AS legacy_total,
       COALESCE(r.total, 0)                   AS ledger_total
FROM legacy l
FULL OUTER JOIN ledger r
  ON l.employee_id = r.employee_id AND l.date = r.date
WHERE ABS(COALESCE(r.total, 0) - COALESCE(l.total, 0)) > 0.0001
ORDER BY 1, 2;

Two things to note, because both come back later. The comparison key is (employee_id, date) — never the request ID, since the two feeds' IDs are at different grains and never match. And that > 0.0001 tolerance is not defensive padding: the legacy column is REAL, ours is NUMERIC, and Postgres returns sum(real) -> real, so an exact comparison reports float noise as drift. 0.83 reads back as 0.83000004.

That query returns rows. So you go and fix things.

Two days of whack-a-mole

Bug 1 — the superseded field. The HR platform had quietly started sending a new field for the leave type name, superseding the old one. Both were present during the transition. We were reading the old one. Type labels diverged between the feeds, so heal never matched, so nothing healed, so everything double-counted. Around 1,900 records' worth.

Bug 2 — timezone off-by-one. toIsoDate() read a Postgres DATE back and called .toISOString() on it. The driver builds that Date from local-time components, not UTC, so any process running ahead of UTC shifts the calendar day by one. Heal was comparing the 12th against the 13th and finding nothing.

Bug 3 — case sensitivity. The two feeds spelled some leave types with different casing. The match was case-sensitive.

Fixing 2 and 3 together took a test sync from 25 of 45 rows healing correctly to 472 of 473. That felt like winning. We added a regression query to the comparison script and moved on.

Bug 4 — the unbounded heal. The replacement test was an EXISTS: does a new-feed row with this value shape exist for this employee-day? If two legacy rows happened to share an identical shape on the same day and only one replacement existed, EXISTS was true for both, so heal cancelled both — moving the balance by (legacy_count − replacement_count) × amount.

The fix was to cap healing 1:1 per group: count the available replacements, count the ones already used by previous heals, rank the unhealed legacy rows, and only heal up to the difference.

WITH keys AS (…),
     legacy_rows AS (…),          -- + whether each is already healed
     group_used AS (…),           -- replacements consumed by previous runs
     replacement_counts AS (…),   -- replacements available in this group
     ranked_unhealed AS (…)       -- ROW_NUMBER() over the group
INSERT INTO leave_ledger (…)
SELECT … FROM ranked_unhealed
WHERE rn <= available_replacements - used_replacements

It worked, and it was idempotent, and it turned a twenty-line statement into five CTEs. At the time that read as rigour. It was actually the mechanism telling us something: a matching rule that needs rank-and-cap arithmetic to stay correct is a matching rule that doesn't have enough information to work with.

Bug 5 — the one that broke it. A brand-new leave request can have the exact same value shape as an old legacy booking that has already been cancelled by a correction. Heal saw the shape match, decided the new request was a duplicate, and cancelled the legacy row a second time. Silently deflating a real person's balance.

We fixed that one properly — or thought we did. The insight was that the signal separating the two cases is temporal, and the source system already sends it: the legacy rows are a frozen copy taken at one instant, so they cannot contain an event that hadn't been initiated by then. A new row initiated after its candidate legacy row was snapshotted is provably a different event. We added an initiated timestamp to the schema, threaded it through the transformer, and gated heal on causality rather than coincidence. Three regression tests, one replaying a real three-sync sequence against production IDs.

It was, honestly, a nice fix. It was also the moment the whole approach fell over.

The sentence that ended it

While writing the commit message for bug 5, we wrote this to explain why no simpler rule would do:

No rule over those five columns can fix this — the identical shape also occurs when the heal
is correct, so any ordering preference gets one of the two cases wrong.

Read that again with fresh eyes. It isn't a description of a bug. It's a statement that the mechanism cannot be made correct. (employee_id, date, leave_type, unit, amount) takes the same value when two rows are the same underlying event and when they are unrelated events that coincide. Two 8-hour sick days for the same person on the same date are indistinguishable in those columns whether one is a duplicate of the other or not.

Not undecidable in the computer-science sense — this is more mundane and more annoying than a halting problem. The information needed to answer the question is simply not present in the data, and no amount of cleverness over five columns conjures it. Every fix we'd shipped was a better guess at a question that has no answer.

Five root causes in two days, all living inside the same matching rule, and the fifth one's fix shipped with a written argument for why the rule can't be made sound. That's not a code quality problem. That's the design talking.

So we stopped fixing and started measuring.

Measuring instead of fixing

Three queries against production data:

Measurement	Result
Compensating rows heal had ever written in production	13
…of those, wrong	9
…the 4 correct ones dated from	the single sync right after the snapshot
Employee-days present in both the frozen snapshot and the new feed	244
…reconciling exactly under a no-heal-at-all rule	238
…explained by a correct heal row	4
…unexplained	2
New-feed rows ever mutated across syncs (`updated_at` trigger)	0 of 1,299
Max `updated_at − created_at`	8.8 ms

Three things fall straight out of that.

Heal was net-negative in production. Thirteen rows, out of roughly 1,300 the new feed had written. Nine wrong, four right, and all four right ones came from one sync immediately after the snapshot. That asymmetry is structural, not bad luck: genuine overlap is a spent cutover artifact that decays to nothing, while coincidental value matches accrue forever, with every new request. The mechanism was guaranteed to get worse over time.

Corrections are deltas, not restatements. 238 of 244 overlapping employee-days reconcile exactly if you just let both rows stand and add them up. The HR platform doesn't restate a day's total; it emits signed adjustments that sum correctly. We had built compensation for a problem the source data already solved.

The rows were already immutable. Zero of 1,299 rows had ever been updated across syncs. The 8.8 ms maximum gap between create and update means the only DO UPDATE that ever fired did so within a single batch — never across syncs. Our upsert's update branch existed purely to produce bugs.

The bill for all this was nine hours of leave, deflated across two people's balances, deleted by hand once we understood them. Small, and it stayed small for an unsatisfying reason: the new table had no downstream readers yet, because the later phases of the migration hadn't run. The sync does publish each changed balance as an event, so the wrong numbers did leave the service — but the tables the wider business reads were still the legacy ones.

Nothing alerted, either. Every one of those 13 rows was written by a sync that reported success. The only reason we know the number at all is that we'd built the parity harness.

Which brings us to those two unexplained employee-days.

The twist

One request from the HR platform, business process "Absence Correction", carried this:

entries:            "13/08 - -8 Hours; 13/08 - 8 Hours;
                     14/08 -  8 Hours; 14/08 - -8 Hours"
total_units_hours:  "0"

Four entries, two dates, netting zero on both — a cancel-and-rebook, which is exactly what a correction looks like.

Our table's primary key was (request_id, date). Our transformer emitted one row per entry. So all four rows collided on two keys, and the sequential upsert kept the last write per date:

#	Entry	Result
1	`13/08 −8`	INSERT → `−8`
2	`13/08 +8`	conflict → UPDATE → `+8` overwrites
3	`14/08 +8`	INSERT → `+8`
4	`14/08 −8`	conflict → UPDATE → `−8` overwrites

The balance we published was 16 hours on the 13th and 0 on the 14th. The truth was 8 and 8.

No error. No warning. No failed row. And look at the last line of the payload: the source system sent us total_units_hours: "0", a checksum for the entire request, flatly contradicting what we had stored. We had never checked it.

The design document for the table said, in as many words, that corrections "are modelled as separate requests, not as mutations of the original row", and therefore (request_id, date) identifies exactly one value. That assumption was wrong. A single request can carry multiple entries for the same date, and any correction that cancels and re-books on the same day hits it.

Worse, the bug destroys its own evidence. An overwritten row leaves nothing behind saying it was overwritten, so you cannot query the table to find out how often this happened. We still don't know.

Why the tests were green

They were green because they were honest tests of the wrong thing.

The transformer had unit tests. The repository had integration tests against real Postgres in a container, not a mock. Both passed throughout. Their fixtures were built from payloads we had actually seen — one entry per date, clean value shapes, the happy path — because that is what fixtures are: a record of what you already know.

The four-entry correction wasn't in the fixture set because we didn't know that shape existed. Every bug in this post lived in the correction path, which is a few percent of volume, produces no errors when it's wrong, and is the part that matters most.

So: the reconciliation step could not be made correct, and the primary key it reconciled against was not unique. Two findings, one conclusion — this wasn't a patch job. Part 2 covers what we built instead.

What we'd tell ourselves two days earlier

When a fix requires proving no simpler rule works, the design is the bug. We wrote a paragraph explaining why value-shape matching can't be made correct, and then shipped a sixth fix to it. That paragraph was the finding.

Watch the shape of your fixes, not just their correctness. Bug 4's fix was right, tested and idempotent, and it took the query from twenty lines to five CTEs. Rising complexity in the same spot is the cheapest signal you get that the model underneath is wrong, and it arrives before the proof does.

Count the mechanism's production output before you fix it again. "13 rows ever written, 9 of them wrong" took one query and ended a two-day argument. Any mechanism you're repeatedly patching can be measured, and the measurement is usually cheaper than the next fix.

Ask what happens if you delete it. "238 of 244 overlapping employee-days reconcile with no compensation at all" was the single most valuable number we produced. The counterfactual query — what would this data look like if the code didn't exist — is badly underused.

Trust the checksums your source hands you. The payload contained a total that contradicted what we stored. Free validation, ignored for months.

Silent data loss doesn't leave evidence, so build the harness. Nothing here threw an exception. Every wrong row was written by a green sync. The parity query is the only reason any of it is a story rather than a slowly-drifting table.

Part 2: the append-only ledger that replaced it, the one-line change that made the whole reconciliation problem disappear, and the cutover run that lost 235 employee-days.

Static Site, Live Inventory: Two Sources of Truth That Don't Fight Each Other

David Bartalos — Thu, 04 Jun 2026 12:24:00 +0000

The shop sells two things: original watercolour paintings (one of each, ever) and open-edition prints. Originals sell out permanently. Prints don't. The question the architecture has to answer is: how does the site know which originals are still available, and how quickly does it reflect a sale?

The naive answer is to fetch from Medusa at build time and bake the sold status into the static HTML. That works until a painting sells between deploys — the site shows it as available, someone clicks "Add to cart," Medusa rejects the request, and the experience is broken. Rebuilding on every sale is an option, but it couples the storefront's uptime to Medusa's webhook reliability.

The naive answer in the other direction is to fetch from Medusa client-side on every page load and render nothing until the data arrives. That's a spinner on a content site. The paintings are the product. Making visitors wait to see them is the wrong trade.

The actual solution has two layers with clearly defined responsibilities.

Layer 1: build-time hint

Every painting in the content collection has an optional sold field in its frontmatter:

---
title: "Autumn Morning"
sold: true
---

When sold: true, the build-time effects are:

Catalog feed: the original variant is excluded from the Google/Meta product catalog TSV. No point advertising something that can't be bought.
JSON-LD: the product structured data uses OutOfStock for availability. Google doesn't index it as a purchasable product.
OG tags: product:availability is set to "oos".

None of these affect the shop UI. A sold-out painting still has a page, still shows in the gallery, still shows the print options. The sold flag is a build-time signal to external systems, not a UI gate.

The flag is kept in sync automatically. bun run sync reads stocked_quantity from Medusa for every product and patches the frontmatter:

↕ autumn-morning → sold: true
↕ winter-estuary → removed sold flag (back in stock)

↕ in the output means a patch was written. Running sync before deploying keeps the catalog and structured data accurate without manual frontmatter edits.

Layer 2: runtime hydration

The shop grid is static Astro HTML. Every card renders with data-status="available" by default — the optimistic assumption. The original price, the "Add to cart" button, the availability badge: all rendered at build time, all assuming the painting is available.

After the page loads, a plain <script> block calls the Medusa store API and patches each card:

async function hydrateAvailability() {
  const products = await fetchProducts() // cached promise, fires once per page

  cards.forEach((card) => {
    const handle = card.dataset.handle
    const availability = products.get(handle)
    const originalAvailable = availability?.originalAvailable ?? true // optimistic fallback

    card.dataset.status = originalAvailable ? 'available' : 'sold'

    if (!originalAvailable) {
      card.querySelector('.variant-original')?.setAttribute('data-sold', '')
    }
  })
}

hydrateAvailability()

data-sold on the original variant row triggers CSS: the price gets a strikethrough, the row fades slightly, the "Add to cart" button disappears. The card stays in the grid — sold originals are visible as FOMO and context, not hidden. Prints on the same painting remain fully purchasable.

No framework. No Svelte island. No loading state. The grid is visible and interactive immediately; the sold indicators arrive silently a few hundred milliseconds later without shifting anything.

What happens when Medusa is down

The optimistic fallback on line 6 above is intentional. If fetchProducts() fails — Medusa is restarting, the VPS is briefly unreachable — every card stays data-status="available". Visitors can browse. The cart still works. If someone tries to add a sold original, Medusa rejects the cart request and the UI shows the error then.

The worst case is a few extra "sorry, sold out" cart errors during a brief backend outage. The alternative — blocking the grid on a Medusa response — would mean a broken shop during any downtime. For a low-traffic art shop, optimistic-with-graceful-degradation is the right default.

The filter system

The shop grid has filters: show all / available originals only / prints only / by theme. The filters use data-hidden (not display:none) driven by data-status and data-tags:

function applyFilters() {
  cards.forEach((card) => {
    const hidden = shouldHide(card, activeFilter, activeTags)
    card.dataset.hidden = String(hidden)
  })
}

CSS transitions on data-hidden give the appearance/disappearance a fade rather than a jump. The "available originals" filter count updates after hydrateAvailability() completes — it reads the live data-status values, not the build-time assumptions.

Why two layers instead of one

Build-time data is fast and free — it's just frontmatter. Runtime data is live and accurate. The split is about matching the right data source to the right consumer:

External systems (Google, Meta) see the build-time state. They cache it. A slightly-stale catalog entry means a sold original might briefly appear in Google Shopping — a bad click, but not a broken purchase (Medusa rejects the cart). Running bun run sync before each deploy keeps the gap small.
The shop UI sees the runtime state. A "available" badge on an actually-sold painting is a much worse experience — someone browses, adds to cart, gets rejected. That one must be live.

bun run sync closes the gap before each deploy, so the build-time state is never more than one deploy behind. In practice, originals sell slowly enough that the gap is rarely more than a few hours.

If you're applying this on a different stack, the principle generalises: optimistic static HTML + silent runtime patch + accept that the worst case is a cart error. The trick is being honest about which data source serves which consumer, and not making the visitor wait for the slow one.

When this pattern doesn't fit

Optimistic-with-graceful-degradation is the right default for a low-traffic shop where originals sell on the order of days. It's the wrong default for a flash sale, a sneaker drop, or anything where stock depletes in seconds and a misleading "available" badge would mean hundreds of cart errors a minute. At that point the spinner stops being a UX failure and starts being an honest signal — "we're checking, because the answer changes faster than we can ship HTML."

That's the full series. The stack behind nadiapoe.co.uk: Astro 6 + Svelte on Cloudflare Pages, Medusa v2 on a €3.29/mo Hetzner VPS, and a handful of patterns that took longer to figure out than they should have.

Transactional Email in Medusa v2 Without the Notification Module

David Bartalos — Tue, 02 Jun 2026 12:18:00 +0000

Medusa v2 has a notification module. It's designed exactly for transactional email — you register a provider, configure templates, and the module fires on order events. There's one problem: there's no official Resend provider.

The community providers that exist are hit-and-miss on maintenance. The official SendGrid provider exists, but its setup felt heavier than the problem warranted. Resend, on the other hand, seemed easy enough to implement directly — clean API, good TypeScript types, and 3,000 emails a month free and a dollar per thousand beyond that.

This is what I did instead: skip the notification module entirely.

The approach

Medusa's event system still works without the notification module. Any subscriber can listen to order.placed and do whatever it wants. So the setup is:

An order.placed subscriber that calls the Resend SDK directly.
The email template inlined in the subscriber file.
A dev-redirect pattern so order emails in staging don't land in real inboxes.

No notification module configuration. No provider abstraction. Just a function that runs when an order is placed and sends an email.

The ESM trap: why the template lives inline

The natural instinct is to put the HTML template in a separate file and import it:

// ❌ This fails at runtime
import { orderConfirmationTemplate } from '../templates/order-confirmation'

Medusa's API uses "module": "Node16". Cross-file imports for subscriber dependencies work in dev and fail in production with ERR_MODULE_NOT_FOUND. I didn't fully diagnose which resolver did what — inlining everything sidesteps the question entirely.

The fix is to keep subscriber files completely self-contained. Everything the subscriber needs — template, helpers, types — lives in the same file.

The same rule applies to import type. With "module": "Node16", plain import { SomeType } for TypeScript types isn't guaranteed to be erased from the compiled output. Always use import type { ... } for type-only imports in subscriber files.

The subscriber

// api/src/subscribers/order-placed.ts
import type { SubscriberArgs, SubscriberConfig } from '@medusajs/framework'
import { Modules } from '@medusajs/framework/utils'
import { Resend } from 'resend'

export default async function orderPlaced({ event, container }: SubscriberArgs<{ id: string }>) {
  const orderModule = container.resolve(Modules.ORDER)
  const order = await orderModule.retrieveOrder(event.data.id)

  const isDev = process.env.PUBLIC_ENV === 'development'
  const toAddress = isDev
    ? process.env.EMAIL_DEV_REDIRECT!
    : order.email

  const resend = new Resend(process.env.RESEND_API_KEY)

  await resend.emails.send({
    from: 'Nadia Poe <hello@nadiapoe.co.uk>',
    to: toAddress,
    subject: `Order confirmed — ${order.display_id}`,
    html: buildOrderEmail(order),
  })
}

export const config: SubscriberConfig = {
  event: 'order.placed',
}

function buildOrderEmail(order: any): string {
  // template inlined here — plain HTML string, no JSX, no template engine
  return `<!DOCTYPE html>...`
}

The EMAIL_DEV_REDIRECT pattern is worth keeping. In development, every order confirmation — regardless of who placed the order — goes to a +dev alias on your own email address. You see the real email, the real order data, without polluting a customer inbox. In production, toAddress is the customer's email. The guard is a single ternary.

The contact form: no SDK needed

The storefront has a contact form that also sends via Resend. For a one-off form POST, installing the Resend SDK client-side isn't worth it — the API is just an HTTP endpoint:

// client/src/pages/api/contact.ts
import { env } from 'cloudflare:workers'

export const POST: APIRoute = async ({ request }) => {
  const { name, email, message } = await request.json()

  await fetch('https://api.resend.com/emails', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${env.RESEND_CONTACT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      from: 'nadiapoe.co.uk <hello@nadiapoe.co.uk>',
      to: env.EMAIL_CONTACT_TO,
      reply_to: email,
      subject: `Message from ${name}`,
      text: message,
    }),
  })

  return new Response(null, { status: 204 })
}

env comes from cloudflare:workers — the live runtime binding, not import.meta.env. The reply_to is set to the sender's address so replying in Gmail works naturally.

Four API keys, not one

One API key for everything is convenient until you need to rotate it, audit usage, or debug which part of the system sent a bad email. The setup uses four keys:

Key	Used by	Environment
`medusa-notifications-prod`	order subscriber	production
`medusa-notifications-dev`	order subscriber	staging
`storefront-contact-prod`	contact form	production
`storefront-contact-dev`	contact form	staging

Resend shows per-key send history. When something goes wrong you can see exactly which key sent what, without digging through logs.

DNS: the boring bit that breaks everything if you skip it

Resend's Cloudflare integration auto-configures DKIM and SPF. The setup that works:

SPF: v=spf1 include:_spf.resend.com ~all on the root domain
DKIM: Resend generates the records; Cloudflare auto-applies them via the integration
DMARC: v=DMARC1; p=reject; rua=mailto:hello@nadiapoe.co.uk — p=reject means unauthenticated mail claiming to be from nadiapoe.co.uk gets dropped, not delivered
MX + inbound: Cloudflare Email Routing with a catch-all rule forwarding to Gmail. hello@nadiapoe.co.uk works as a real inbox without running a mail server.

The Resend SMTP credentials (smtp.resend.com:587, username resend, password = the API key) let Gmail send as hello@nadiapoe.co.uk via "Send mail as" — so replies from the shop's inbox come from the right address.

What you give up

The notification module's abstraction is useful if you ever want to swap providers or add multiple notification channels (email + SMS + push). Bypassing it means that flexibility lives in your subscriber code instead. For a shop that will always send via Resend, that's a fine trade. If the requirements change, the migration is straightforward: add the official provider when it ships, move the template, delete the subscriber.

Live shop: nadiapoe.co.uk.

Three Cloudflare Patterns Earned the Hard Way

David Bartalos — Thu, 28 May 2026 12:13:00 +0000

Every Cloudflare product is well-documented in isolation. The interesting bugs are always at the seams between two products — the edge injecting scripts into HTML that already has a CSP, the WAF inspecting requests for media served from R2, Vite substituting variables at build time that don't exist yet on Pages. These three patterns are from running nadiapoe.co.uk on Astro 6 + Pages, with R2 hosting the artwork media.

1. CSP nonces via middleware, not build-time hashes

The textbook way to do a strict CSP on a static site is build-time hashing: scan every inline <script>, hash it, list the hashes in the CSP header. Cloudflare even has a build hook to do it for you.

For an art site, Bot Fight Mode is non-negotiable — automated scrapers harvesting painting images are a real concern, and Cloudflare's challenge platform is the cheapest layer of protection available. But it breaks the moment you enable it. Cloudflare's edge injects the challenge widget at request time with a rotating token. The hash changes per request. Your CSP rejects it. Half your visitors get a broken challenge widget because the static hash you baked in this morning no longer matches.

The fix is a per-request nonce. Astro 6's middleware runs as a Worker; Workers have HTMLRewriter. From client/src/middleware.ts:

export const onRequest = defineMiddleware(async (context, next) => {
  const response = await next()
  if (typeof HTMLRewriter === 'undefined') return response
  if (!response.headers.get('content-type')?.includes('text/html')) return response

  const nonceBytes = crypto.getRandomValues(new Uint8Array(16))
  const nonce = btoa(String.fromCharCode(...nonceBytes))

  const rewritten = new HTMLRewriter()
    .on('script', { element(el) { el.setAttribute('nonce', nonce) } })
    .transform(response)

  const headers = new Headers(rewritten.headers)
  headers.set('Content-Security-Policy', buildCsp(nonce))
  // private cache — never share a nonce between users
  headers.set('Cache-Control', 'private, max-age=1500, stale-while-revalidate=7200')

  return new Response(rewritten.body, { status: rewritten.status, headers })
})

Two non-obvious bits:

Cloudflare reads the nonce from your CSP header and stamps its own injected scripts with it. Undocumented but stable. This is the only reason the pattern works at all — without it, the challenge widget would still get blocked.
Cache-Control: private is load-bearing. A shared cache that served one user's nonced HTML to another would only break the cached client (their nonce doesn't match the newly injected scripts), but it's still a bug. private keeps Cloudflare's edge from doing this.

2. Server secrets via `cloudflare:workers`, not `import.meta.env`

Astro has two environments: build-time and runtime. Vite resolves import.meta.env.SOMETHING at build time by string substitution. If the value isn't in .env at build time — and Cloudflare Pages doesn't expose dashboard-configured secrets during the build — Vite bakes in the literal undefined.

Worse: it does this silently. No warning, no error. The contact form deploys, the Resend SDK call fails with "API key undefined," and you spend an hour checking the Cloudflare dashboard before realising the value never made it into the bundle.

Astro 6 has two ways to read server-side env at runtime. They are not equivalent:

// ❌ Broken in Astro 6 — Astro.locals.runtime.env was removed
const apiKey = Astro.locals.runtime.env.RESEND_API_KEY

// ✅ Works
import { env } from 'cloudflare:workers'
const apiKey = env.RESEND_API_KEY

The cloudflare:workers module is provided by the Workers runtime. env is the live binding object — the same one your wrangler.toml and Cloudflare dashboard configure. No build-time substitution; nothing is baked in.

Client-side code (anything in a Svelte component or a non-SSR Astro page) keeps using import.meta.env.PUBLIC_*. Those are baked at build time on purpose — they're public.

One gotcha: bindings may be absent in local dev without a full Pages emulation setup. Wrap access in try/catch when the value is optional:

function getDb() {
  try { return (env as any)?.DB ?? null } catch { return null }
}

3. R2 hotlink protection with an inverted WAF rule

Print fulfillment runs through Prodigi — a print-on-demand provider that produces and ships prints worldwide. When an order comes in, Medusa generates a time-gated presigned R2 URL pointing to the high-resolution print master and hands it to Prodigi. Prodigi fetches the file, prints it, ships it. The URL expires. Nobody else ever needs access to that file.

The high-res masters live in R2. Keeping them protected means ensuring those presigned URLs can only be opened by the intended recipient in the intended window — not scraped, not re-shared, not embedded on another site. The WAF rule is the layer that enforces origin intent on the media domain.

The naive WAF rule is "block if the Referer header doesn't match nadiapoe.co.uk."

It works until you try to:

Open an image URL directly in a browser tab — no Referer, blocked.
Load a <video preload="metadata"> tag — some browsers send no Referer on media requests, blocked.
Test on a *.pages.dev preview deployment — Referer is <branch>.nadiapoe-co-uk.pages.dev, blocked.

The fix is to invert the logic: block only when a Referer exists and isn't in the allowlist.

(http.host eq "media.nadiapoe.co.uk")
and (len(http.referer) > 0)
and not (http.referer contains "nadiapoe.co.uk")
and not (http.referer contains "localhost")
and not (http.referer contains ".pages.dev")

Empty Referers pass — direct nav, preload requests, RSS readers. Preview deployments pass via the .pages.dev wildcard. Real hotlinks from other sites get a 403.

If you script your WAF rules via the Cloudflare API (which you should, for reproducibility), two quirks not mentioned in the error messages: a PUT to the rulesets endpoint must not include kind or phase (they're implicit from the URL), and rate-limit characteristics on the free plan must include cf.colo.id because counts are per-colo, not global.

Closing

The seams are where you learn things. Check the network tab when behaviour is wrong — Cloudflare adds its own response headers that tell you which rule fired, which challenge ran, which WAF block triggered. The answers are usually there; they're just not in the docs.

nadiapoe.co.uk runs on all three patterns in production.

Medusa v2 in Production: Three Bugs That Each Ate a Weekend

David Bartalos — Tue, 26 May 2026 12:13:00 +0000

Production bugs don't care that your infrastructure costs €3.29/mo.

Medusa v2 is genuinely good — the headless model, the workflow engine, the v2 admin API are all a step up from v1. But the docs surface 80% of what you'll hit, and the remaining 20% is where weekends go. These are three bugs I hit running nadiapoe.co.uk's shop on Medusa v2. All three had simple fixes. None of the fixes were obvious.

Bug 1: The `Date.parse` shipping rule trap

The shop has two delivery options — a small incentive to encourage slightly larger print orders:

Standard delivery — £4.50, always available.
Free delivery — £0, available when cart_subtotal >= 60.

A £100 cart. Free Delivery disappears. Standard gets auto-selected. Refresh, clear cart, retry — same result. Stranger: a £10 test cart shows Free Delivery correctly. The rule is set up right. The data in the database looks right. Something in the middle is broken.

That something is buried in @medusajs/fulfillment/dist/utils/index.js. The comparator for gte / lt rules does this:

const left = Date.parse(a)
const right = Date.parse(b)
if (!isNaN(left) && !isNaN(right)) {
  return new Date(left) < new Date(right)   // date branch
}
return Number(a) < Number(b)                // numeric branch

That looks fine until you remember what Date.parse does to bare integer strings:

Date.parse("60")    // → -315619200000     (year 1960 — 2-digit year expansion)
Date.parse("100")   // → -59011459125000  (year 100 AD)
Date.parse("60.00") // → NaN

A £100 cart with cart_subtotal = "100" and a rule value of "60" evaluates as Date(100 AD) < Date(1960) → true. The "show this option when subtotal is below £60" condition fires on a cart worth nearly twice the threshold. Free Delivery gets stripped.

The fix is one toFixed(2). From api/src/workflows/shipping-options-context.ts:

import {
  listShippingOptionsForCartWorkflow,
  listShippingOptionsForCartWithPricingWorkflow,
} from "@medusajs/medusa/core-flows"
import { StepResponse } from "@medusajs/framework/workflows-sdk"

const injectCartSubtotal = async ({ cart }: { cart: any }) =>
  new StepResponse({ cart_subtotal: (cart.item_total ?? 0).toFixed(2) })

listShippingOptionsForCartWorkflow.hooks.setShippingOptionsContext(injectCartSubtotal)
listShippingOptionsForCartWithPricingWorkflow.hooks.setShippingOptionsContext(injectCartSubtotal)

The rule values stored in the database have to match the same shape — "60.00", not "60". Once both sides are decimals, Date.parse returns NaN and the evaluator falls through to the numeric branch.

Bug 2: There are two shipping workflows, and you have to hook both

Look at the snippet above again. There are two workflow hooks, not one. That's not an accident.

By default Medusa v2's shipping rule evaluator only sees is_return and enabled_in_store. Anything cart-financial — cart_subtotal, item_count, currency, region — has to be injected via the setShippingOptionsContext hook. That part is documented.

What isn't documented: there are two workflows that evaluate shipping options.

listShippingOptionsForCartWorkflow runs when the storefront fetches options to display.
listShippingOptionsForCartWithPricingWorkflow runs inside addShippingMethodToCartWorkflow when a customer actually selects an option.

Hook only the first and the storefront shows Free Delivery correctly. The customer selects it, gets a 400 back — because the second workflow has no cart_subtotal in its context, the rule fails, and Medusa rejects the assignment as "option not available for this cart." The response body is generic. The server logs are silent.

Cost: one Friday evening.

Bug 3: The workaround that aged badly

Some workarounds need an expiry date. This one didn't have one.

Early Medusa v2 had two related bugs — #11766 and #13301. Stripe charged the card, webhooks fired, but order.paid_total stayed at 0 and the payment status never advanced past pending. Every order had to be manually marked paid in the admin — which also meant no order confirmation email fired, since the email subscriber was gated on a completed order. Customers paid, heard nothing, and had to be chased manually.

I patched it with a subscriber on order.placed that called capturePaymentWorkflow directly:

// api/src/subscribers/order-capture-payment.ts  (DELETED in 2026-05)
export default async function orderCapturePayment({ event, container }) {
  // ...fetch payment collection, mark fully captured, refresh order
}

It worked. Shipped.

Then Medusa v2.11.1 landed and fixed both upstream bugs. The subscriber kept running — double-firing the capture (harmless, since the payment was already captured) but also re-emitting order.placed. That re-emission triggered the email subscriber a second time. Every customer started getting two identical confirmation emails.

I didn't notice until v2.14.2, months later, when an unrelated change made the second order.placed event log a warning. The fix was a one-line deletion. The lesson cost more than the bug did.

Every workaround for a third-party bug needs three things:

The upstream issue URL in a comment — so future-you knows why it exists.
A version check or feature flag to disable it — so it can be switched off without deleting it immediately.
A note to revisit on the next major upgrade of that dependency.

I had #1. I didn't have #2 or #3. The duplicate emails probably did 30 minutes of brand damage before I caught it. The fix was free. The discipline to set expiry dates on workarounds isn't instinctive, but it's cheap.

One note if you're starting a Medusa v2 project: the v1 docs URL still resolves and Google ranks both. Make sure the URL doesn't have /v1/ in it before you copy a snippet — the APIs changed significantly between versions.

Live shop: nadiapoe.co.uk.

The Hosting Rejection Tour: Render, AWS EC2, Oracle, and How I Ended Up on a €3.29/mo VPS

David Bartalos — Tue, 19 May 2026 12:17:00 +0000

Before the stack worked, three hosting options failed. Each one looked perfect on paper. Each one had a specific, concrete reason it couldn't work. This is the rejection tour.

The constraint: Medusa v2 is stateful. It needs PostgreSQL, Redis for BullMQ, and enough RAM to run the event bus and workflow engine without getting killed. That rules out serverless. (Medusa can technically start without Redis — it falls back to an in-process event bus — but that means losing job queuing, workflow retries, and reliable event delivery. Fine for a quick local demo; not something you want processing real orders.) It needs persistent storage, a real process manager, and a consistent IP for outbound webhook validation. Every "just deploy it for free" option assumes your workload is stateless. This one isn't.

Attempt 1: Render

Render's free tier looked fine for a low-traffic shop. 512MB RAM, easy deploys from GitHub — cold starts on the free tier, always-on on the paid plan. The plan was to pair it with Neon for PostgreSQL (generous free tier, serverless scaling) and Upstash for Redis (free tier covers BullMQ at low volume). Three managed services, total cost: $0.

I got Medusa running, ran the setup scripts, and then installed the Prodigi print fulfillment plugin — which loads product mappings and prefetches shipping zones at startup.

OOM kill on boot. 512MB wasn't enough.

The obvious fix is to upgrade the Render service. Their starter plan is $7/mo. That's just the API — Neon and Upstash stay free at low volume, but now I'm at $7/mo for a single service with no room to grow, and I still hadn't solved staging. Render's starter plan is $7/mo per service. Two environments means two API instances: $14/mo before touching the databases.

I could have stripped the fulfillment plugin to fit inside 512MB. But without it there are no print orders — Prodigi integration is how open-edition prints get produced and shipped. Dropping it to hit a RAM limit means the shop sells originals only, which wasn't the brief.

Attempt 2: AWS EC2

After Render, AWS EC2 looked like the right move. A t4g.micro in eu-west-2 (London): 1 GiB RAM, 2 vCPU ARM64 Graviton2, always-on, full SSH access, swap configurable — all within the AWS free tier for the first 12 months. Double the memory of Render's paid plan, at no cost. I built out the full setup: CloudFormation stack, Nginx reverse proxy, Let's Encrypt TLS, systemd service, GitHub Actions CD, health check cron.

It ran. There were a couple of ARM64 quirks — a ts-node source-map crash under Bun that needed TS_NODE_SKIP_SOURCE_MAP_SUPPORT=1, and Node.js auto-limiting the V8 heap to ~512MB on a 1 GiB instance, fixed with NODE_OPTIONS=--max-old-space-size=1024. But Medusa came up, Prodigi loaded, the health check passed.

Then I ran a checkout flow under load. OOM kill.

The 1 GiB ceiling wasn't enough headroom when Prodigi, Medusa, and an active checkout were all competing for memory at once. And the infrastructure complexity — CloudFormation, Nginx config, cert renewal timers, CloudWatch, a manual cutover checklist — was a real ongoing cost for a solo project. After the free year, the bill would be ~$7.90/mo anyway. At that price you can just buy a VPS that has the memory you need and none of the ceremony.

Attempt 3: Oracle Always Free

Oracle's Always Free tier is, on paper, absurd. The A1 Flex shape gives you up to 4 OCPU and 24 GB RAM at no cost, permanently. ARM64, which is what Hetzner's cheapest VPS uses anyway. UK London region available. I signed up.

"The selected shape is not available in this Availability Domain. Please try a different Availability Domain or shape."

I tried every Availability Domain in UK London. Same message. I tried Frankfurt. Same message. I tried Amsterdam. Same.

This isn't a new problem. The Oracle community forum has threads going back two years with hundreds of people reporting A1 capacity unavailable in every European region. Oracle adds capacity occasionally, and it disappears within hours as people snap it up. The forum advice is to script retries and keep trying. I tried that for a few weeks.

The Always Free tier only works if you can actually provision the instance. If capacity is gone, it's gone indefinitely. For a project you want to actually ship, "keep retrying and hope" isn't a deployment strategy.

What actually worked: Hetzner CAX11

Hetzner's CAX11 is €3.29/mo. ARM64, 2 vCPU, 4 GB RAM, 40 GB NVMe SSD, 20 TB/month egress included. I signed up, got the server provisioned in about 30 seconds, and had Medusa running the same afternoon.

The setup that's been stable since:

Two systemd services, one box. Dev and production run as separate Medusa instances — different ports, different .env files, different PostgreSQL databases. Caddy sits in front and routes api-dev.nadiapoe.co.uk and api.nadiapoe.co.uk to the right one. Each service restarts automatically on failure. No Docker, no orchestration — just two medusa.service unit files and a Caddy config.

Deploys via GitHub Actions. On push to main, a workflow SSHes in, pulls the latest code, runs bun install and bun run build, and restarts the appropriate service. Under 60 seconds end to end.

Backups to Cloudflare R2. A nightly cron runs pg_dump and uploads the compressed archive to a dedicated R2 bucket (nadiapoe-backups). R2 is already in the stack for media — adding a backup bucket costs nothing extra. Retention is 7 daily dumps on-server, 30 in R2. If the VPS burns down, restoring is pg_restore and a git pull.

The total monthly cost: €3.29. Both environments. All services. Backups included.

The lesson

"Free" hosting for stateful backend workloads usually means one of two things: a RAM ceiling that kills anything real, or a capacity queue where "available" means "available when someone else cancels." For a stateless frontend or a simple API, free tiers are great — Cloudflare Pages handles the storefront for nothing. But the moment you have a process that needs to stay alive, own persistent state, and run at startup, a cheap paid VPS is more reliable than a free tier with asterisks.

Hetzner CAX11 at €3.29/mo is less than most people spend on a coffee a month. It's not free. It's better than free.

One genuine acknowledgement before moving on: the free tiers from Cloudflare, Resend, Neon, and Upstash make it possible to build and prove a business before it earns a penny. They lower the bar for anyone who wants to try something without betting money on it first. That matters, and it's worth saying.

Live shop: nadiapoe.co.uk.

Blazingly Fast Ecommerce Stack for Less Than a Coffee a Month — No Marketplace, No Platform Cut

David Bartalos — Mon, 18 May 2026 06:30:00 +0000

If you've ever looked at a marketplace's fee page and felt your eye twitch, this post is for you.

The major selling platforms take their cut from every angle — transaction fees, listing fees, monthly subscriptions, payment processing. The percentages vary but the direction doesn't: a meaningful slice of every sale goes to infrastructure you don't own or control. And that's before the visibility problem: on a marketplace of millions of listings, the algorithm decides whether your work gets seen at all.

My girlfriend had been listing her work on one of the big marketplaces for a while — barely any traffic, zero sales. The fees were almost beside the point. I saw the disappointment and floated the idea: her own site, her own corner of the internet — and I'd build it.

I'm a software engineer. I like a challenge. So I set out to give it a shot. The result runs at €3.29/mo for all backend infrastructure. The site is live at nadiapoe.co.uk. Here's the stack and the decisions behind it.

The constraints

Artwork loads instantly. Watercolours are the product. A 2-second LCP would send visitors away before they saw a painting. No image-CDN that stamps a watermark on the hero image, no spinner while the page wakes a cold serverless function.
No third-party watermarks. Image-CDN convenience — Cloudinary, imgix — isn't worth a logo in the corner of the hero. This is an artist's portfolio. The paintings deserve respect.
Real commerce, not a payment link. Multi-currency (GBP / EUR / USD / AUD), international fulfillment for prints, originals shipped from the UK. A Stripe payment link in the Instagram bio wasn't going to cut it.
No tracking, no cookie banner. The site doesn't follow visitors. No analytics cookies, no third-party pixels, no consent popup to dismiss before you can see a painting. Purchase data goes only as far as it needs to: card details to Stripe, a shipping address — originals are shipped by us from the UK, prints via a print-on-demand provider for international orders. Nothing retained beyond what's needed to get the order out the door.
Indie budget. One artist, no team, no investor. Anything more than ~£10/month total infrastructure is a recurring tax on the creative work. That ceiling shaped every hosting decision in the stack.

The stack, piece by piece

The infrastructure splits cleanly across two providers.

Cloudflare (free tier)

Everything the visitor touches runs on Cloudflare. CDN and WAF sit in front of everything — Bot Fight Mode, rate limiting, R2 hotlink protection. Behind them:

Cloudflare Pages hosts the Astro 6 storefront. Static by default, per-route SSR where needed (checkout callbacks, contact form, structured data feeds). The painting pages are pure HTML — the entire collection ships zero JS until the cart is opened.

Cloudflare R2 stores all images and process videos. Zero egress fees, served from a custom domain (media.nadiapoe.co.uk). Videos are pre-encoded to four variants locally with ffmpeg (720p desktop, 480p mobile, JPEG poster, 64×64 thumb) and uploaded via wrangler. No URL transforms, no image-service quotas to exhaust.

Cloudflare D1 is the edge SQL database — one table, one purpose: like counts. The like button stores your choice in localStorage and increments a counter in D1. No cookies, no tracking, no consent popup. You see the count; nothing sees you.

Hetzner VPS — €3.29/mo

Everything commerce-related runs on a single Hetzner CAX11: 2 vCPU ARM64, 4 GB RAM, 40 GB NVMe, 20 TB/month egress. On it:

Medusa v2 — the commerce backend. Dev and prod as separate systemd services, both reverse-proxied by Caddy.
PostgreSQL — orders, products, customers.
Redis — BullMQ event bus and workflow engine.

Render, AWS, and Oracle Always Free each failed for a different specific reason. Hetzner just works.

One gap in Medusa v2 worth knowing: there's no official Resend provider. Order confirmation emails skip the notification module entirely and call the Resend SDK directly from an order.placed subscriber.

Third-party services

Stripe handles payments across four currencies (GBP / EUR / USD / AUD). Cloudflare injects cf.country into a <meta> tag at the edge; the storefront reads it to pick the matching Medusa region and present prices in the local currency. User override persists in localStorage.

Resend handles transactional email — 3,000 emails/month free, then $1/1,000.

The interactive layer

Svelte islands handle the cart drawer, quantity controls, painting gallery, and region selector. Nano-stores (cartStore, cartUpdating, regionStore) keep islands in sync without a framework router.

The shop grid itself is static Astro HTML — no Svelte involved. The paintings are the product; a visitor should see the full collection immediately, not wait on an inventory check before anything renders. So every card defaults to "available," then a plain <script> tag calls the Medusa API in the background and patches data-status on each card to flip sold originals to a faded state. No layout shift, no spinner, no framework overhead for a read-only grid.

One Astro 6 gotcha that cost an afternoon: server-side secrets must come from import { env } from 'cloudflare:workers'. The old Astro.locals.runtime.env was removed and import.meta.env silently bakes undefined for server-only vars. No build error, no runtime warning — just missing data in production.

What it actually costs

Backend hosting: €3.29/mo — both staging and production Medusa instances, PostgreSQL, Redis, Caddy, automated nightly backups to Cloudflare R2. Frontend, CDN, edge SQL, object storage, WAF, analytics: free tier. The metered costs are Stripe (1.5–2.9% per transaction — unavoidable regardless of platform, but at least there's no extra platform cut on top) and Resend (3,000 emails/month free, then $1/1,000).

Compare that to a typical marketplace taking 6–7% on a £150 original watercolour — that's £9–10 per sale, forever, to infrastructure you don't own. At even modest volume the self-hosted setup pays for itself inside the first month.

Will this survive a traffic spike? Honestly, no idea — this shop has never been Slashdotted, and a 2 vCPU ARM box with 4 GB RAM is not going to win any load test. But if it ever buckles under the weight of people trying to buy original watercolours, upgrading the VPS will be the easiest problem on the list that day.

One snippet worth stealing

This pattern only works because the HTML is served through a Cloudflare Worker — but if you're already on Cloudflare Pages, you have that for free.

The full CSP is set per-request with a fresh nonce, injected into every <script> tag at the edge. No build-time hash dance, no list of inline script hashes to maintain. From client/src/middleware.ts:

export const onRequest = defineMiddleware(async (context, next) => {
  const response = await next()
  if (typeof HTMLRewriter === 'undefined') return response
  if (!response.headers.get('content-type')?.includes('text/html')) return response

  const nonceBytes = crypto.getRandomValues(new Uint8Array(16))
  const nonce = btoa(String.fromCharCode(...nonceBytes))

  const rewritten = new HTMLRewriter()
    .on('script', { element(el) { el.setAttribute('nonce', nonce) } })
    .transform(response)

  const headers = new Headers(rewritten.headers)
  headers.set('Content-Security-Policy', buildCsp(nonce))
  return new Response(rewritten.body, { status: rewritten.status, headers })
})

Cloudflare's own bot-fight challenge scripts get whitelisted automatically — they read the nonce from the CSP header and stamp themselves with it. On a static-only setup you're stuck with hashes, and those break the moment Cloudflare rotates a challenge token. The Worker approach sidesteps that entirely.

The site is nadiapoe.co.uk if you want to see the result.

DEV Community: David Bartalos

Replace the Heuristic With a Boundary: Rebuilding a Leave Table as an Append-Only Ledger

Start from the read path

One row per entry, keyed on the amount, never updated

seq, and why it counts per group

NUMERIC, not REAL, once it's in the key

The boundary that replaced heal

What that deleted

The assumption we couldn't eliminate

The invariants we run

The cutover is where the risk actually went

Where this actually stands

What the design taught us

Nine of Thirteen Corrections Were Wrong: The Fix That Came With a Proof It Couldn't Work

The setup

The parity check

Two days of whack-a-mole

The sentence that ended it

Measuring instead of fixing

The twist

Why the tests were green

What we'd tell ourselves two days earlier

Static Site, Live Inventory: Two Sources of Truth That Don't Fight Each Other

Layer 1: build-time hint

Layer 2: runtime hydration

What happens when Medusa is down

The filter system

Why two layers instead of one

When this pattern doesn't fit

Transactional Email in Medusa v2 Without the Notification Module

The approach

The ESM trap: why the template lives inline

The subscriber

The contact form: no SDK needed

Four API keys, not one

DNS: the boring bit that breaks everything if you skip it

What you give up

Three Cloudflare Patterns Earned the Hard Way

1. CSP nonces via middleware, not build-time hashes

2. Server secrets via cloudflare:workers, not import.meta.env

3. R2 hotlink protection with an inverted WAF rule

Closing

Medusa v2 in Production: Three Bugs That Each Ate a Weekend

Bug 1: The Date.parse shipping rule trap

Bug 2: There are two shipping workflows, and you have to hook both

Bug 3: The workaround that aged badly

The Hosting Rejection Tour: Render, AWS EC2, Oracle, and How I Ended Up on a €3.29/mo VPS

Attempt 1: Render

Attempt 2: AWS EC2

Attempt 3: Oracle Always Free

What actually worked: Hetzner CAX11

The lesson

Blazingly Fast Ecommerce Stack for Less Than a Coffee a Month — No Marketplace, No Platform Cut

The constraints

The stack, piece by piece

Cloudflare (free tier)

Hetzner VPS — €3.29/mo

Third-party services

The interactive layer

What it actually costs

One snippet worth stealing

`seq`, and why it counts per group

`NUMERIC`, not `REAL`, once it's in the key

2. Server secrets via `cloudflare:workers`, not `import.meta.env`

Bug 1: The `Date.parse` shipping rule trap