Replacing Increddy's commerce backend meant two teams working on two completely separate git repositories, owned by separate people, with no shared codebase to force alignment. The interesting part of this project isn't just the architecture; it's how two independently owned repos converged on a working system without drifting apart the way parallel workstreams usually do.
Why a monorepo wasn't the answer
The instinct when coordination is hard is to reach for a shared repository. That would have solved the wrong problem here. The frontend deployed to Vercel; the backend deployed to AWS EC2. Different teams owned each one. A shared folder structure doesn't make a frontend team correctly guess what API shape a backend will produce, and it doesn't make a backend team correctly guess what a frontend actually calls. The coordination problem was a contract problem, not a repository-location problem.
The documents that did the work
Two structured documents carried the coordination:
- A gap tracker, mapping every frontend data need to the backend capability meant to serve it: built, planned, or missing. This turned "does the backend support X yet" from a question into something either side could check without asking the other.
- Matched task lists, one for backend work and one for frontend work, with explicit dependency IDs linking a frontend task to the specific backend task it needed finished first.
The rule that mattered more than the documents
Documents drift. A gap tracker can say a capability is "done" because someone updated it optimistically, not because it's actually correct against the live system. The rule that made this process work wasn't the documents themselves; it was a standing instruction to both teams: verify every claim against running code and a live backend, not against the other side's notes, and not against your own.
That rule caught real problems. Several claims in the backend team's own status notes turned out to be wrong or incomplete once checked against the actual running system, not because anyone was being careless on purpose, but because a written status update is a claim, and claims drift from reality the moment nobody re-checks them. Catching that during development, against a live backend, is far cheaper than catching it during a staging walkthrough days before launch.
Coordinating two teams on separate repos?
Tell us how your frontend and backend work is currently split. We'll tell you whether a contract-document process like this fits, or whether your situation actually calls for something simpler.
Talk to an engineer →The rule
If two teams can't share a codebase, don't try to force alignment through one. Give them a living contract instead: a gap tracker and dependency- linked task lists, both cheap to maintain and easy for either side to check without a meeting. Then enforce the one rule that actually keeps a contract honest: verify against running code, not against notes, on both sides, including your own. For the architecture this process was coordinating, see how we replaced Shopify's backend without touching the frontend. We run engagements this way under our process.