← The Machine Room · Case File 006 — Factory OS Gen 1 · Running · --:--:-- GST · Gen 2 · Awaiting cutover · Sheet 1 of 8
CASE FILE · THE FACTORY OPERATING SYSTEM · MANUFACTURING / OPS DWG NO. AH-CS-006-B · SECOND EDITION — SUPERSEDES 006-A

An aluminum-duct plant runs tonight on a spreadsheet taught to behave like a database. Its successor refuses to be edited at all.

Case File 006 documents two revisions of one machine. Gen 1 made Smartsheet the system of record for a real factory — 22 serverless functions holding every business rule — and still runs the floor. Gen 2 rebuilds the same order-to-cash spine on an append-only Postgres ledger, drafted and checked, waiting for cutover.

GEN 1 · SMARTSHEET + 22 AZURE FUNCTIONS · RUNS THE PLANT
GEN 2 · POSTGRES · 12 MODULES · APPEND-ONLY LEDGER
BUILT THROUGH STREAM K OF 16 · MIGRATION UNBUILT

NO CUTOVER HAS RUN — AND THIS PAGE SAYS SO
REVOKE
UPDATE, DELETE;
THE TWO VERBS GEN 2'S INVENTORY LEDGER REFUSES —
ENFORCED AT THE DATABASE ROLE, NOT IN APP CODE VERIFIED
Drawn byAbu Huraira Mukhtar
RoleArchitect & Sole Engineer
ClientUAE Aluminum-Duct Plant · Anon.
Build windowG1 2026-01→05 · G2 2026-04→05
StatusG1 Running · G2 Awaiting Cutover
Edition2nd — Old Sheet Ghosted Behind New
SourceG1 ~22K LOC · G2 12 Modules / 26 Migr.
Sheet1 of 8
SHEET 2 OF 8 · ABSTRACTGENERAL NOTES APPLY

01 · One machine, drawn twice

This is the only case file in the drawing office with a second edition: the same factory, the same order-to-cash spine, engineered twice.

The spine both generations share is the plant itself: a customer LPO arrives, production tags are planned, the cutting machine's nesting software emits its manifest, material is mapped and allocated, consumption is recorded, a margin gate decides whether the delivery may bill, and a truck leaves the gate with paperwork that reconciles back to the LPO. Gen 1 built that spine on Smartsheet — the grid the staff already trusted — with every business rule moved out of the sheet into 22 Python Azure Functions. It runs the plant tonight.

Its success is what exposed its ceiling. A spreadsheet is last-write-wins; references rot; line items live as JSON in text columns. Gen 2 keeps the domain and replaces the physics: twelve Postgres modules around an append-only inventory ledger where UPDATE and DELETE are revoked at the database role. It is built through eleven of sixteen planned streams — and the migration that would retire Gen 1 is, deliberately, not one of them yet.

GENERAL NOTES
1 · GEN 1 — 22 AZURE FUNCTIONS · 27 SHARED MODULES · IN PRODUCTION VERIFIED
2 · GEN 2 — 12 POSTGRES MODULES · 26 MIGRATIONS · 63 ADRS / 46 GOTCHAS
3 · SHARED SPINE — LPO → NEST → ALLOCATE → CONSUME → MARGIN → DISPATCH → RECONCILE
4 · CUTOVER — NOT RUN · GEN 1 REMAINS SYSTEM OF RECORD
SHEET 3 OF 8 · FIELD NOTESTHE BEFORE-STATE

02 · Three counts, no truth

At month-end the plant has three counts of the same aluminum coil — the system's, SAP's, and the bin's — and no way to say which one is lying.

The rest of the month leaks in quieter ways. A truck idles at the gate carrying finished duct with no delivery order behind it. A tag was cut against an LPO that never had the balance to cover it. A gross margin was approved on a hand calculation nobody can reproduce. Deliveries ship and the invoices don't follow, because nothing forces them to.

Before Gen 1, all of this lived in Excel and memory: no audit trail, no idempotency, re-keyed piece counts from the cutting software's merged-cell exports. FIG. 1 shows the four leaks as observed. The monthly reconciliation loop that is supposed to close them runs by hand — and returns a recount, not an answer.

