Why We Ban Mocks and Demo Mode

Most products grow a hidden second personality: a demo mode, a mock flag, a "fake data" path that exists so the app looks good in a screenshot or a sales call. We don't have one, and it's a hard rule: no IS_MOCK, no DEMO_MODE, no NEXT_PUBLIC_DEMO_MODE, no synthetic-data branch. Every code path — including the demo account — hits real services. This post is why a rule that sounds inconvenient actually makes the product more honest and the engineering better.

What demo mode quietly costs you

A DEMO_MODE flag feels harmless. Here's what it actually buys you over time:

• A second code path that's never really tested. The fake path diverges from the real one, and the divergence is invisible until a customer hits the difference.
• Demos that lie. "It works in the demo" can mean "the demo never called the real thing." You ship confidence you didn't earn.
• Bugs that hide behind the flag. The real integration breaks, but the demo (on the mock path) stays green, so nobody notices until production.

Every if (DEMO_MODE) is a fork where reality and appearance can drift apart. The more important the surface, the more dangerous that drift.

The rule: real services, always

BANNED:  if (IS_MOCK) return fakeData()
         if (DEMO_MODE) skipRealCall()

REQUIRED: every path → real Supabase, real Stripe (test mode),
                       real backend, real LLM calls

The demo account is the best example. It's not a mock — it's a real account with real Supabase auth, real Stripe (in test mode), real credits, real virtual keys, and real LLM calls. When we walk through the demo, every guardrail, budget, and CRUD path is the actual code path a paying customer runs. (See the no-server-side-key playground — even the interactive tester uses a real virtual key.)

"Test mode" is not "fake mode"

There's an important distinction we do honor: Stripe test mode. Using Stripe's test environment isn't a mock — it's Stripe's real API, real webhooks, real signature verification, exercised against test cards. The idempotent webhook handling and atomic credit grant run exactly as they do in production; only the money is play money. That's the line: use the real system in a safe mode, never a fake system pretending to be real.

Why this is a culture decision, not just a tech one

Banning mocks is really a stance on honesty. It says: we'd rather a demo be harder to set up than be a lie, and we'd rather find the broken integration ourselves than let a green mock hide it until a customer does. It forces the real path to always work, because there's no fallback that papers over it. That pressure — the real thing has to work, every time, for everyone including us — is exactly the pressure that produces a product you can trust.

It also keeps us honest in a second way: the same discipline shows up in cost (read the provider's real number, never compute a convenient one) and in data (real tenants, real RLS). "No mocks" is one expression of a broader rule — don't build a comfortable fiction next to the truth.

The takeaway

A mock flag is a fork where appearance and reality drift apart, and the drift always surfaces at the worst time. Banning IS_MOCK and DEMO_MODE — running every path, including demos, against real services (Stripe in test mode, not fake mode) — means the demo is an honest end-to-end test and a broken integration can't hide. It's less convenient and far more trustworthy, which is the trade we make on purpose.