Ten Years of Data, One Handshake: What a Family Business Taught Me About Migration

Every consultant has a project they measure the rest of their work against. Mine lasted eleven months, involved a family-owned wholesale distributor in the Ohio Valley, and taught me more about software than any framework I've since adopted.

The company — I'll call them Hartwell Supply — had run their entire operation on a custom-built inventory and invoicing system since 2009. The original developer had retired to Florida. The source code lived on a single aging server under a desk in the back office. Every employee, from the warehouse floor to the owner's desk, had memorized its quirks the way you memorize the creaks in an old house.

They needed out. They also could not afford for anything to break. Those two facts pulled in opposite directions for the better part of a year, and navigating that tension is where the real lessons lived.

The First Meeting Was Not About Software

I came in prepared to talk architecture. Instead, I spent the first meeting listening to the owner's daughter — effectively the COO — describe how her father still printed every invoice because he didn't trust screens. I heard about the one shipping clerk who knew why certain customers got handwritten notes on their packing slips. I learned that a particular pricing rule existed because of a handshake deal made at a county fair in 1994.

None of this was in the requirements. All of it shaped the requirements.

The mistake I see in failed migrations is treating the legacy system as a problem to escape rather than an archive of accumulated decisions. Hartwell's software was ugly, but it encoded fifteen years of operational wisdom. My first deliverable wasn't a proposal. It was a map of why — a document cataloging every odd behavior and the business reason behind it.

Scope Is a Conversation, Not a Contract

The original statement of work covered data migration, a modern web application, and training. Reasonable. Also insufficient.

By month three, it was clear that "training" really meant helping a workforce that had built identity and pride around the old system grieve it a little. By month five, "data migration" meant sitting with the bookkeeper while she explained that three "duplicate" customer records were, in fact, distinct entities for tax reasons nobody had written down.

A rigid scope would have made these changes feel like failures. Instead, we treated scope as a rolling conversation. Every two weeks, we revisited what mattered. When the owner's father passed away in the spring, we paused feature work for three weeks and used the time to build the reporting views he'd asked about — the ones that let the family see the business the way he had.

That pause cost me billable hours on paper. It bought something no invoice line can capture: the family's conviction that I was invested in their outcome, not just their budget.

Migrate in Shadows, Not in Leapfrog

Technically, the engagement went the way textbooks recommend but rarely describe honestly. We ran both systems in parallel for four months. The old system remained the system of record; the new one shadowed it, ingesting the same orders and flagging discrepancies daily.

The shadow period was humbling. The new system missed edge cases I'd have sworn were impossible — customers with two shipping addresses and one billing address, seasonal price breaks keyed to handwritten date ranges. Each discrepancy became a small archaeology project. We fixed, re-ran, compared again.

When we finally flipped over, it was almost anticlimactic. The warehouse crew had been dual-entering orders for weeks. The cutover was a Tuesday. There was cake. By Thursday, nobody missed the old server under the desk.

What No Tutorial Covers

People ask what stack we used, as if the answer explains the success. It doesn't. The transferable lessons were these:

Listen before you architect. A week of listening saved a month of rework. The client's operational folklore — the fair handshake, the printed invoices — was the real specification.

Budget for grief. Every migration asks people to give up mastery they spent years earning. Plan for that emotionally, not just procedurally. Training is partly a funeral.

Run the shadow, eat the cost. Parallel operation is expensive and tedious. It is also the only honest way to know your migration worked. Discrepancy reports are cheaper than downtime.

Let scope breathe. A statement of work is a starting hypothesis, not a fortress. The engagements that go right are the ones where both parties can say "we learned something" without it becoming a negotiation.

Hartwell Supply still runs that system. They've since added a second location, and the daughter tells me the reporting views — her father's views — get checked every Monday morning.

I've built larger systems since. I'm not sure I've built more meaningful ones. The framework you choose will be obsolete in five years. The trust you build, if you build it right, won't be.