This is a book about an architecture. It is a book about building software for small and medium businesses that does not ask the business to change how it works. It is a book about wrappers: thin, scheduled, stateless programs that read a spreadsheet, perform governed actions, and write results back into the same spreadsheet the business already uses.
The architecture described here is in production today at ColdCode Si Labs in Harare. Three products — Tapstall (payment rails), Bidfold (tender intelligence), and STPi (recruitment automation) — are built this way. Together they serve over 400 paying customers, process thousands of transactions per month, and run on five-dollar-a-month servers. The wrapper code for each product is under 1,200 lines of Python. None of the products has a dashboard for the operator. The spreadsheet is the interface.
This book is a companion to The Governable Enterprise (Garikai, 2026), which lays out the four pillars of governable autonomous systems: Evidence, Authority, Resources, and Recovery. You do not need to have read that book to understand this one — the patterns here are self-contained — but the governance controls described there (budgets, reconciliation, pause, kill switches, approval gates) are applied concretely here to the specific case of spreadsheet- wrapped systems.
This book is written for three readers:
The builder who is tired of shipping dashboards nobody uses. If you have ever built a web application, shipped it, and watched users export the data into Excel to do their actual work, this book explains why and shows you a different way.
The technically competent operator of a small business who already uses a spreadsheet to run things and wants to add automation without migrating to an ERP or hiring a developer full-time. The code examples are short and straightforward.
The student or engineer who has been taught that spreadsheets are a toy that real systems replace. They are not. They are the most successful end-user programming environment in the world, and they deserve better than to be dismissed as legacy.
Part I makes the argument. It explains why spreadsheets are already the interface for most businesses, why asking users to migrate is a tax most will not pay, and what a spreadsheet actually is from a software perspective. Read it even if you already agree.
Part II is the architecture. Seven short chapters lay out the wrapper pattern, the column schema, the read/write boundary, cadence binding, custody rules, and the approval column. These are the core chapters.
Part III walks through the three ColdCode Si Labs products built this way — Tapstall, Bidfold, and STPi. These chapters are concrete: specific column names, specific cron schedules, specific failure modes.
Part IV is the how-to: choosing your substrate, setting up the five columns, writing the wrapper code, applying governance, handling sheet-specific failures, migrating when (and if) you outgrow the sheet, and a closing chapter that argues for the end of the dashboard.
This is not a “no-code” book. You will need to write code — between 200 and 1,200 lines of it for a useful wrapper.
The code is simple, but it is code.
This is not an enterprise architecture book. The patterns here are for businesses with tens to tens of thousands of rows, not millions. If you are running a bank or a hospital on spreadsheets, you need a different book.
This is not a book about replacing ERPs, accounting systems, or purpose-built software for genuinely complex operations. Double-entry bookkeeping is genuinely hard; regulatory reporting is genuinely complex; high-volume e- commerce with thousands of SKUs genuinely needs specialized tools. But for the vast majority of small businesses, the spreadsheet is good enough, and the wrapper adds what is missing.
The businesses described in the case studies are real.
Customer names are used with permission or changed where requested. The column names, cron schedules, and code snippets are from the actual running systems.
Numbers are accurate to the production records.
Rutendo runs a small knitwear shop out of a converted shipping container in Eastlea, Harare. She sells hand-knitted baby jerseys, hats and blankets to customers around the country. She has been in business for four years. She has a WhatsApp Business account, an EcoCash merchant number, and an Instagram page with 3,200 followers. She processes between forty and seventy orders per week.
When I met Rutendo in August 2025, I was trying to sell her Tapstall. Tapstall at that time was a one-link storefront: the customer taps a link, picks a product, pays EcoCash, the order lands in a web dashboard the shopkeeper logs into.
The pitch was simple: stop taking orders over WhatsApp DMs, stop manually confirming payments, stop losing orders in the noise. One link. One dashboard. Everything organized.
Rutendo heard me out. She looked at the demo on my phone. She asked two questions.
“How do I see it on my laptop?” “You log into the dashboard in your browser.” “Can I print a list of tomorrow’s orders?” “Yes, there’s an orders page you can print.” “Can I colour-code the ones that are paid?” “Yes, we have a status system — paid, processing, fulfilled.” She nodded. She did not sign up.
A month later I visited her shop again. On the counter, next to her knitting needles and a half-finished jersey in cream wool, was her laptop. On the screen was an Excel spreadsheet. It had columns for date, customer name, phone number, item, size, colour, price, payment method, payment status, delivery address, notes. The payment-status column was colour-coded — green for paid, yellow for pending, red for not paid. She sorted it by date every morning, printed the page, and worked her way down the list. When a customer paid, she changed the cell to green.
When an order went out for delivery, she wrote “sent” in the notes.
The spreadsheet did everything my dashboard did. And it did three things my dashboard did not. She could open it without internet if the fiber was down. She could add columns whenever she wanted for things I had not anticipated — “customer’s baby name,” “return regular?,” “yarn supplier” — without emailing a founder and waiting for a feature request. And she already knew how to use it.
She had been using Excel since form one at high school.
I did not sell Rutendo a dashboard that afternoon. I left her shop and walked back to the car with a different product in my head. The dashboard was the wrong interface. The spreadsheet was already the interface. The question was not “what dashboard should we build for Rutendo?” The question was “what can we wrap around Rutendo’s spreadsheet so that she never has to retype an EcoCash confirmation into the green column by hand?” That question is the origin of the architecture described in this book. We did not build another dashboard. We built a thin autonomous layer that reads a spreadsheet, detects state changes, performs the actions that a human would otherwise perform (verify payment, send a confirmation SMS, log delivery), and writes the result back into the sheet. The shopkeeper keeps their spreadsheet. They do not learn a new tool. They do not log into a new website. The automation lives in the background, handling the boring parts, and the spreadsheet stays the source of truth.
This is not a small idea or a workaround for a “low- resource” market. It is a general architecture for building software that people will actually use. Spreadsheets are the most successful end-user programming environment in the history of computing. Over a billion people use them every day. They are the default interface for small business in Harare and in Houston, in Lagos and in London, in Delhi and in Des Moines. Every attempt to replace them with purpose-built SaaS dashboards has failed to displace them, because spreadsheets do something no dashboard can: they let the user decide the shape of the data.
This book is about building governable autonomous systems that respect that fact. It is about wrapping spreadsheets in software that acts on behalf of the operator without asking them to migrate, retrain, or abandon the tool they already know. It is drawn from three years of operating three production products built this way — Tapstall (payments), Bidfold (tender intelligence), and STPi (recruitment automation). All three use a spreadsheet as the primary operator interface. All three run autonomously. All three are governable using the framework in the previous book.
The spreadsheet is not a temporary stage on the way to a proper system. It is the proper system.
Tomorrow morning, visit three small businesses you know (a shop, a salon, a workshop, a surgery) and ask to see how they track their orders or their customers.
Every time you ask a user to leave their existing tool and learn yours, you charge them an interface tax.
The tax has four components, and almost every builder underestimates all of them.
The learning tax. How long does it take a competent user of spreadsheets to become a competent user of your custom dashboard? In our experience, between four and eight hours of concentrated effort. That does not sound like much, but it is four to eight hours of concentrated effort that a small business owner does not have. The shop is open from 8 a.m. to 6 p.m. The children need to be picked up from school. The books are done after dinner. Four hours is half a Saturday, and half a Saturday is a more valuable currency than any subscription fee.
The migration tax. Before using your dashboard, the user must move their existing data into it. That means exporting from whatever they use today, cleaning the data, mapping columns, resolving duplicates, handling the records that do not fit your schema. For a small business with a thousand rows of order history, this is a full day of work. Most users will not do it, even when your software is clearly better than what they use today. The cost of switching exceeds the benefit, even when the benefit is large.
The availability tax. Your dashboard requires internet. It requires a browser that is not six years out of date. It requires a screen large enough to see the columns. It requires that your servers are up, that the fiber has not been cut, that load-shedding has not taken the router down.
Spreadsheet files live on a laptop. They open in Excel 2010.
They open when the internet is off. They can be copied to a USB stick and printed at the internet café. In a market where power is unreliable and fiber is cut on average three times per month, this is not a feature — it is table stakes.
The flexibility tax. A dashboard has an opinion about how your business works. It has a fixed set of columns, a fixed order lifecycle, a fixed set of statuses. If your business works slightly differently — if you track the baby’s name because that is how your customers think about their orders, if you have a “maybe paid” status for when an EcoCash confirmation is ambiguous, if you want to colour- code customers who are also your neighbours — the dashboard either cannot do it, or it requires a custom feature request that will be triaged in six months. A spreadsheet has no opinions. You add a column. You change a colour. You insert a formula. You do it now, without asking permission.
These four taxes explain why spreadsheets survive, even in businesses that can afford “proper” software. The spreadsheet is free (or came with the laptop), it is offline- capable, it is flexible, and the user already knows how to use it. The total cost of ownership for a spreadsheet is effectively zero. The total cost of ownership for a SaaS dashboard — subscription fee plus learning time plus migration plus availability requirements plus flexibility losses — is much higher than builders who live in San Francisco with gigabit fiber and 40-hour work weeks tend to assume.
This is not an argument against purpose-built software.
Some problems genuinely require one: accounting with double-entry bookkeeping, regulatory reporting, high- volume e-commerce with thousands of SKUs. But for the vast majority of small and medium businesses — the seven million SMEs in sub-Saharan Africa, the forty million small businesses in the United States, the owners and operators who run businesses from a laptop and a phone — the spreadsheet is good enough. It is more than good enough. It is what they use.
The architectural insight that follows is simple: instead of asking the user to come to your interface, bring your automation to their interface. Wrap the spreadsheet.
Before we can wrap a spreadsheet, we need to understand what one actually is. This sounds obvious. A spreadsheet is a grid of cells, right? Rows, columns, formulas. But to a builder who wants to extend it, a spreadsheet is several things at once, and understanding the layers is the key to wrapping it well.
A spreadsheet is a database. Every row is a record. Every column is a field. Every sheet is a table. You can sort, filter, search, deduplicate, and aggregate. It is a schemaless database in the best sense — you add a column when you need a field, you rename columns when your understanding changes, you do not run a migration. For a business doing fewer than ten thousand rows of anything, a spreadsheet is a perfectly good database. It is transactional enough (one user editing at a time, or a few users in Google Sheets), it is queryable enough (Ctrl-F, filters, VLOOKUP), and it is durable enough (saved on disk, version history in the cloud).
A spreadsheet is a user interface. The cells render as a grid on screen. The user can click, type, colour, and format. They can see all their data at once, not one record at a time as in most web apps. They can print it. This is a surprisingly important property: a shopkeeper prints the day’s orders every morning, because the printed sheet goes to the person packing orders, who does not sit in front of a laptop. A dashboard that renders one order at a time cannot be printed meaningfully.
A spreadsheet is a workflow engine. Conditional formatting is a decision system. Formulas are business logic. A column that says “if payment_status = PAID and delivery_status = PENDING then READY TO SHIP” is a business rule, written by the operator in five seconds, that most SaaS products would require a support ticket to implement. The spreadsheet executes these rules continuously, in real time, without a deploy.
A spreadsheet is an audit trail. Every cell has a history. Every edit has a timestamp and an editor in Google Sheets. The grid shows the state of the business right now, but the state arrived there through a sequence of visible changes. You can look at a row and reconstruct what happened to an order from creation to fulfilment.
A spreadsheet is a communication surface. Comments, cell notes, @mentions, colour-coding — the spreadsheet is a shared workspace where multiple people can collaborate. The warehouse person reads the notes column. The bookkeeper reads the payment column. The owner watches the totals. Everyone sees the same grid.
There is no sync problem between “the system” and “the spreadsheet” because the spreadsheet is the system.
This is why people do not leave spreadsheets. It is not because they are unsophisticated or behind the times. It is because a spreadsheet is five tools in one — database, UI, workflow engine, audit trail, communication surface — and all five tools work, for free, with zero onboarding. Every “proper” software system replaces one of these tools and tries to replicate the other four, badly.
The wrapper does not try to replace any of these five tools. It adds a sixth capability to the spreadsheet that the spreadsheet cannot do on its own: autonomous action outside the sheet.
Open a spreadsheet you use for real work (personal budget, project tracker, content calendar). Identify which of the five layers you use it for (database, UI, workflow engine, audit trail, communication surface).
The most common advice given to a small business that has outgrown its spreadsheet is: upgrade to a proper system. Buy NetSuite. Buy QuickBooks. Buy an industry-specific ERP. Move to Salesforce, HubSpot, Odoo, SAP Business One, or whatever the consultant recommends.
This advice is bad for most small businesses, and it is particularly bad for the kind of businesses I work with in Zimbabwe. Let me tell you why.
A “proper system” replaces the spreadsheet’s flexibility with a schema. The schema was designed by someone who has never seen your business. It assumes your orders move through a standard lifecycle that your actual orders do not follow. It has fields you do not need and no fields for the things you track. The standard implementation requires a consultant to configure it, which costs more than the license itself, and the consultant leaves after three weeks. After six months of frustration, the staff maintain the “proper system” for compliance and accounting while running the actual business in a spreadsheet on the side. I have seen this at a fifty-person company. I have seen it at a ten-person company. I have seen it at a three-person company. The “proper system” becomes a fancy, expensive tax that generates reports for auditors while the real work continues in Excel.
The architecture in this book goes the other direction.
Instead of replacing the spreadsheet, we accept it as the system of record and add a thin layer of automation around it. The spreadsheet remains the interface, the database, the workflow engine, the audit trail, and the communication surface. The wrapper adds capabilities the spreadsheet cannot provide natively: sending SMS, verifying mobile- money payments, scraping external data sources, matching records against each other, generating documents, and performing actions on a schedule — all governed by the four pillars of evidence, authority, resources, and recovery described in The Governable Enterprise .
You do not need to migrate. You do not need to train your staff on a new tool. You do not need to change how you work. You add columns to your existing sheet — a status column, an actions column, a last-run column — and the wrapper begins handling the parts of the job that are boring to do by hand.
The rest of this book shows you how.
Find a business running on a “proper system” that also maintains a spreadsheet on the side. Ask why. Listen carefully. The answer will teach you more about software adoption than any UX book.
The wrapper is the core architectural pattern in this book. It is simple to describe, harder to implement well, and remarkably powerful once it is working.
Here is the pattern, in one paragraph:
A wrapper is a small, scheduled process that reads rows from a spreadsheet, identifies rows that need an action to be taken, takes those actions subject to governance controls (budgets, approvals, reconciliation), and writes the result back into the same spreadsheet. The wrapper never holds the canonical state — the spreadsheet does. The wrapper never replaces the spreadsheet’s user interface — it only adds columns. The wrapper is stateless between runs; every run starts fresh from the sheet.
Let me break this down into its six properties, because each one matters.
1. The wrapper reads from the spreadsheet. It does not read from a separate database that mirrors the spreadsheet. There is no sync, no ETL, no replication. The spreadsheet is the single source of truth. On every run, the wrapper opens the sheet, reads the rows it cares about, and operates on what it finds. If the shopkeeper adds a row by hand at 10 p.m., the next scheduled run sees it. If the shopkeeper changes a cell from “pending” to “paid,” the next run sees that too. There is no cache to invalidate, no event stream to subscribe to, no webhook to miss. The read is simple, direct, and — crucially — idempotent. Reading does not change anything.
2. The wrapper identifies rows that need action. Each row has a status column. The status value tells the wrapper what to do next. A row with status “NEW” might need a payment verification. A row with status “PAID” might need a confirmation SMS. A row with status “READY” might need to be sent to the delivery queue. A row with status “SENT,” “DONE,” or “ERROR” needs nothing. The wrapper scans for rows in states that require action and processes them. This is a state machine, and the spreadsheet holds the state.
3. The wrapper acts subject to governance. Before sending an SMS, charging a card, or calling any external API, the wrapper checks the same controls described in The Governable Enterprise : is this action within the authority level for this row? Is this within the send budget for this run? Has a human approved this action if approval is required? The wrapper does not act blindly because a row is in the “ready” state. It enforces the same governability rules that any autonomous system requires.
4. The wrapper writes back. After performing an action, the wrapper writes the result into the sheet. It updates the status column to the new state. It writes a timestamp into a “last_action_at” column. It writes the result (confirmation number, error message, external ID) into a “result” column. The shopkeeper sees what happened by looking at the sheet. There is no separate dashboard or log to consult — the sheet itself is the log.
5. The wrapper is stateless between runs. It does not remember what it did last run. It does not maintain an internal queue. It starts fresh every time, reads the sheet, processes rows that are ready, writes back results, and exits. Statelessness makes the wrapper simple, testable, and easy to reason about. It also means that if the wrapper crashes mid-run, the next run picks up where the previous one left off — because the state is in the sheet, not in the wrapper’s memory.
6. The wrapper runs on a schedule. It does not run in response to webhooks, event streams, or triggers. It runs on a timer: every five minutes, every hour, every morning at 6:30, depending on the action’s natural cadence (see Governable Enterprise, Chapter 10). Scheduled runs are easier to govern, easier to pause, easier to debug, and easier to reason about than event-driven systems. A wrapper that runs at 6:30 a.m. after the daily read has a recovery window of zero seconds; a wrapper that runs on every webhook event has a recovery window of however long it takes the operator to notice something is wrong.
The wrapper is not a framework you install from npm. It is a pattern you implement in whatever language you prefer.
All three Coldcode Si Labs wrappers are written in Python in about 800-1,200 lines of code each, including governance controls, error handling, and reconciliation. They read Google Sheets via the Sheets API or read a file from a shared sync folder. They write back the same way. They run as cron jobs on a five-dollar VPS. They are not complicated.
They do not need to be.
In plain language, in one paragraph, write what your wrapper does. If the paragraph contains the words “platform,” “ecosystem,” “revolutionary,” or “AI- powered,” you have not understood the pattern yet.
The first rule of wrapper design is simple and rigid: one wrapper job does one thing, operating on one sheet, where each row represents one instance of one entity. A sheet of orders has rows that are orders. A sheet of tenders has rows that are tenders. A sheet of candidates has rows that are candidates. One sheet per entity type. One wrapper job per action.
This sounds trivial until you see how spreadsheets actually grow in the wild. A shopkeeper starts with a sheet for orders. After six months they add a sheet for customers.
After a year they add a sheet for inventory. After two years the orders sheet has tabs for each month and a summary tab and a “specials” tab and a tab where they track which suppliers are paid. The wrapper cannot navigate this complexity. It should not try to.
The discipline is: identify the primary entity the wrapper operates on, give it one dedicated sheet with one header row and one row per entity, and have the wrapper read only that sheet. All other tabs remain the shopkeeper’s domain, to organize however they wish. The wrapper’s sheet is the contract.
Why one job per action? Because governability requires knowing what the system is doing. A single wrapper job that verifies payments, sends confirmation SMS, prints delivery notes, reconciles the ledger, and sends marketing follow-ups is a wrapper job that cannot be paused independently, cannot be budgeted independently, and cannot be reasoned about independently. When the SMS provider is down, the entire monolith stops. When an email template has a bug, payment verification stops too. Split the actions into separate jobs, running on separate schedules, with separate budgets, and each one becomes governable on its own.
The cost of splitting is small. Each job reads the same sheet. Each job looks at a different status column (or a different status value) and takes a different action. They share the same read path. They share the same write path.
But they run independently, fail independently, and can be paused independently.
On Tapstall we have four wrapper jobs: 1. Payment watcher (runs every two minutes): reads the order sheet, checks for new EcoCash confirmations, marks rows as
“PAID.” 2. Confirmation sender (runs every five minutes): reads the order sheet, sends confirmation SMS for newly paid rows. 3. Daily digest (runs once at 6:35 a.m.): reads the order sheet, sends the shopkeeper a summary of yesterday’s orders. 4. Reconciliation (runs once at 6:05 a.m.): reads the order sheet and the payment provider’s records, flags mismatches.
These four jobs share one sheet but do not interfere with each other. If the SMS provider is down, jobs 1 and 4 continue running; job 2 holds pending sends; job 3 sends its digest with a note about pending confirmations. Each job can be paused individually. Each has its own budget (daily SMS cap, payment-check frequency cap). Each has its own error alerting. Each fits in under 250 lines of code.
The “one table, one sheet, one job” rule is the spreadsheet-system equivalent of the Unix philosophy: do one thing, do it well, compose with other things.
Spreadsheets are naturally composable because they are just grids; you do not need an API gateway or a service mesh to connect the payment watcher to the confirmation sender. You need them both to read and write the same cells responsibly.
The most common failure mode in wrapper systems is a read/write conflict between the wrapper and the human. The wrapper reads a row, decides the order is unpaid, sends a follow-up SMS — but one second before the wrapper ran, the shopkeeper had manually changed the status to “PAID” after confirming payment over the phone.
The customer receives a “please pay” SMS when they have already paid.
This is not a theoretical problem. It happened with Tapstall in the second month of operation. Mrs. Chitando paid via EcoCash at 9:14 a.m. The wrapper ran at 9:15 a.m.
Before the wrapper could read the payment confirmation (which can take up to 90 seconds to propagate through EcoCash’s API), Rutendo manually marked the order as paid and added a note: “paid cash, dropped off.” The wrapper saw the row as “PAID” and correctly skipped the payment check — but its SMS logic had a race condition in which it had already queued a follow-up before re-checking the status. The follow-up was sent. Mrs. Chitando received a message asking her to pay for an order she had already collected.
The fix is not to remove the wrapper or to lock the sheet during runs (which would prevent the shopkeeper from working). The fix is a strict read/write boundary with three rules:
Rule 1: Re-read immediately before writing. The wrapper reads the row at the start of processing, does its work, and then re-reads the same row immediately before writing any result. If the row has changed between the initial read and the write — if the status is different, if the human has added a note, if another job has already updated it — the wrapper abandons the action for that row and moves to the next one. The re-read costs one API call. It prevents a whole category of race conditions.
Rule 2: Write only designated columns. The wrapper writes only into columns that belong to it. It does not overwrite cells the human writes into. A typical wrapper writes into three columns: a status column that it owns (or shares with the human under defined transitions), a last- action timestamp column, and a result/notes column that it appends to rather than overwriting. The customer name column, the product column, the address column — these belong to the human, and the wrapper never touches them.
Rule 3: Append, don’t overwrite, in the log column. The wrapper’s notes column is an append-only log. Each run adds a new line with a timestamp and the action taken. Old entries are never deleted or overwritten. This gives the human a complete audit trail of everything the wrapper did to the row, in order. If the wrapper sends an SMS, it appends “9:15 — confirmation SMS sent”; if the SMS fails, it appends “9:16 — SMS failed, will retry”; when the human adds a note, they write it in a separate human-notes column that the wrapper does not touch.
These three rules do not eliminate race conditions entirely — nothing can, if two independent actors are writing to the same sheet — but they reduce them to near zero. In the year since we implemented the re-read rule on Tapstall, we have had zero customer-visible race conditions out of approximately 14,000 orders processed.
Web applications use buttons: a “confirm payment” button, a “send confirmation” button, a “mark as shipped” button. Buttons require a UI, which means a dashboard, which means logging in, which means the interface tax we discussed in Chapter 2.
A spreadsheet wrapper uses a different mechanism: status columns . Instead of clicking a button, the human changes the value of a cell. Instead of a button that says “approve,” the human types “APPROVE” into the approval column. Instead of a button that says “cancel,” the human changes the status to “CANCELLED.” Instead of a button that says “send now,” the human changes the priority column to “URGENT.”
Status columns have four properties that make them better than buttons for a spreadsheet-wrapped system: They are visible without opening a special interface. The status is there, in the grid, next to the customer name and the product. The shopkeeper can scan fifty orders and see the state of every one in a single glance, without clicking into detail views.
They are composable with formulas. A cell that says
“=IF(payment_status="PAID", IF(delivery_status="PENDING", "READY", "DONE"), "AWAITING PAYMENT")” is a dashboard in one cell. The shopkeeper can build these themselves, without asking a developer to add a feature. The status columns are data, and data can be computed, filtered, and formatted.
They work offline. Changing a cell does not require a network request. The shopkeeper can mark orders as shipped on a printed copy and type the updates into the sheet when they return to the office with connectivity.
The next wrapper run will see the new statuses and act accordingly.
They are auditable. A cell change has a timestamp and an editor in the version history. A button click in a dashboard is logged only if the developer built logging.
Every wrapper job is bound to a cadence. The cadence determines how often the job runs, which determines the delay between a state change and the system’s response, which determines the recovery window if something goes wrong.
Cadence binding is the discipline of matching each wrapper job’s schedule to the natural frequency of the underlying action and the availability of the operator. This is the same idea described in The Governable Enterprise , Chapter 10, but applied specifically to the wrapper pattern.
The rules are:
Actions that are cheap and reversible can run frequently. Payment verification on Tapstall runs every two minutes. Reading an EcoCash confirmation costs nothing in API fees, the read is idempotent, and the consequence of a false positive is small — the wrapper might think a payment has arrived a minute before it actually has, which the re- read rule catches. Two minutes is an acceptable delay for a shopkeeper waiting to pack an order.
Actions that send messages to customers run less frequently and only during waking hours. Confirmation SMS runs every five minutes between 7 a.m. and 7 p.m. It does not run at 3 a.m. Even if a customer pays at 3 a.m., the confirmation waits until 7:05. This respects the customer’s attention budget and ensures that if something goes wrong, the operator is awake before customers start receiving messages.
Actions that send batches run once per day, after the daily read. The morning order digest for Tapstall runs at 6:35 a.m., after the 6:05 reconciliation and after the operator has done the ten-minute daily read. This guarantees that a bad digest is never sent before a human has looked at the day’s data.
Reconciliation runs before any action that costs money. The payment reconciliation runs at 6:05, before the 6:35 digest and before the confirmation job resumes for the day. If something is wrong, the operator pauses before any money is spent.
Each wrapper job has its own cadence documented in the authority matrix, alongside its budget and its escalation target. The cadence is not a technical default chosen by a developer; it is an operating decision made by the person who is on call. The developer implements the schedule; the operator decides the frequency.
One practical note: avoid real-time, event-driven triggers for wrapper jobs. It is tempting to use webhooks — EcoCash can push a payment confirmation to your endpoint the second it arrives, Google Sheets can fire a trigger when a cell changes — but event triggers destroy the clean failure model that makes wrappers governable. An event-driven wrapper acts instantly, which means it acts during the night, during fiber cuts, during incidents, before the operator is awake. A scheduled wrapper acts on a known schedule; the operator knows exactly when actions will happen, which means the operator knows exactly when they need to be paying attention. The difference is the same as the difference between a landmine and a doorbell: one goes off unexpectedly; the other rings at a predictable time and you can choose not to answer.
Write down the cadence for every wrapper job. Write next to each cadence why it runs that often. If the answer is “because that’s what the cron default was,” you have not made an operating decision.
There is one class of action the wrapper must never take on the spreadsheet’s authority alone: moving money.
The spreadsheet is a powerful tool, but it is not a system of financial control. A user can type “PAID” into a cell by accident. A bug in the wrapper can misread a row. A malicious collaborator can edit a status to trigger a refund.
If the wrapper can move money — charge a card, initiate a payout, release escrow, send an instant-money transfer — solely because a cell on a spreadsheet says so, you do not have a financial control. You have a spreadsheet that can write checks.
The rule is:
the wrapper can read payment instructions from the sheet, but it must never execute a financial movement without an independent confirmation from the payment system itself. The sheet can record that a payment should be made; the wrapper asks the payment provider whether the payment was actually received; the wrapper only acts when both the sheet and the provider agree.
For Tapstall, this means the payment-watcher job never marks an order as paid because a human typed “PAID” in the status column. It marks an order as paid only when (a) the EcoCash API confirms a matching incoming transaction for the correct amount and reference, and (b) the sheet status is not “CANCELLED.” The human can type “PAID” as a note to themselves (in a separate human-only column), but the wrapper trusts only the payment provider for the actual state of money.
The reverse is also true. The wrapper never initiates an outbound payment because a spreadsheet row says “REFUND.” Outbound payments — refunds to customers, payments to suppliers, payouts to sellers — require a human to press a button in the actual payment interface, or require a separate signed approval outside the spreadsheet. The sheet can record that a refund is due; the wrapper can queue it for approval; but the actual movement of money always involves either an independent payment callback or a deliberate human action outside the sheet.
This custody boundary extends to other high-stakes actions, not just money. A recruitment wrapper (STPi) should never submit a job application on behalf of a candidate solely because a cell says “SEND.” It drafts the application, queues it for human approval, and only sends after a human presses “approve” in the approval interface (which can be a second spreadsheet column, but the approval action must be a deliberate, timestamped event, not a default cell value). A tender-matching wrapper should never submit a bid on behalf of a company solely because the sheet says “BID.” The wrapper can match, it can prepare, it can calculate — but the act of submitting a bid to a third party is high-stakes enough to require an explicit human gate.
The general principle: custody of irreversible or high- value actions always sits outside the sheet, with a system or a human that requires proof beyond the cell value. The sheet can request, record, and track. It does not command.
List every action your system takes that involves money.
For each one, identify the independent check that confirms the money actually moved. If an action is triggered solely by a spreadsheet cell value, redesign it.
The human-approval gate (Governable Enterprise, Chapter 9) translates cleanly into a spreadsheet wrapper as the approval column . It is the simplest possible interface for human oversight: a column in the sheet, blank by default, where a human types “APPROVE” (or picks it from a dropdown) to release an action that the wrapper is holding.
The pattern works like this:
The wrapper processes a row and determines that an action is ready, but the action requires approval (Level 1 on the autonomy gradient — for example, sending an urgent same-day tender alert, submitting a drafted cover letter, issuing a refund over $50).
Instead of performing the action, the wrapper sets the status column to “PENDING APPROVAL” and writes into the action column what it is proposing to do: “Send urgent tender alert: City of Harare asphalt tender, closing tomorrow, matches 3 of 4 filters.”
The shopkeeper or operator sees the pending row in the sheet (rows in “PENDING APPROVAL” are formatted in yellow via conditional formatting). They review the proposed action. If they agree, they type “APPROVE” in the approval column. If they disagree, they type “REJECT” and add a note.
On the next wrapper run, the wrapper sees “APPROVE,” performs the action, updates the status, and clears the approval column. If it sees “REJECT,” it logs the rejection and moves on.
The approval column has three important properties: It requires no custom UI. There is no “approval dashboard,” no login, no special interface. The operator opens the same spreadsheet they already use for everything and types in a column. The approval can be done from a phone in Google Sheets mobile, from a laptop, even from an internet café on a public computer. The sheet is the approval interface.
It produces a durable record. Every approval is a cell change, which means it has a timestamp and an editor in the version history. You can audit who approved what, when. This is a compliance requirement in some industries; it is a governability requirement in all of them.
It is composable with formulas. You can add a column that shows how long an action has been pending approval (using NOW() minus the timestamp when it went pending).
You can add conditional formatting that turns rows red if they have been pending for more than two hours. You can have a separate “summary” tab that shows all pending approvals at the top. You can do all of this without asking a developer to build a feature.
For very high-stakes actions, the approval column can require two approvals. We use this for STPi when sending a cover letter on behalf of a candidate to an employer: the draft is prepared, the status goes to “PENDING REVIEW,” a reviewer approves (sets review column to “OK”), and then the operator approves the send (sets approval column to “APPROVE”). The wrapper only sends when both columns are set. The two-approval system is implemented with two columns and an AND formula in a “ready to send” computed column — no engineering required.
The approval column is the spreadsheet-wrapped system’s answer to the enterprise workflow engine. It costs nothing, requires no new software, and produces a complete audit trail in cells anyone can read.
Add an approval column to the sheets where actions require human review. Start with one action type — the highest-stakes one.
Implement the approval check in your wrapper: only send/act when the approval column is explicitly set to “APPROVE.”
Add conditional formatting to highlight pending approvals in yellow so they are visible at a glance when the operator opens the sheet.
Tapstall was the first product where we got the wrapper architecture right. Earlier I described how Rutendo’s spreadsheet showed me the futility of building a dashboard. The version of Tapstall that Rutendo eventually signed up for — and that 187 shops now use — is not a dashboard. It is a storefront link that the shop shares with customers. When a customer taps the link, they see a simple product list, pick what they want, enter their phone number and address, and confirm. The order is written into the shopkeeper’s Google Sheet as a new row. The wrapper does the rest.
Let me walk you through a single order end-to-end so you can see the architecture in action.
10:02 a.m. A customer in Chitungwiza taps a Tapstall link shared on a knitwear shop’s WhatsApp status. They select a cream baby jersey (size 6-12 months), enter their phone number and address, and tap “confirm order.” The Tapstall storefront creates a new row in the shopkeeper’s Google Sheet with columns: timestamp, order ID, customer name, phone, item, size, price, payment status, delivery status, notes, wrapper_log. The payment status is set to “AWAITING PAYMENT.” The customer receives an on-screen message: “Pay $18 to EcoCash merchant 12345, use reference TAP-4821. Your order will confirm automatically.”
10:04 a.m. The payment-watcher wrapper runs (every two minutes). It reads the sheet and finds the new row with status “AWAITING PAYMENT.” It checks the EcoCash merchant API for incoming transactions with reference “TAP-4821.” It finds nothing. It writes in the wrapper_log: “10:04 — no payment found, will retry.” It exits.
10:07 a.m. The customer completes the EcoCash payment of $18.
10:08 a.m. The payment-watcher runs again. It queries EcoCash. It finds a transaction for $18 with reference “TAP-4821,” confirmed at 10:07. It re-reads the row to confirm the status is still “AWAITING PAYMENT” (it has not been manually cancelled in the last four minutes). It updates the payment status to “PAID.” It appends to the wrapper_log: “10:08 — payment confirmed via EcoCash, txn EC-948372.”
10:10 a.m. The confirmation-sender wrapper runs (every five minutes between 7 a.m. and 7 p.m.). It finds the newly PAID row. It sends a confirmation SMS to the customer: “Your Tapstall order from Rutendo Knitwear is confirmed!
We will deliver today. Reference TAP-4821.” It appends to the wrapper_log: “10:10 — confirmation SMS sent to +26377…” It updates the delivery status to “PACKING.”
6:35 a.m. next day. The daily-digest wrapper runs. It reads yesterday’s orders, summarises them (22 orders, $387 total, 19 paid, 3 pending), and SMSes the digest to the shopkeeper.
Throughout the day. The shopkeeper works from the sheet. She prints it in the morning. She marks each row’s delivery status to “DELIVERED” as orders go out. She adds notes: “left with security,” “customer wants blue not cream.” The wrapper does not interfere with her notes. It just keeps processing new orders as they arrive.
Let me list the concrete pieces that make this work: The storefront writes new rows into the sheet. It never reads from the sheet (other than to pull product names and prices, which are on a separate “products” tab). It is fire-and-forget — if Google Sheets is temporarily unavailable, the storefront queues the order and retries.
The Google Sheet holds all order state. It has 12 columns. The shopkeeper can add any additional columns she wants (and many do — baby name, repeat customer, yarn type, etc.) without telling us. The wrapper ignores columns it does not recognize.
The payment-watcher wrapper (Python, ~180 lines) runs every two minutes via a cron job on a five-dollar VPS in Johannesburg. It reads the “payment_status” column, checks EcoCash for rows awaiting payment, and updates the status when payment is confirmed.
Bidfold is the tender intelligence desk described in The Governable Enterprise . The architecture is a wrapper, but the data flow is the inverse of Tapstall. Tapstall writes new rows into the shopkeeper’s sheet (customer orders arrive from outside). Bidfold reads from thirteen external sources and writes matches into the subscriber’s sheet; the subscriber reads the sheet and acts on the rows.
Here is the Bidfold architecture:
The scraper fleet (thirteen separate scrapers, one per public tender source) runs every morning at 4:00 a.m. Each scraper reads its source, extracts open tenders (title, issuing body, region, sector, value, closing date), and writes them into a master “all tenders” sheet. The scrapers are simple — 50 to 200 lines each, depending on how terrible the source website is. If a source is down or its HTML has changed, the scraper logs the failure and moves on; the other twelve sources still populate the sheet.
The matcher wrapper runs at 5:30 a.m. after all scrapers finish. It reads the master tenders sheet and reads each subscriber’s filter sheet (each subscriber has a tab with their filter criteria: regions, sectors, minimum value, keywords). It performs the matching and writes a row into each subscriber’s “matches” sheet for every tender that passes the filters. Each match row includes: tender title, issuing body, region, value, closing date, link to the tender document, and a “why this matched” column listing which filters triggered.
The digest wrapper runs at 6:35 a.m. after the reconciliation. It reads each subscriber’s matches sheet for the day, compiles a digest SMS listing the new matches, and sends it. The digest is capped at five messages per subscriber per day; if more than five matches are found, the subscriber receives five and a note to view the rest in the sheet.
The subscriber interface is a Google Sheet that we own and share with them. Unlike Tapstall, where the shopkeeper provides their own spreadsheet, Bidfold provisions a sheet per subscriber on our own Google Workspace account. The subscriber gets view access (or edit access if they want to add their own notes). This is deliberate — the tender database is curated, the matching logic is ours, and we want the same schema for all subscribers to keep the wrapper simple. The subscriber can export the sheet, copy it, add columns on their own copy; they just cannot break our shared version.
Wait — that sounds like a dashboard. Is Bidfold a dashboard? It is not, because the subscriber’s primary interaction with the data is a spreadsheet grid, not a custom web page. They can sort, filter, add notes, add columns (on their own copy), share the sheet with colleagues, and print it. They do not log into our website to see their matches after the initial sign-up. The SMS digest points them back to the sheet. The sheet is the interface.
The reason Bidfold uses our sheet rather than the subscriber’s sheet is that the data flows the other direction.
Tapstall takes data from customers (through our storefront) and writes it into the merchant’s sheet — the merchant already owns their workflow, we are inserting orders into it.
Bidfold aggregates data from many sources and presents it to the subscriber; the subscriber does not have a tender sheet before signing up, so we provide one. The architecture is the same — wrapper, scheduled runs, status columns, governed actions, budgets — but the ownership of the sheet is reversed based on who owns the workflow.
The Bidfold wrappers total about 1,100 lines of Python across five jobs (scrape orchestrator, thirteen scrapers, matcher, digest sender, reconciliation). They process about 30,000 tenders per month across 200+ subscribers. The architecture has survived one major incident (March 14, documented in The Governable Enterprise ) and dozens of source-website breakages, because when one scraper fails, the others continue to run, the matcher works with whatever data it has, and the shopkeeper sees partial results rather than a broken product.
Identify a public data source relevant to your business (tenders, job boards, price lists, regulatory filings).
TPi (Strategic Talent Placement Infrastructure) is the most complex of the three wrappers because it involves AI drafting and high-stakes outbound communication. But the architecture is the same pattern: a sheet, a scheduled wrapper, governance controls, human approval before irreversible action.
Here is how STPi works for a job-seeking candidate: Onboarding. The candidate signs up, uploads their CV, and specifies the kinds of jobs they are looking for (role, seniority, location, industry, salary range). This creates a row in the “candidates” sheet and a set of filter criteria similar to Bidfold.
Job scraping. Every morning at 5:00 a.m., scrapers pull new job postings from 76 job-board families across 21 African markets. Jobs are written to a master “openings” sheet.
Matching. The matcher wrapper runs at 5:30, matching new openings against candidate filters.
Matches are written into each candidate’s “matches” tab with a match score and a “why” explanation.
Drafting. The drafting wrapper runs at 5:45 for each new match. It reads the candidate’s CV (stored as parsed text from the upload), reads the job description, and uses an LLM to draft a tailored cover letter and a CV tailored to the specific job. The drafts are written into the candidate’s “pending applications” sheet.
Status is set to “DRAFTED.”
Human review. A reviewer (a human on the STPi team) opens the pending-applications sheet, reads each drafted cover letter and CV, and either edits, approves, or rejects. Approval is a column: “REVIEW” set to “OK” (draft is good to go) or “EDITED” (reviewer made changes) or “REJECT” (wrong match, hallucinated content, inappropriate). The reviewer is a real human being paid to read drafts. This step takes about 60-90 seconds per application.
Operator send approval. After reviewer approval, a second human (the operator on duty) does a final check and sets the “APPROVE” column to “SEND.” This is the two-person
rule
Looking across Tapstall, Bidfold, and STPi — three products in three different domains (payments, intelligence, recruitment) — there are seven architectural properties that held in every case and that I believe are general to any successful spreadsheet-wrapped system:
1. The sheet is the source of truth. Not the wrapper’s database, not the SaaS provider, not the LLM’s memory. The sheet. If you open the sheet, you know everything there is to know about the state of the system. There is no hidden state.
2. The wrapper is stateless between runs. Every run starts by reading the sheet. There is no internal queue, no event log, no message bus that the wrapper depends on.
This means a crashed wrapper can be restarted at any time, and a new developer can understand the system by reading the sheet and the wrapper code in an afternoon.
3. Cadence is a deliberate operating decision. No job runs faster than it has to. No job runs before the daily read if it costs money or touches customers. Every schedule is documented in the authority matrix.
4. Custody sits outside the sheet. Money does not move because a cell says so. Emails to employers do not send because a cell says so. High-stakes actions require either an independent third-party confirmation or a deliberate human action outside the sheet.
5. Human approval is a column, not a dashboard. Approval happens in the same grid where the operator already works. It does not require a separate login, a separate UI, or a separate device. It leaves a timestamped, auditable trail for free.
6. The wrapper is boring code. None of the three wrappers use clever abstractions, fancy frameworks, or complex architecture. They read rows, apply logic, make API calls, write results back. The code is straightforward Python. A competent junior developer can understand any of the three wrappers in a day. This is a deliberate choice: in an incident at 5 a.m., you want to read boring code.
7. The user never migrates. In every case, the user keeps their workflow exactly as it was before the wrapper arrived. Tapstall’s shopkeepers keep their own sheets and we write orders into them. Bidfold’s subscribers receive a sheet they can sort, filter, and print like any other. STPi’s candidates and reviewers work from a grid that looks exactly like the spreadsheets they already use for tracking applications. Nobody is asked to learn a new tool.
There is one more thing that held across all three, and I want to name it explicitly because it contradicts almost everything the software industry teaches: the wrappers are small. Each wrapper is under 250 lines of code for an individual job. The total codebase for all three products combined is under 6,000 lines. This is not a limitation we are working to overcome; it is the point. Small code is governable code. Boring code is operable code. The spreadsheet absorbs complexity so the wrapper does not have to.
This is the architectural lesson that building these three products taught me. Most software engineers look at a spreadsheet and see a mess to be replaced with a proper system. The proper system they build is 60,000 lines long, requires a team to maintain, breaks in ways nobody can predict, and the customer stops using it after three months because they go back to their spreadsheet anyway. The wrapper approach respects the spreadsheet for what it already does and adds only the missing piece — autonomous, governed action — in a piece of code small enough to understand completely in a morning.
Look at a product you have built. Count the lines of code. If it is over 5,000 lines for a single action, ask: what is the code doing that a spreadsheet plus a 200- line wrapper could do instead?
Ask a new developer (or a technical friend) to read your wrapper code and tell you what it does. If they cannot understand it in under an hour, simplify it.
Write down the seven properties from this chapter on a card and tape it to your monitor. Review it before every major architectural decision.
There is a number I keep coming back to when reviewing wrapper code: eight hundred lines . A single wrapper job should fit in about 800 lines of straightforward Python. If it grows beyond that, you are probably doing too much in one job — split it.
The 800-line ceiling is not an arbitrary aesthetic preference. It is based on a constraint from operational reality: the code must be readable from top to bottom by a competent developer in under 30 minutes, including during an incident at 5 a.m. If the payment watcher is 3,000 lines long with six levels of abstraction and a framework imported from another repository, nobody can debug it at 5 a.m. If it is 600 lines with one main loop, three helper functions, and no magic, a developer who has never seen the code before can read it, understand it, and fix it while coffee is brewing.
This constraint forces specific design choices. You cannot use heavy frameworks. You cannot build clever abstraction layers. You cannot hide logic behind dependency injection or decorator stacks or reactive programming models. You write boring code. Functions do what their names say. The main loop reads in a straight line from top to bottom. Errors are caught and logged, not wrapped in five layers of exception hierarchy.
All three production wrappers at ColdCode Si Labs fit within this ceiling. The largest single job is the STPi drafting wrapper at 720 lines, and it includes the LLM prompting logic, the CV parser, the template renderer, and the Google Sheets read/write layer. If I can build a fully functional AI-powered drafting system in 720 lines, you can build a payment verification wrapper in under 200.
The first decision in building a wrapper system is which spreadsheet substrate to use. There are three realistic options for most builders, each with trade- offs. There is no single correct answer — the choice depends on your users, your reliability requirements, and the environment in which you operate.
Option 1: Google Sheets. This is the default choice for most wrapper systems, and it is what we use for all three Coldcode Si Labs products. The Google Sheets API is well- documented, has generous free quotas, handles authentication cleanly with service accounts, supports real- time collaboration, and provides a native mobile app.
Version history is automatic. Conditional formatting and data validation are built in. The principal downsides: it requires internet (both for the wrapper to access it and for the user to edit it), it is a Google product with Google’s terms of service and downtime, and it requires a Google account. For our market in Zimbabwe, Google accounts are ubiquitous (every Android phone ships with one), and the internet dependency is acceptable because the wrapper is the thing that needs connectivity; the user can always download the sheet as Excel for offline work.
Option 2: Microsoft Excel / OneDrive / Office 365. Microsoft’s spreadsheet stack is the enterprise default, and for business users who are already on Office 365 (common among corporate clients and government contractors), Excel is the interface they use. The Microsoft Graph API provides programmatic access to workbooks stored in OneDrive and SharePoint. The downsides: authentication is more complex than Google’s, API quotas are tighter, and the developer ecosystem is less friendly. If your customers are already committed to Microsoft (as many corporate tender desks are), this is the right choice; for individual SMEs and small shops, Google Sheets is almost always easier.
Option 3: Local files synced via a file-sync service. For users who cannot or will not use cloud spreadsheets — for regulatory reasons, for privacy reasons, or because internet connectivity is too unreliable — the wrapper can read and write local spreadsheet files (Excel .xlsx files) synced via Dropbox, Nextcloud, Resilio Sync, or a simple network share. The wrapper watches for file changes, opens the file, reads the rows it cares about, writes results back, and saves. This is the most complex option to implement (file locking, conflict resolution, handling partially saved files), but it provides the highest degree of user sovereignty.
The user literally owns the file. We have one prototype running this way for a corporate client in the financial sector who cannot store customer data on Google or Microsoft servers.
A fourth option — Airtable, Notion databases, Coda, and other “spreadsheet-adjacent” cloud tools — is technically viable but I do not recommend it. These platforms are not spreadsheets. They have rigid schemas, API rate limits, pricing that scales poorly with rows, and vendor lock-in.
They market themselves as “spreadsheets for people who hate spreadsheets,” which means the user does not actually have a spreadsheet and cannot take their data with them easily. The whole point of the wrapper pattern is to meet the user where they already are — which is Excel or Google Sheets, not a proprietary SaaS database with a spreadsheet- looking UI.
For most builders starting out, use Google Sheets. It is the fastest path, the API is mature, the quotas are generous enough for products up to tens of thousands of users, and you can migrate individual customers to other substrates later if needed.
If you are starting a new wrapper project, create a test Google Sheet, enable the Sheets API, and write a 20- line script that reads a range and writes a value back.
You can build a working wrapper system with as few as five columns in the sheet. These five columns are the minimum contract between the wrapper and the human. Everything else — customer name, product, price, address, phone, notes — is domain-specific and depends on what the sheet tracks. The five wrapper columns are universal.
Column 1: id (or order_id , tender_id , application_id ). A unique identifier for each row, generated when the row is created. The wrapper uses this to track which rows it has processed. It should be a short, unique string (we use the format TAP-4821 , BID-2914 , STP-883 ) so that it can be used as a payment reference or confirmation code without requiring a separate identifier. The ID is immutable once assigned.
Column 2: status . The current state of the row. This is the primary column the wrapper reads to decide what to do.
Agree on a small vocabulary (AWAITING_PAYMENT → PAID → PACKING → DELIVERED for orders; MATCHED → DRAFTED → APPROVED → SENT for applications; NEW → REVIEW → RESPOND → CLOSED for tenders) and enforce it with data validation. Every status transition has a defined meaning; the wrapper never invents a status.
Column 3: action_required . A boolean or short value that tells the human something needs their attention. The wrapper sets this to “APPROVAL NEEDED,” “REVIEW ERROR,” “MANUAL CHECK REQUIRED,” or similar when it encounters something it cannot resolve. The human filters on this column to see what needs attention. This column replaces notifications in most cases: if the human opens the sheet and filters action_required to non-blank, they see everything that needs them.
Column 4: wrapper_log . An append-only log of everything the wrapper has done to this row, with timestamps. Each wrapper run adds a line like “10:08 — payment confirmed via EcoCash” or “10:10 — confirmation SMS sent” or “14:22 — retry failed, will retry at next run.” The log is never overwritten. It is the audit trail for the row.
Column 5: last_updated . A timestamp that the wrapper updates every time it touches the row. This lets the human (and the wrapper) quickly identify rows that have not been processed recently — for example, orders that have been in “PACKING” for three days and may have been forgotten. It is also useful for incremental processing (the wrapper can process only rows changed since the last run, though I recommend reading all rows on every run for simplicity and safety at small scale).
That is it. Five columns. Add whatever domain-specific columns your use case requires — customer name, product, price, address, phone, CV link, tender link, salary range — but those five are the wrapper’s contract. When we deploy Tapstall for a new shopkeeper, we create a sheet with these five columns plus the domain columns the shop needs (item, size, colour, price, address, phone), we set up data validation on the status column, and the wrapper begins operating. Setup takes about ten minutes.
You do not need a framework to write a wrapper. You need a programming language with a spreadsheet API client, a cron scheduler, and HTTP libraries. Python is the obvious choice; Node.js works; Go and Rust work; even Bash with curl and grep works for the simplest cases.
Here is the structure of a wrapper, in pseudocode, so you can see how little there is to it:
def run_job():
# 1. Read configuration: which sheet, which tab, which columns, budget limits
config = load_config()
# 2. Open the sheet
sheet = open_sheet(config.sheet_id, config.tab_name) # 3. Read all rows (or rows since last_updated) rows = sheet.read_rows()
# 4. Check global budget before doing anything if count_actions_today() >= config.daily_budget: log("daily budget reached, pausing") return
# 5. Iterate through rows, find ones needing action for row in rows:
if row.status not in config.actionable_statuses: continue
# 6. Re-read the row immediately before acting (read/ write boundary)
fresh_row = sheet.read_row(row.id)
if fresh_row.status != row.status:
log(f"row {row.id} changed since read, skipping") continue
# 7. Check per-row budgets and approvals if requires_approval(fresh_row) and fresh_row.approval != "APPROVE":
continue
# 8. Perform the action (call API, send SMS, verify payment, etc.)
try:
result = perform_action(fresh_row) new_status = config.success_status log_message = f"{now()} — action succeeded: {result.summary}"
except ActionFailed as e:
result = e
new_status = config.error_status log_message = f"{now()} — action failed: {e.message}"
# 9. Write the result back
sheet.update_row(row.id, {
"status": new_status,
"wrapper_log": fresh_row.wrapper_log + "\n" + log_message,
"last_updated": now()
})
# 10. Check global budget after each action; break if exceeded
if count_actions_today() >= config.daily_budget: log("daily budget reached mid-run, stopping") break
# 11. Write run summary to log
log(f"run complete: {actions_count} actions, {errors_count} errors")
That is the whole pattern. A production wrapper adds error handling, retries with backoff, rate limiting on the external API, alerting on unexpected errors, and the reconciliation step — but the core loop is exactly what you see above. It reads rows, checks conditions, acts within budgets, writes back.
The most important implementation advice I can give you is this: write the wrapper to be restartable and idempotent. If the wrapper crashes after performing an action but before writing the result, the next run must not perform the action again. This means either: (a) perform the action, then immediately write the result (and accept that a crash between action and write may cause a duplicate action, which you detect via reconciliation), or (b) use idempotency keys on the external action so that retrying is safe (most payment and SMS APIs support idempotency keys — use them).
For Tapstall’s confirmation SMS, we use idempotency keys based on the order ID. If the wrapper sends SMS for order TAP-4821 and crashes before writing “SENT,” the next run re-reads the row (which still says “PAID” but the SMS log entry is missing), retries the send with the same idempotency key sms-TAP-4821-conf , and the SMS provider dedupes it. The customer receives exactly one SMS.
The four pillars of governability from The Governable Enterprise — Evidence, Authority, Resources, Recovery — apply to spreadsheet-wrapped systems exactly as they apply to any other autonomous system. But the spreadsheet substrate changes how each pillar is implemented.
Evidence. Evidence comes almost for free in a spreadsheet system, because the spreadsheet itself is the record. The wrapper_log column is the per-row audit trail.
The version history shows who changed what when. The fact file can be generated from the sheet itself: total rows, rows per status, action counts, error rates, cost per day — all are queries against the grid. The daily read is literally opening the sheet and reading the summary tab. There is no log aggregation infrastructure, no observability platform, no separate monitoring stack. You can see everything by looking at the sheet.
This is a double-edged sword. Because the evidence is easy to see, operators tend to be lax about reconciliation.
They assume that because the sheet shows “PAID,” payment was received. The reconciliation step must still exist, and it must compare the sheet against independent records (payment provider receipts, SMS delivery receipts, email send logs). The fact that the spreadsheet is the interface does not mean the spreadsheet is always correct.
Authority. The authority matrix applies as normal: each wrapper job has an autonomy level, thresholds, and escalation targets. In a spreadsheet system the enforcement is simpler because the wrapper is the only code that can perform actions; there is no admin dashboard where an operator can accidentally click a button that triggers a mass send. The only way an action happens is (a) a scheduled wrapper run, or (b) a human manually performing the action outside the wrapper. The matrix controls (a). For (b), you rely on training and the principle that high-stakes actions (moving money, sending to employers) are not available as buttons anywhere.
The status-column vocabulary is the primary authority- enforcement mechanism. If a row is in status “PAID,” the payment watcher will not look at it. If the approval column is blank, the send wrapper will not act. If a human manually sets a row to “CANCELLED,” the wrappers will not touch it because “CANCELLED” is not an actionable status.
Resources. Budgets are enforced the same way as in any autonomous system: per-run caps, per-customer caps, monthly caps. In a spreadsheet system it is particularly easy to implement a budget because the wrapper can count actions by counting rows with today’s date in the wrapper_log. No separate metrics system needed.
Recovery. The kill switch pauses the cron jobs. Pausing is instant. Rollback means redeploying the previous version of the wrapper code (which is a 200-line Python script you keep copies of). Because the sheet holds all state, rolling back the wrapper code never loses data — the worst case is that a bug writes incorrect statuses into a column, which you can revert via the sheet’s version history. This is one of the great advantages of the pattern: production state lives in the user’s spreadsheet, which is versioned and can be rolled back independently of the code.
Incident response is simpler with a spreadsheet system because diagnosis involves reading the sheet. When something goes wrong, you do not start by grepping logs in Datadog. You open the sheet, filter the wrapper_log column for errors, find the problematic rows, and see exactly what happened. In the March 14 Bidfold incident, I diagnosed the cause within three minutes of waking by opening the sheet and seeing that every subscriber had seven matches against their filters when they normally had one to three — the evidence was right there in the grid.
Spreadsheet-wrapped systems fail in ways that traditional SaaS systems do not. You need to be prepared for the spreadsheet-specific failure modes.
The user breaks the schema. The most common failure: a shopkeeper accidentally renames the “payment_status” column to “Payment Status” (with a space and capital P), or inserts a new column between “id” and “status,” or sorts the sheet in a way that confuses the wrapper, or deletes a column entirely. The wrapper must handle this gracefully. Every wrapper starts by validating that the expected columns exist and have the expected names; if they do not, the wrapper logs an error to the wrapper_log sheet (a separate tab that the wrapper owns and the user should not edit), alerts the operator, and pauses — it never proceeds with a broken schema. The alert includes a plain-language message: “The ‘payment_status’ column appears to have been renamed or deleted in Rutendo Knitwear’s sheet. The payment watcher has been paused. Please check the sheet.”
The user adds data the wrapper does not expect. A shopkeeper puts text like “PAID!!!” in the status column instead of “PAID,” or puts “N/A” in a numeric column, or merges cells across rows (which breaks every spreadsheet API known to man). The wrapper must parse defensively: case-insensitive matching, trim whitespace, ignore punctuation, reject values it does not recognise rather than guessing. Unrecognised values trigger an alert, not a crash.
Concurrent edits. The human and the wrapper are editing the sheet simultaneously. This is the race condition discussed in Chapter 7, solved by the re-read-before-write rule. If the wrapper is going to write to a row, it reads the row one final time immediately before writing and compares what it sees to what it read at the start of processing. If anything has changed, it abandons that row for this run and tries again next time.
Accidental deletion. A shopkeeper accidentally deletes a row that the wrapper has already processed. This is fine — the wrapper will not recreate deleted rows (because it does not hold canonical state), but payment records and sent messages are preserved in the external systems (EcoCash, the SMS provider). The wrapper can detect that a previously known row has disappeared (by tracking the IDs it has seen) and can flag the deletion for review, but it should never resurrect deleted rows automatically. Deletion is a deliberate action.
API outages. The Google Sheets API is down, or the file is not shared with the service account, or the user has revoked access. The wrapper must fail gracefully: log the error, alert the operator, and retry on the next run. It must not take any destructive action when it cannot read the sheet. Treat an unreadable sheet the same way you treat a paused system: do not act until you can see.
None of these failure modes are fatal. All of them are detectable quickly if the wrapper has reasonable validation, good error logging, and the operator does the daily read.
The most important defence against spreadsheet-specific failures is the same as the defence against all operational failures: build a boring wrapper that fails loudly and obviously, and look at the sheet every morning.
The objection I hear most often from technically trained people is: “A wrapper around a spreadsheet is a hack. When the business outgrows the spreadsheet — when there are 50,000 orders, when there are 15 staff, when there are regulatory reporting requirements — you’ll have to migrate to a proper system, and migration will be painful.”
There are three answers to this objection.
First: most businesses never outgrow the spreadsheet.
The average Tapstall merchant processes 20-70 orders per week. The average Bidfold subscriber reviews 5-30 tender matches per day. STPi processes a few hundred applications per week total across all subscribers. At these volumes, Google Sheets does not even blink. The performance limit for Google Sheets is around 5-10 million cells, which for an order sheet with 20 columns means 250,000-500,000 rows — approximately 20 years of 50-orders-per-day volume. For most small businesses, the spreadsheet will outlast the business itself.
Second: when a business does grow to the point where a spreadsheet is genuinely constraining, the wrapper architecture makes migration less painful, not more.
Because all the business logic lives in the wrapper code (not in spreadsheet formulas that are difficult to extract), and because all state lives in a simple row-per-record structure (not in a custom database schema that requires a migration team), you can swap the backend from a Google Sheet to a PostgreSQL database by changing one adapter in the wrapper. The wrapper continues to run the same jobs, using the same logic, with the same governance controls — it just reads from a database instead of a sheet API. The user can continue to use a spreadsheet view (the wrapper writes to a Google Sheet as a cache/reporting layer), or you can add a web UI, or both. The architecture lets you migrate gradually.
Third: even if migration eventually happens, the business has already received years of value from the wrapper in the meantime. A small business does not need to wait until they are “big enough for a proper system” to have automated order processing, payment reconciliation, and customer confirmation. They can have all of that from day one via a wrapper, and when they grow to the point where they need ERP-level accounting, they can take their data to any system — because it is in a spreadsheet, which every ERP and accounting package can import.
The argument that “you will have to migrate eventually” is an argument for never starting. It is the same argument that says you should never write a prototype in a high-level language because you might have to rewrite it in Rust when you scale. Most prototypes never need to scale, and most small businesses never need an ERP. For the ones that do, the wrapper is a perfectly good starting point that produces a clean data set for the migration.
I have seen businesses running on spreadsheets with wrappers processing $500,000 a year in revenue with a staff of four and zero operational incidents in two years. I have seen businesses running on $200/month ERP systems with six-month implementation times, three consultant engagements, and staff who still maintain parallel spreadsheets because the ERP does not actually cover their workflow. The wrapper approach does not prevent migration. It prevents premature migration, which is far more expensive than late migration.
Export your production data as a CSV from Google Sheets. Open it in Excel, in LibreOffice, and in a text editor. If any of these cannot read it, your data is locked in.
Write a version of the wrapper that reads from a CSV file instead of the Google Sheets API. If the wrapper is well-structured, this should take under an hour. This is the migration path.
Write down the criteria you would use to decide when to migrate away from the spreadsheet. Be specific (row count, number of concurrent users, regulatory requirement). Do not migrate until a criterion is met.
There is a moment in every builder’s development when they discover event-driven architecture, and they immediately want to rebuild everything to be real-time.
Webhooks, message queues, streaming pipelines, serverless functions that fire within milliseconds of a state change — the promise of instantaneous response is seductive.
For customer-facing actions taken by an operator on behalf of a business in our market, real-time is almost always the wrong choice. Let me tell you why, beyond the operational arguments I made in Chapter 9.
Real-time systems destroy the operator’s ability to reason about time. When actions happen milliseconds after triggers, there is no “before the run” window where the operator can review, reconcile, and approve. There is only a continuous stream of actions happening now, all the time, and the operator is perpetually playing catch-up. A scheduled system is predictable: actions happen at known times, the operator knows when to look, and the operator knows when it is safe to step away from the desk. A real- time system demands constant vigilance. That is not a sustainable way to operate a small business.
Real-time systems also destroy natural batching. A customer who places an order at 2:17 a.m. does not need a confirmation SMS at 2:17 a.m. They need it when they wake up, along with any other notifications that arrived overnight, in a single batch at 8 a.m. A single notification at 8 a.m. is noticed and acted on. Seven notifications spread across the night are silenced by Do Not Disturb and ignored in the morning. Batching is not a delay. It is respect.
And real-time systems cost more. Not just in server costs — they cost more to monitor, more to debug, more to keep reliable. A cron job that runs once per day can fail and be fixed before the next run with zero customer impact. A real- time webhook handler that fails loses data forever unless you build a complex retry and dead-letter infrastructure that rivals the complexity of the system itself.
None of this is to say that real-time is never appropriate.
A payment confirmation page in a customer-facing checkout flow should respond immediately (that is synchronous UX, not an autonomous wrapper). A chat application must deliver messages in real time. A fire alarm must trigger instantly. But for the vast majority of back-office business automation
—
order
Let me return to Rutendo in Eastlea, because her story is where this book started and it is where the argument lands.
Rutendo signed up for Tapstall three weeks after I visited her shop. We did not ask her to migrate her orders into our system. We did not give her a new login, a new password, a new dashboard to check every morning. We gave her a storefront link that she shared with her customers on WhatsApp. We connected her existing Google Sheet to the wrapper. When customers ordered, new rows appeared in her sheet, the payment status turned green when EcoCash confirmed, and a confirmation SMS went out without her lifting a finger.
Rutendo did not learn a new tool. She kept working exactly as she had been working — the spreadsheet open on her laptop, sorted by date, colour-coded, printed every morning. The only difference was that she no longer had to manually check EcoCash, type “PAID” into the column, or send a confirmation SMS. Those things happened on their own, and she could see them happening in her sheet.
In her first month on Tapstall, Rutendo processed 184 orders (up from about 110 the previous month, because sharing the storefront link was easier than taking orders over WhatsApp DMs). She spent approximately one hour less per day on order administration. She used that hour to knit.
This is the end state I want you to imagine. Not a future where every business runs on a sophisticated AI-powered dashboard. A future where every business runs on the tool they already know, augmented by a thin layer of quiet, boring, governable automation that handles the tedious parts without asking the user to become a software expert.
A future where the wrapper does the work that does not require a human, and the human does the work that does — designing the jerseys, talking to customers, deciding which yarn to buy, packing the orders, running the business.
The dashboard is not the future of business software for SMEs. The spreadsheet is. The spreadsheet was already here. It was here before SaaS was invented, and it will be here after the current generation of venture-backed dashboard companies has pivoted or shut down. A billion people know how to use a spreadsheet. Almost no one knows how to configure an ERP. The job of the software builder is not to replace the spreadsheet with something “better” that the user does not want and will not use. It is to wrap the spreadsheet in the small amount of autonomous action that makes the user’s Tuesday genuinely easier, and to build it so that the wrapper is governable, honest, and quiet.
That is it. That is the architecture. One sheet, one set of columns, one wrapper per job, one human reading the sheet every morning. Everything else is detail.
Close this book. Open a spreadsheet. Put five columns at the top of a blank tab.
Write the wrapper.
Find one repetitive task in your own business that you do manually and that could be handled by a wrapper around a spreadsheet. Build the wrapper this week. It does not need to be perfect. It needs to save you one hour per week.
Show a small business owner the result. If they ask “do I need to learn a new system?” you have succeeded.
Stop building dashboards.
There is a genre of software writing that celebrates the spectacle. A screen full of live-updating charts. A deployment pipeline that pushes to production fifty times a day. An AI that writes its own code. An architecture diagram with fifteen services connected by arrows in seven colours.
These things are impressive when you see them on stage at a conference. They are impressive when you work at a company of a thousand engineers with dedicated SRE teams and multi-million-dollar cloud budgets.
For a small business in Harare — or Houston, or Hanoi, or Hull — these things are not impressive. They are noise.
They get in the way. A small business does not want a dashboard; it wants the orders to come in, the payments to confirm, and the SMS to go out without someone having to do those things by hand. A small business does not want a CI/CD pipeline; it wants the software to keep working, quietly, without surprises. A small business does not want artificial intelligence; it wants boring automation that handles the tedious parts so the human can do the human parts.
The wrapper architecture described in this book is quiet software. It runs on a schedule, not in real-time. It does not draw attention to itself. It does not send marketing emails about its own features. It writes into cells in a spreadsheet that the user already has open. If it is working well, the user barely notices it is there. They only notice when it stops, and when it stops it pauses before it does harm.
I believe this is what most software should be. Not an event. Not a spectacle. Not something that demands your attention every fifteen minutes. A quiet servant, working in the background, handling the boring parts with discipline and humility, while you do the actual work that makes your business yours.
The minimum columns for any wrapper-operated sheet: COLUMN
PURPOSE
WRITTEN BY id
Unique
immutable
identifier
(e.g.
TAP-4821)
Creator (storefront, scraper, human) status
Current state, from
controlled vocabulary
Both human and wrapper action_required
What the human must
do (blank = nothing)
Wrapper wrapper_log
Append-only audit trail
with timestamps
Wrapper last_updated
ISO timestamp of last
change
Wrapper Add domain-specific columns freely. Do not remove or rename these five without updating the wrapper code.
def run_job():
config = load_config()
sheet = open_sheet(config.sheet_id, config.tab_name) rows = sheet.read_rows()
if count_actions_today() >= config.daily_budget: return PAUSE_BUDGET
for row in rows:
if row.status not in config.actionable_statuses: continue
fresh_row = sheet.read_row(row.id) # re-read boundary if fresh_row.status != row.status:
continue
if requires_approval(fresh_row) and fresh_row.approval != "APPROVE":
continue
try:
result = perform_action(fresh_row) new_status = SUCCESS_STATUS
msg = f"{now()} — OK: {result.summary}" except ActionFailed as e:
new_status = ERROR_STATUS
msg = f"{now()} — FAIL: {e.message}" sheet.update_row(row.id, {
"status": new_status,
"wrapper_log": fresh_row.wrapper_log + "\n" + msg, "last_updated": now(),
})
if count_actions_today() >= config.daily_budget: break
For an order-processing sheet: AWAITING_PAYMENT → PAID → PACKING → SHIPPED → DELIVERED / CANCELLED / REFUNDED. For an outbound messaging sheet: DRAFTED → REVIEWED → APPROVED → SENT / REJECTED / FAILED. For a matching sheet: MATCHED → NOTIFIED → VIEWED → RESPONDED / EXPIRED.
Keep the vocabulary small (fewer than eight states per sheet). Enforce with data-validation dropdowns.
External reads/polling (checking for payments, scraping): 2–5 minutes during business hours.
Customer-facing sends (SMS, email): 5–15 minutes during waking hours only (7 a.m.–7 p.m. recipient time).
Batched digests: once per day, after reconciliation and after the daily read.
Reconciliation: before any money-spending action runs.
Wrappers never run on webhook/event triggers.
Schedule everything.
Before deploying a wrapper to production, verify: The five columns exist with correct names in every sheet.
Data validation enforces the status vocabulary.
The wrapper re-reads rows immediately before writing.
Idempotency keys are used on every external action.
Daily and per-run budgets are set and enforced.
Approval columns exist for Level 1 actions.
The kill switch pauses all jobs within 10 seconds.
For Rutendo, who did not need another dashboard and told me so on a Tuesday afternoon in August. For Tendai, who wrote the first payment-watcher wrapper and said “why are we overcomplicating this” when I proposed a queue-based architecture. For Farai, who tested every column name against three shopkeepers before any code was written. For the 187 shopkeepers, 200+ Bidfold subscribers, and 400+ STPi candidates who let their businesses and careers run on a system that writes into a spreadsheet. For the open-source developers who build and maintain the Google Sheets API client libraries, without which this book would not exist at any price.
From Spreadsheet Interface to Governable Autonomy: The architecture of businesses that run on a sheet First edition, November 2026 © 2026 Courage Garikai. Licensed under CC BY 4.0. Published by ColdCode Si Labs, Harare, Zimbabwe DCAI — Distributed Cognitive Autonomous Infrastructure series Cover: ColdCode Si Labs cream/navy/oxblood pamphlet design Trim: 6×9″ trade paperback Typeset in Georgia (serif body) and Helvetica Neue (sans-serif heads) Twenty-two chapters · Five column patterns · One architecture Printed digitally on demand; no copies warehoused
Online reader and updates: https://library.coldcode-si- labs.workers.dev/preview/spreadsheet
Contact: couragegarikai@atomicmail.io Source code patterns: https://github.com/king-kunta-cpu/wrapper-patterns Pass it on to a builder who is tired of shipping dashboards nobody uses.