03Decision Systems
A recommendation per style, and a spreadsheet it cannot damage
The spreadsheet was the system of record and was going to stay that way — that constraint was not negotiable, and designing around it rather than against it is most of the work.
The real risk was not a wrong recommendation. It was a script with write access to a live merchandising sheet that 1,900 product rows and several people depend on. Anyone re-running it risked destroying formulas or a colleague's work.
Read everything before writing anything. Two integration layers feed a pipeline whose stages are all pure until the final write plan, which is guarded by a column allowlist, a source fingerprint and per-cell idempotency.
The decision engine is a pure function with no I/O and no clock. Status group, two sales figures, stock, samples, release date, next-season availability and inventory in; an 'ACTION — Reason.' sentence out.
Because it has no dependencies, it is fully testable, and a threshold experiment can run without touching the sheet at all.
Columns are resolved by header text at run time rather than by position, so inserting a column upstream does not silently corrupt the write.
Every run builds a pure write plan first, then asserts that plan touches only an allowlisted set of columns and never the header row. A SHA-256 fingerprint of every source cell, a single in-process run lock, and per-cell idempotency checks sit between the plan and the API call.
A second run over unchanged data writes nothing at all. A Shopify failure mid-run leaves the spreadsheet untouched rather than half-updated. An unmatched row is flagged for human review rather than written as zero sales.
A hand-written Admin GraphQL client mints and refreshes its own OAuth client-credentials token — 24-hour lifetime, refreshed ten minutes early, re-minted and retried on a mid-run 401.
It paces itself against Shopify's calculated query cost and leaky bucket with exponential backoff, jitter and Retry-After handling, rather than guessing at a fixed delay.
A standard run applies itself. A custom-threshold run stops at a results table and requires an explicit confirmation dialog listing every setting that differs from the agreed rule set — so an experiment can never be mistaken for policy.
The sheet is live, shared and full of formulas. The answer was to make the write plan a value the code can inspect before it executes — allowlist the columns, forbid the header row, fingerprint the source, and check each cell for idempotency. A destructive write becomes something you can assert against in a test rather than something you hope does not happen.
The old script used a sample count as a stand-in for 'quantity that can be made', and a proxy date column for 'releases again next season'. Both now read real sources — live inventory, and the next season's tab. Two placeholders quietly wrong for a long time is a good illustration of why a system beats a script.
The app has no sign-in; the deployment boundary is the entire access control. That is stated prominently at the top of the README with a comparison table of four ways to add one, rather than buried. Leading with your system's biggest limitation is what makes the rest of the document trustworthy.
Replaces a Google Apps Script workflow and the manual steps around it: pulling Shopify unit sales for two rolling windows, keying them to the right row by style and colour, hand-typing the date range each sales column covers, and applying the slow-seller rules style by style. A one-off migration endpoint clears the legacy column the old script wrote, showing the affected cell count before confirmation.
The 1,032-line README documents the platform setup step by step, the service-account sharing step and what to ask a Workspace admin when external sharing is blocked, a troubleshooting matrix mapping every user-facing error to its fix, and a 'where to change X' table pointing every tunable to the file that owns it. Design decisions are recorded as rationale in code — 'do not reorder these thresholds without an explicit instruction — the wording is safe to edit, the numbers are not'.
Objective size signals taken from the repository. No impact metrics are claimed that the source does not prove.
Internal tool behind a network boundary. Not publicly reachable.