ReturnDesk Puts the Rules in Postgres

No ORM, no TypeScript, no tests. A one-file schema and a database trigger enforce the return lifecycle while the API stays a thin skin.

7 min read · Single contributor · 14 commits • View on GitHub • More from 712Kunal

A wide overhead editorial illustration of a small shop's back-room returns desk. One wooden desk sits alone with a single clerk's chair, a hand-drawn workflow diagram pinned to the wall above it, a stack of unopened parcels to the left, and a tidy row of processed parcels to the right. The illustration establishes the physical metaphor of a returns desk and the theme of a deliberately under-tooled operation, with nothing digital in the frame.
A returns desk is a small, honest machine: parcels in, decisions made, parcels out. ReturnDesk keeps that machine tiny on purpose.
Key Takeaways

A Return Is a Token That Can Only Move Forward

A return in ReturnDesk is a token. It starts as Open, moves to In Review, and then goes to Approved or Rejected. Approved returns carry a resolution (Refund, Replacement, or Store Credit) and eventually reach Completed. Those are the only legal moves.

The surprising part is who decides what is legal. It is not the Express route, and it is not a service method full of if checks. It is a trigger inside schema.sql. The database refuses an illegal transition before the application ever sees an error. The API's job is to ask nicely and relay the answer.

This is a small idea with a large consequence. When the rule lives in the schema, you cannot bypass it by adding a second client, a script, or a background job. Any code that touches the table plays by the same rules, because the rules are part of the table.

The Trigger Is the Guardrail

The trigger fires on updates to the requests table, compares the old status to the new one, and raises an exception if the pair is not an allowed edge in the lifecycle graph. The Express handler in routes/requests.js does not duplicate that logic. It validates the input shape, calls the service, and shapes the response.

A return is a token, transitions are constrained, and the constraint is enforced one layer below where you would expect it.

The same philosophy shows up twice more. Notes are append-only, so the history of a request cannot be quietly rewritten. Deletions are soft, guarded by a check that the request is still removable, so a closed record stays put. In all three cases the protection sits at the storage layer, not in the app.

Twenty-Four Hours and a One-File Schema

ReturnDesk reads like a take-home exercise that quietly outgrew its brief. The README notes the build took roughly a day, and that the brief only allowed a separate backend service. The author built one anyway, then gave it a real lifecycle and a real guard.

The whole migration story is one file. schema.sql is idempotent, so running it again is safe, and migrate.js executes it as a single multi-statement query. There is no migration framework, no versioned history, and no second source of truth about what the database looks like. You read the schema, and you know the system.

The repository is one contributor and fourteen commits. Stars and forks are at zero. None of that changes what the code argues, but it does tell you who is on the hook if something breaks.

A tight close-up editorial illustration of a clerk's hand writing a rounding adjustment in a paper ledger, with a single coin resting beside the entry. The ledger line shows a value rounded to two decimal places. The illustration makes the NUMERIC-to-float-to-rounded-cents tradeoff physical and memorable, framing a single precise correction rather than a whole workflow.
A refund is stored as a precise NUMERIC(10,2) and becomes a JavaScript float in memory. The validator rounds it to cents on the way in, and that rounding is the whole safety margin.

Every Shortcut Was Chosen in Pairs

There is no ORM. All SQL is hand-written inside requestService.js, which is where the business rules and the queries live together. That is a real cost in verbosity and a real gain in transparency. You can read exactly what hits the database.

Two type parsers in db.js are the clearest example of how the constraints were chosen together, not one at a time.

pg.types.setTypeParser(20, (v) => parseInt(v, 10));      // INT8 -> JS number
pg.types.setTypeParser(1700, (v) => parseFloat(v));      // NUMERIC -> JS float

Parsing a Postgres BIGINT into a JavaScript number is usually a mistake, because BIGINT can exceed the safe integer range. Here it is safe for a specific reason: the route layer caps IDs at fifteen digits with /^\d{1,15}$/. Fifteen digits tops out below Number.MAX_SAFE_INTEGER. The parser and the validator were built to fit each other.

The second parser turns a NUMERIC(10,2) refund into a float. That is a genuine precision tradeoff, and the code pays for it on input by rounding with Math.round(refundAmount * 100) / 100 before the value is written. The refund is precise in the database and approximate in memory, and the rounding is what keeps those two facts from disagreeing.

The transaction helper is the other reusable primitive. It checks out a client, begins, runs the callback, commits, rolls back on error, and always releases. One edge case: if the rollback itself throws, that error replaces the original one.

async function withTransaction(fn) {
  const client = await pool.connect();
  try {
    await client.query("BEGIN");
    const result = await fn(client);
    await client.query("COMMIT");
    return result;
  } catch (err) {
    await client.query("ROLLBACK");
    throw err;
  } finally {
    client.release();
  }
}

The routes have no try/catch blocks, and that is deliberate too. Express 5 forwards rejected promises from async handlers straight to the error middleware. The framework change removed the boilerplate, so the boilerplate is gone.

Code You Own vs. Platforms You Rent

The right axis for comparing ReturnDesk is not features. It is deployment and control: whether you install code you can read, rent a hosted service, or bolt a plugin onto someone else's platform.

ProductDeployment & controlWhere the rules liveCustomizationWho operates it
ReturnDesk (this repo)Self-hosted JavaScript you run yourselfA Postgres trigger and one schema fileEdit the source directlyYour team
WooCommerce returns pluginInstalled inside a commerce platformPlugin code and platform hooksPlugin settings and hooksMerchant, inside WordPress
Loop ReturnsHosted SaaSVendor's servers, not visibleConfiguration and integrationsVendor plus merchant
ReturnGOHosted SaaSVendor's servers, not visibleConfiguration and integrationsVendor plus merchant
AfterShip ReturnsHosted SaaSVendor's servers, not visibleConfiguration and integrationsVendor plus merchant

That table is category-level, not a verified feature comparison. The hosted and plugin rows describe whole product categories, not confirmed competitors of this repository, and none of them were verified against ReturnDesk's actual code. The point is the shape of the trade: renting a returns platform buys you integrations and support; owning the code buys you the ability to read and change the rules, and the obligation to run them.

What It Honestly Does Not Do

The minimalism has a bill, and the code is candid about it. These are the costs of the choices above, not a takedown.

Read together, these are the same trade stated twice. ReturnDesk spends its safety budget in one place, the database, and accepts thin margins everywhere else. It is a coherent argument that a small, honest system can be assembled from primitives, and that the lifecycle belongs in the schema. Whether you would ship it is a separate question from whether the argument holds.