That setup is cheap and fast to ship. It also means a change on one side can quietly break the other, and nothing crashes when it does.

The failures we kept hitting

None of these threw an error. Each one just made the product slightly wrong:

• A renamed quiz field. The form posted a field under a new name while the endpoint still read the old one, so that answer never reached the lead.

• A button calling a route that no longer existed. The CRM UI called an /api/... path that had been moved. The button looked fine and returned a 404 into the console.

• A stage string with a typo. Leads move through named stages. One code path wrote a stage name that was not in the list, so those leads sat in a stage that nothing ever acted on.

• Two pages disagreeing. A copy edit changed a number on one page but not on another. The site contradicted itself for a day, and a plain string search did not find it because the number sat in its own <span>.

Unit tests did not catch these, because each half was correct on its own. The bug was in the contract between them.

The fix: one script that reads both halves

We wrote contract_sync.py, a plain Python script with no model judgement in it. It reads the repo as text and checks the places where the site and the CRM touch:

The route check is the simplest example. Pages Functions map files to URLs, so the script walks functions/api/ and turns each file path into the route it serves:

def api_routes():
    routes = set()
    for p in glob.glob(os.path.join(ROOT, "functions", "api", "**", "*.js"), recursive=True):
        r = rel(p)[len("functions"):-3].replace(os.sep, "/")   # /api/leads/index
        if r.endswith("/index"):
            r = r[:-6] or "/"
        routes.add(re.sub(r"\[[^\]]+\]", "*", r))              # [id] becomes *
    return routes

Then it collects every /api/... string the front end calls and fails on any that has no matching route. Exit code 0 means the halves agree. Exit code 1 prints exactly what drifted.

Two details made it trustworthy:

1. Compare tag stripped text, not raw HTML. Our number mismatch survived a global replace because the number sat in its own element. The copy checks strip tags first and compare what a reader actually sees.

2. One rule for new coupling. Whenever someone adds a new point where the site and the CRM touch, they add a check for it in the same change. That is how the list stays complete without anyone having to remember.

Testing the test

A gate that never fails proves nothing. So we wrote a negative control: a shell script that plants known violations into a copy of the project (a renamed field, a missing route, a bad stage and so on), runs the checker, and expects every one to be caught. When we first set it up it planted 7 violations and caught 7.

One lesson from building that control: make the backup before you plant anything, and assert the backup exists. An early version used cp a || cp b, which skips the second copy when the first succeeds, left the restore path empty, and would have left the planted bugs in the working tree.

Other traps on Cloudflare we learned the hard way

• PBKDF2 iterations. 120,000 iterations passed every local test and then threw an uncaught exception (error 1101) in production. Pinning to 100,000 fixed it.

• D1 has no migration ledger unless you build one. We apply migrations by hand, so the only reliable way to know what is applied is to probe the schema for each migration's tables and columns.

• A column no code writes. One column existed in the schema, the query and the UI, and every row still read 0, because the INSERT never set it. Syntax checks and an end to end test both passed. Now, after a feature runs, we read the row it should have written.

• A deploy turns on every pending setting. Pages applies all environment variables and secrets at the next deploy, not just your files. A pure copy change once switched on outbound email because a secret had been added earlier. We now compare setting names against the live deployment before every upload.

What it costs

The checker is one file of standard library Python, so it runs before every deploy along with our other gates, and a red result blocks the release.

If your website and your back office share a database, the cheapest test you can write is the one that reads both halves and checks they still agree.

We build and run Dental Link, a dental concierge for international patients in Ho Chi Minh City and Hanoi, Vietnam. The platform described here is its website and CRM.