THE FOUR LEAKS
1 · UNBILLED REVENUE — PARTS SHIP, INVOICES DON'T
2 · DELIVERIES WITHOUT DOS — FREE PRODUCT AT THE GATE
3 · MATERIAL DISCREPANCY — SYSTEM ≠ SAP ≠ BIN
4 · OVERPRODUCTION — CUT WITHOUT COMMERCIAL COVER
LPO · COMMERCIAL COVER THE FLOOR · CUT THE GATE · TRUCKS INVOICE · BILLED CUT WITHOUT COVER LEFT WITHOUT A DO SHIPPED, NEVER BILLED MONTH-END RECONCILIATION — BY HAND, EVERY MONTH SYSTEM 131.0 · SAP 126.2 · BIN 118.4 — THREE COUNTS, NO TRUTH
FIG. 1 — THE FOUR LEAKS, AS OBSERVED · COUNTS ILLUSTRATIVESCALE — ONE MONTH : ONE RECOUNT
SHEET 4 OF 8 · GENERAL ARRANGEMENT — GEN 1DWG 006-A · SUPERSEDED, STILL RUNNING

03 · The spreadsheet that runs the plant

Gen 1's bet: keep the grid the staff already trusted as the interface — and move every rule that matters out of it, into code.

Smartsheet stayed the UI and the data store; 22 Azure Functions became the brain. Every state change flows through an event backbone — webhook receiver, Service Bus queue, ID-routed dispatcher — with the queue pinned to a batch size of one, because idempotency mattered more than throughput. All 32 sheets sit behind an ID-first manifest: code addresses logical names, the manifest resolves them to immutable physical IDs, and plant staff can rename or reorder anything without breaking a single integration.

The most characteristic station is the margin gate. When consumption is submitted, deterministic costing runs in code — material, a fixed per-SQM cost, a credit-risk buffer, the UAE's 9% corporate tax, checked against the target margin — and the decision goes to a human: an Adaptive Card on the production manager's phone, approve or append a billing-area penalty. The machine computes; the manager decides.

And it worked — which is how its ceiling was found. A spreadsheet is last-write-wins, so concurrent writes could over-allocate stock. References are loose, so integrity rotted quietly. Line items lived as JSON in text columns. The 84 KB manifest, the queue locks, the deterministic idempotency strings — each was platform tax, paying interest. Gen 1's later fixes hardened the platform; none of them could change its physics.

AS BUILT · GEN 1
22 FUNCTIONS · 27 SHARED MODULES VERIFIED
~22K SOURCE LOC · ~26K TEST LOC
~1,050 TESTS ACROSS 57 FILES AUTHORED · RUN NOT VERIFIED
RECONCILIATION — AGGREGATE-DERIVED, IDEMPOTENT: RECOMPUTE + SET; CANCELLATIONS DROP OUT OF THE NEXT SUM
SUPERSEDED BY DWG 006-B — SEE SHEET 5
PHYSICS CEILING — LAST-WRITE-WINS · NO FOREIGN KEYS · NO TRANSACTIONS SMARTSHEET · 32 SHEETS — UI + DATA STORE 84 KB MANIFEST LOGICAL → PHYSICAL IDS — STAFF RENAME ANYTHING, NOTHING BREAKS WEBHOOK ADAPTER THE EU-REGION API — POWER AUTOMATE COULD NOT REACH IT SERVICE BUS · BATCH = 1 ONE MESSAGE AT A TIME — IDEMPOTENCY OVER THROUGHPUT DISPATCHER ID-ROUTED 22 FUNCTIONS ALL BUSINESS LOGIC IN CODE — NONE IN THE SHEET MARGIN CARD → PM APPROVE / APPEND AREA SAP — PEER, NOT MASTER BLOB — DO + NESTING FILES EVERY STATE CHANGE → USER ACTION LOG · EVERY RULE VIOLATION → EXCEPTION LOG, SLA-TRACKED
FIG. 2 — GEN 1 GENERAL ARRANGEMENT · IN PRODUCTIONEVENT BACKBONE — WEBHOOK → QUEUE → DISPATCHER
DETAIL B · SEE FIG. 2, WEBHOOK ADAPTER

The connector that wasn't there

