Act IV: The Joinery
Bringing The Black Box Into The Room
The rep was good at his job, which is what made it worse. A customer had written in about her box—the frozen coffee had arrived, the right number of capsules, nothing broken, no complaint about the product at all. She just wanted to know why these ones. She drank her coffee black, she’d said as much in her preferences, and the box had three roasts she’d flagged as too bright the last time anyone asked. So she wrote in, politely, the way people write when they assume there’s a person on the other end who decided: Can you tell me why I got these?
He couldn’t. He looked. He pulled up her account, her order history, her stated preferences, the inventory notes, and none of it told him why the system had chosen the coffees it chose, because the choosing happened somewhere he couldn’t see—in a model that weighed her history and her preferences and what was in the freezer that week and some number of other things, and emitted a box. The reasons were real. The reasons were also buried in code that nobody on his side of the building could read, and the people who could read it were three time zones and one ticket queue away. So he did the only humane thing available to him. He apologized, told her he’d make sure the next box leaned darker, and sent her a substitution he picked by hand, because picking it by hand was the only part of the transaction he could actually explain.
Six months later, some version of that conversation was happening dozens of times a week. Not a crisis. Nothing on fire. Just a steady, low-grade tax on everyone’s trust—customers who wanted a reason, reps who didn’t have one, engineers who’d built something genuinely clever and watched it become the thing support quietly dreaded. The algorithm worked. By every metric the data team looked at, it worked well. And it was making the company a little less able to talk to its own customers every single day, because the one question it couldn’t answer was the only question that mattered to the person asking it.
Here is the thing the algorithm had become, and the word is exact, so let me use it: a black box. Something goes in, something comes out, and the part in the middle is sealed. Not maliciously. Not even carelessly—Cometeer’s system was the opposite of careless, it was the product of real thought about how to delight a subscriber. But it was sealed all the same, and a sealed system has a property that doesn’t show up in any dashboard: nobody who has to answer for it can see inside it.
That property is more expensive than it looks, and it gets more expensive in a shape worth tracing, because the shape is the whole argument. It starts with a system people can’t see into. Because they can’t see into it, they don’t quite trust it—and low trust in an automated system isn’t a feeling, it’s a behavior, it’s the rep hand-picking a substitution because the machine’s choice can’t be defended. Because the people who run the business don’t trust the system, they route around it, and the cross-team collaboration that would actually improve it never happens—the support team has the customer signal and no way to feed it back, the data team has the model and no idea what’s annoying anyone. Because nobody can explain a decision, every support ticket that touches the black box takes longer to resolve, because resolving it means apologizing for a reason you don’t have. And because no one outside the original build can see what the system is doing, improving it stays the exclusive, bottlenecked privilege of the handful of engineers who wrote it—which means it improves slowly, if at all, and the slowness compounds everything above it.
Low visibility, low trust. Low trust, no collaboration. No collaboration, slow resolution and slower improvement. It’s a cascade, and it runs downhill, and the thing at the top of the hill is simply whether the people who have to live with the system can see it.
If you can’t see it, you can’t trust it. Hold onto that, because it is the whole of the cure as well as the whole of the disease, and most of this chapter is just that sentence pointed at one surface after another. If you can’t see it, you can’t trust it—and the corollary, the one that turns a complaint into a plan, is that visibility is something you build, deliberately, at whatever level of effort the problem deserves. You do not have to choose between a sealed box and a cathedral. There is a ladder between them.
The ladder has five rungs, and the discipline is to start on the lowest one that solves your actual problem and climb only when usage tells you to. Teams get this backward constantly. They see an invisible process, decide it needs a real interface, and start scoping a custom application—which is the top rung, the most expensive rung, the rung you reach for last—when a great deal of the time the bottom rung would have done. So we’ll take the rungs from the bottom, because the bottom is almost always where you should be standing.
The lowest rung is tags. Shopify gives you tagging on nearly everything—products, orders, customers—and a tag is the lightest possible control plane you can put on an automated process. It is a flag a human can read and a human can set, no deploy, no engineer, no ticket. This sounds too humble to matter until you watch it work. The wine retailer—the same Italian brand that turns up elsewhere in this book wearing a few different hats—controls which products sync to its ERP with tags. An operations person who has never written a line of code, and never will, adds a tag, and the product flows; removes it, and it stops. The control plane for a piece of integration logic that used to require an engineer is now a field that a person who actually understands the business can operate from the admin, while drinking coffee, between other things. That is the bottom rung doing the entire job, and it cost nothing to build because the platform already had it.
The second rung is metafields, for when a flag isn’t enough—when the thing you need to make visible has structure, parameters, values, not just on and off. The same wine retailer that drives its ERP sync with tags drives its third-party pricing engine with metafields: the parameters the engine uses live in structured fields on the product, where a merchandiser can read them, change them, and watch the effect, all inside Shopify, without opening a black box or filing a request against one. Tags are a light switch. Metafields are the dials underneath it. Both share the property that matters—a non-engineer can see the state of the system and change it—and both live at the bottom of the ladder precisely because they require nothing built. You are surfacing logic by storing it where people can already look.
The third rung is where you start building, and it’s Admin UI Extensions—native interfaces that live inside the Shopify Admin, where the team already spends its day. This is the rung that would have saved the Cometeer rep. The fix for the black box was not to make the algorithm simpler or to hand support a PDF nobody would read. It was to build, inside the Admin, a view that visualized the decision—that showed, for a given box, the factors the model had weighed: this customer’s stated preferences, her order history, what was in the freezer that week, the relative pull of each. Suddenly the box wasn’t sealed. The rep could open the order, see why these coffees, and tell the customer the truth instead of an apology. And then the part that the team didn’t predict and couldn’t stop smiling about happened: once people could see the decision, non-technical team members started suggesting how to make it better. The support lead noticed a pattern the data team had missed. Someone in ops proposed a weighting change. The model improved faster than it ever had, not despite leaving the engineers’ hands but because it had—visibility had turned a sealed system the whole company worked around into a shared object the whole company worked on.
The fourth rung accepts a truth about people that the third rung doesn’t: sometimes the team you need to reach doesn’t live in the Shopify Admin at all. Your support organization lives in Zendesk, or Kustomer, or whatever the help desk standardized on three years ago, and asking them to switch tools to see what they need is asking them to switch tools dozens of times a day, which means they won’t, which means the visibility you built sits in a window nobody opens. So you bring the logic to them. This is third-party platform integration—surfacing your custom behavior inside the tool the team already has open. MeUndies did exactly this with its subscription logic: rather than make a support agent leave Zendesk to understand or change a customer’s subscription, the subscription surfaced inside Zendesk. The agent could see upcoming shipments, skip a delivery, update preferences—all without leaving the ticket they were already in. The system didn’t get simpler. It got closer. It moved to where the people who needed it were standing.
The fifth and highest rung is the custom frontend—a full application, embedded in the Admin or standing on its own, built when the operation is specialized enough that nothing below it will fit. This is the cathedral, and the warning that comes with it is the same warning that comes with anything expensive: most of the time you don’t need it, and the tragedy of the ladder is how often teams start here. When you genuinely do need it, the build is no longer the multi-quarter undertaking it was a few years ago—acceleration platforms like Retool, and others in that family, can take a meaningful bite out of the time, sometimes most of it. But cost coming down is not a reason to climb. It’s a reason to climb gracefully when the lower rungs have honestly run out, and not one rung before.
So you have a ladder, and the question becomes which rung, and the answer is not a matter of taste—it maps almost mechanically to the shape of the problem, which is the mercy of the whole framework. If you need simple status that a human sets and the system reads, you need a tag. If you need structured parameters a human tunes and the system consumes, you need metafields. If you need a rich view of something complicated, and the people who need that view live in the Admin, you need an Admin UI Extension. If the people who need it live somewhere else, you need to surface it in that somewhere-else. And if the operation is specialized enough that none of those fit, only then do you build the frontend. Match the rung to the problem and you spend the least money that solves it. Reach for the top rung by reflex and you will spend a quarter building a cathedral to hold a light switch.
There is one more piece of discipline, and it’s about sequence rather than selection. Don’t start by surveying every invisible process in your business and building visibility for all of them. Start by finding the one that hurts the most—the black box that is costing you the most trust, the most resolution time, the most quiet daily friction—and put it on the lowest rung that opens it. Then watch how it gets used. Usage will tell you whether the bottom rung was enough or whether the pain has earned a climb. The Cometeer black box earned an Admin UI Extension because the cost of its invisibility was measured in dozens of support conversations a week; a process that costs you one confused email a month has earned a tag, if that. Let the pain pick the rung, and let usage tell you when to climb.
This is not, in the end, an essay about interfaces. It’s an essay about whether the people in your building can look the system in the eye. When you migrate to Shopify, you will build automations—pricing logic, sync logic, subscription logic, recommendation logic, all the clever behavior that makes an enterprise store feel less like a catalog and more like a business. Every one of those is a candidate black box. Every one of them can be the thing the support rep dreads, or the thing the support rep opens and explains. The difference is not whether the logic is good. Cometeer’s logic was good. The difference is whether you spent the small, deliberate effort to bring the box into the room—to put it where the ops person, the support agent, the merchandiser can see it, touch it, and tell you when it’s wrong.
The signs that you’ve done it are quiet and they accumulate. Support tickets that used to escalate now close on first contact, because the agent can see the answer. The internal confidence in the automated systems goes up, which sounds soft until you notice the team has stopped routing around the machine and started trusting it. Cross-team collaboration goes up, because there’s now a shared object to collaborate on instead of a sealed box to file tickets against. Maintenance time goes down and so does the error rate, because the people closest to the problem can see the problem. None of these will show up as a launch announcement. They show up as the slow disappearance of a particular kind of bad day.
And it’s worth ending where the platform makes the bottom of the ladder almost free, because the team migrating onto Shopify has a chance the team on the old stack rarely had. Take the specialty food brand we’ve been following across this book—the one moving its olive oil and vinegars and gift sets off Magento. On the old platform, the rule for which products synced to the back office lived in a sync script and a set of conventions in someone’s head, and the way the operations director kept it honest was a spreadsheet she reconciled by hand, because the spreadsheet was the only surface she could actually see. On Shopify, that same control becomes a tag she sets herself, modeled on exactly what the wine retailer built—and one of her spreadsheets, the one that existed only to track what the sync was doing, quietly has no reason to exist anymore. Nobody announces it. She just opens it one week, realizes she hasn’t touched it in a month, and closes the tab. The black box that used to live in a script she couldn’t read is now a field she owns. That is the whole project, in one small recovered hour: the box came into the room, and the room turned out to be hers all along.
Here lies the algorithm nobody could explain. It chose well. It chose alone. We brought it into the room, and it turned out it had wanted company.