The plant's data residency forced Smartsheet's EU region — a region Power Automate's connector simply cannot reach. The orchestration layer the whole design assumed was unavailable.

Chose to build a custom webhook adapter — receiver → Service Bus → dispatcher — and replace Power Automate orchestration entirely, because accepting the vendor gap meant no event-driven system at all. Cost: more infrastructure to own. Gained: a real queue with dead-lettering routed into the exception log — better plumbing than the tool it replaced.
DETAIL C · SEE FIG. 2, MARGIN CARD

The machine computes, the manager decides

Margin math is fully deterministic and lives in code. The decision to release a delivery stays human — one card, one tap. No model, no automation, sits in the money-release path.

DELIVERY DO-0187 · MARGIN GATEFACSIMILE — FIGURES FICTIONAL
REVENUE · BILLED AREA48,300
MATERIAL COST−29,450
FIXED PER-SQM + CREDIT-RISK BUFFER−8,603
UAE CORPORATE TAX · 9%−922
GROSS MARGIN8.4% — BELOW TARGET
TO REACH TARGETBILL +2.6% AREA
APPROVEAPPEND AREA PENALTY
SHEET 5 OF 8 · SECTION A-A — GEN 2DWG 006-B · CUT THROUGH THE LEDGER

04 · Append-only, or it isn't a ledger

LPO · TAG NEST · PARSE ALLOCATE CONSUME · GM% DO · INVOICE ONE MESSY .XLS → 44 TYPED LINES → SAP CODES INVENTORY_TXN — APPEND-ONLY LEDGER REVOKE UPDATE, DELETE — AT THE DATABASE ROLE ID TYPE SAP CODE QTY · SQM REFERENCE ACTOR SNAPSHOT FLOOR SAP-104 +1,240.000 SAP SYNC · 06-01 system@ducts TXN-0201 ALLOCATE SAP-104 −120.000 ALLOC-0042 · 24 H system@ducts TXN-0202 RELEASE SAP-104 +120.000 CONS-0017 system@ducts TXN-0203 ISSUE SAP-104 −118.000 CONS-0017 supervisor@ducts TXN-0204 ADJUST SAP-104 −3.000 CORRECTION → TXN-0203 storekeep@ducts NET AVAILABLE · SAP-104 — DERIVED BY WALKING THE LEDGER 1,240.000 1,120.000 1,122.000 1,119.000 NO ROW WAS EDITED — THE CORRECTION IS A NEW SIGNED ROW; THE BALANCE RE-DERIVES ONE TAG'S LIFE · INTAKE → INVOICE · EVERY MOVEMENT A SIGNED, ACTOR-STAMPED ROW
FIG. 3 — SECTION A-A · THE LEDGER, ACCRETINGSPECIMEN DATA SYNTHETIC · SCHEMA REAL
BEAT 1 · COMMERCIAL COVER FIRST

1Intake

Nothing is cut without cover. An LPO carries brand line items and a balance; a production tag that would breach it is refused at the form, with the reason — and the database CHECK refuses it again if the form ever lies. Leak four dies at intake.

BEAT 2 · THE FORENSIC BRIDGE

2Parse

The cutting software emits merged cells and floating headers. Gen 1's anchor-based parser — proven in production — is vendored unchanged as an internal service. One real workbook resolves to 44 typed BOM lines, each mapped to a canonical material and SAP code. Test-proven, byte for byte.

BEAT 3 · ALLOCATE, SIGNED

3Allocate

Every resolved code drops an ALLOCATE row into the ledger — quantity signed negative, actor stamped, reserved for 24 hours. Re-running allocation is a no-op: idempotency is a UNIQUE constraint, not a convention the code has to remember.

BEAT 4 · CONSUME · APPROVE · DISPATCH

4Consume

The consumption form arrives prefilled with what was allocated; the supervisor edits differences only, and variance bands flag what drifts. The margin gate recomputes live as the manager moves the inflation slider — spread only across non-straight pieces. Then a delivery order, a gate pass, a proof-of-delivery photo. No truck leaves undocumented.

BEAT 5 · THE CORRECTION — THE THESIS

5Correct

A bin recount finds three square metres less than the ledger says. Gen 1 would have edited the cell. Gen 2 cannot: UPDATE and DELETE are revoked at the database role, so the correction is a new signed row pointing at the row it corrects, and the balance re-derives by walking the ledger. Silent history rewrites aren't forbidden by policy — they are impossible by physics.

DETAIL D · MODULE BOUNDARIES

Boundaries you could extract by

Twelve modules, each owning its Postgres schema. A module's only public surface is its api.ts and Zod contract — no sibling imports, no cross-schema joins, no cross-module transactions; durable messages go through an outbox.

Chose a modular monolith with CI-enforced boundaries — an import-graph walker fails the merge on undeclared edges or cycles (12 modules, 32 declared edges, 0 violations) — because discipline is cheaper than microservices and keeps extraction a one-week option, not a rewrite. Cost: boundary tax on day one. Revisit when a hot module actually needs its own service.
DETAIL E · LEAST PRIVILEGE

Four roles, four blast radii

The app connects as a role that can write business rows but can never UPDATE or DELETE the ledger, and cannot touch DDL. Migrations, analytics and backups each get their own role and login.

Chose four Postgres roles over the tutorial-default single superuser because a leaked connection string should not be able to drop a factory's database — the blast radius of any credential is a written capability matrix. Cost: four credentials to manage. Gained: the append-only invariant lives in the role model itself.
SHEET 6 OF 8 · REVISION HISTORYTWO GENERATIONS, ONE TABLE

05 · What broke, in both generations

Real machines carry revision tables because real machines break. This one broke across two generations — and the pattern differs.

Gen 1 broke where the platform was weak, and each fix hardened the plumbing. Gen 2 broke where all software breaks — constants, edge comparisons, transaction plumbing — and what caught it was machinery built to catch it: a parity audit in CI, edge-pinning tests, concurrency suites. Every row below traces to a commit or a logged decision.

REV
GEN · DATE
WHAT BROKE
THE FIX
TRACE
A
G1 · 2026-01
ORCHESTRATIONData residency forced Smartsheet's EU region — which Power Automate's connector cannot reach. The orchestration layer the design assumed did not exist for this plant.
BUILD THE BACKBONEA custom webhook adapter replaced Power Automate orchestration entirely: receiver → Service Bus → dispatcher, queue batch size one. Gained a real queue with dead-lettering routed to the exception log.
G1 · IMPLEMENTATION PLAN
B
G1 · 2026-05
RECONCILIATIONIncrementing LPO balances per delivery drifted under retries and made cancellations a manual reversal — the balance was a running guess.
RECOMPUTE, DON'T INCREMENTBalances are recomputed from the full delivery aggregate and SET, idempotently. Re-runs converge; cancelled rows simply drop out of the next sum. Self-healing by construction.
G1 · FINAL COMMITS
C
G2 · 2026-04
COSTINGRe-deriving the cost constants from first principles caught a per-SQM constant wrong by about one percent in the live sheet — a sum error inside margin math that was gating real deliveries.
DERIVE, THEN SEEDThe constant was recomputed from its components, corrected, and seeded into Gen 2's constants table with the verified breakdown — the port paid for itself before cutover.
ADR-008
D
G2 · 2026-05
PARITYOne stream persisted only ~30% of a legacy record's fields. Review scored it 4.8/5 and still missed it; the factory operator caught it at acceptance. Human review does not scale to field-level fidelity.
GUARDRAIL, NOT VIGILANCEA legacy-parity audit in CI: every legacy field must be stored, derived, or dropped-with-an-ADR. The merge gate fails on violations. Four specs registered, zero violations standing.
ADR-054
E
G2 · 2026-05
CONCURRENCYNested transactions quietly opened a second database connection — cross-module writes could interleave mid-transaction. A correctness bug in the plumbing everything else stands on.
SAVEPOINT, ONE CONNECTIONNested transaction contexts became SAVEPOINTs on the same connection, pinned by cross-module concurrency tests so the regression cannot return unseen.
3844615 · CC-1
F
G2 · 2026-05
VARIANCELegacy checked variance bands with strict >; the spec said inclusive ≥. A consumption variance of exactly 5.0% read one band too kind — a latent bug for the system's entire life.
SPEC WINSGen 2 implements the inclusive comparison and pins every band edge — 4.9, 5.0, 9.9, 10.0, 10.1 — in tests. The deliberate divergence is documented for any historical re-import.
ADR-062

Rows C through F share an author-unflattering truth worth stating plainly: the reviewer missed some of these, and the guardrails did not. That is the argument for building guardrails — 63 logged decisions and 46 documented gotchas are what let a solo engineer be wrong safely.

DISCIPLINE · GEN 2
63 ADRS · 46 GOTCHAS — LOGGED
PARITY — 4 SPECS · 0 VIOLATIONS
BAND EDGES — PINNED IN TESTS
SHEET 7 OF 8 · APPROVAL PLATEPROVENANCE ON EVERY NUMBER

06 · Checked, stamped — not yet cut over

22Serverless functions running the plant's order-to-cash spine in production tonightVERIFIED · GEN 1
32Spreadsheet sheets behind one ID-first manifest — staff rename anything, nothing breaksVERIFIED · GEN 1
0Boundary violations across 12 modules and 32 declared edges — the import graph is a merge gateVERIFIED · GEN 2
929Tests passing of 1,178 authored, per the build log's last verification runVERIFIED · AS DOCUMENTED
44Typed BOM lines one real cutting-software workbook resolves to, proven in the parser's test suiteVERIFIED · GEN 2
0Legacy fields silently dropped, across four parity specs audited in CI — schema fidelity, not data migrationVERIFIED · SCHEMA FIDELITY

Read the plate against the four leaks. Unbilled revenue: a delivery order cannot be marked invoiced without an invoice behind it. Trucks without paperwork: the gate pass exists only downstream of a DO. Material discrepancy: one append-only ledger over a SAP snapshot floor, so variance becomes signal with an audit trail. Overproduction: refused at intake, by the form and the schema both.

None of these is a business KPI. Hours saved and dirhams recovered are not measured anywhere in either repository, so they are not claimed anywhere on this page.

Discuss a system like this →
NOT ON THIS PLATE
MONEY / HOURS SAVED — NOT MEASURED, NOT CLAIMED
DATA MIGRATED — NONE; STREAM N UNBUILT
SAP RECONCILIATION — PHASE 2, POST-CUTOVER
SHEET 8 OF 8 · CLOSE-OUTPLAIN VOICE

07 · What the drawing doesn't show

The honest close-out: the successor is finished enough to be checked, and it has not replaced anything yet.

Eleven of sixteen streams are built. The two that remain are the consequential ones: the production manager's dashboards, and the data migration itself — parallel run, daily diff reports, cutover. The runbook for that cutover exists in detail, down to "five consecutive clean diffs and sign-off from sales, production and finance." The scripts do not. No row of production data has moved. The last commit on Gen 2 is dated 2026-05-06, and the old machine has kept running the floor every night since.

I show it unfinished because the two-generation arc is the real lesson of this file. Gen 1 proved the domain in production; every invariant Gen 2 enforces in Postgres was first learned the expensive way in a spreadsheet. And replacing a live factory's system of record is a decision with a runbook, not a deploy — the old machine has earned the right to keep running until the diff reports come back clean. What I sell from this drawing is not a cutover story. It is the discipline that makes one safe: an append-only spine, boundaries a CI gate enforces, and a paper trail that caught its own author's mistakes.

UNRESOLVED
STREAM M — DASHBOARDS · UNBUILT
STREAM N — MIGRATION + CUTOVER · UNBUILT
BUSINESS KPIS — NOT MEASURED
GEN 1 — STILL SYSTEM OF RECORD
DRAWN & BUILT BY
ABU HURAIRA MUKHTAR · SOLO · GEN 1 + GEN 2 · 2026
A. H. M.
SHEET 8 OF 8
END OF CASE FILE 006
THE DRAWING OFFICE · AFTER HOURS

Tonight the spreadsheet runs the plant. The ledger is waiting for the word.

If your operation leaks money at month-end — three counts of the same stock, trucks the paperwork never saw, margins approved on a hand calc — the fix starts with an honest drawing of the machine you already run. Bring it.

Start a conversation → ← Back to the machine room
NEXT CASE FILE · 001 ProcessOS — the document machine with a gate → SHEET 1 OF 7