The Same-Origin Engine Boundary

"A boundary only protects you if everything goes through it. One convenient shortcut around the engine and the guard is decorative."

One Origin, One Door

Pippa Go serves its built client and its API from a single engine on one origin. The phone loads the app from the engine and makes every request back to that same engine, which then talks to the canonical Pippa backend. That indirection isn't ceremony — the engine is where real work happens: remote/PIN guarding, staged-image validation, the success-only request cache, retry boundaries. Every request passing through one door is what makes those protections meaningful. A guard at a door nobody has to use is just decoration.

Why Browser-Direct Calls Break It

The tempting shortcut is to have the browser call the canonical upstream directly — it's fewer hops, it feels faster. But a browser-direct call bypasses the engine, and with it every guarantee the engine was enforcing:

Guarding skipped: the remote/PIN checks live in the engine. Go around it and requests reach upstream without them.
Validation skipped: staged-image validation happens at the engine. Bypass it and unvalidated payloads travel.
Boundaries skipped: retry and caching rules are enforced at the engine. A direct call plays by no rules at all.

This is why the rule is stated so bluntly: do not add browser-direct calls that bypass the engine's boundaries. Not because indirection is beautiful, but because a boundary with a hole in it isn't a boundary.

The Low-Bandwidth Dividend

The same-origin engine pays a second dividend that only shows up in the field. Serving the built client from the engine — rather than relying on a development server that fetches modules piecemeal — is what makes the app usable on a genuinely bad link. A dev server's many small requests die on a slow connection; a built client served from one origin arrives and works. This is a lesson learned the hard way somewhere with more mountains than bandwidth, and it's why the built client, not the dev server, is what you reach for when the signal is thin. Development convenience belongs to development; the field gets the build.

Code

Every request through one door — no side entrances·text

RIGHT: one origin, one boundary, all protections apply
  phone --> [ engine: PWA + API ]  --> canonical Pippa backend
              ^ remote/PIN guard
              ^ staged-image validation
              ^ retry + cache boundaries

WRONG: a browser-direct shortcut around the engine
  phone --------------------------> canonical Pippa backend
         (no guard, no validation, no retry boundary — all skipped)

// The engine only protects what passes through it.
// One side entrance and every guarantee above becomes optional.

Exercise

Draw the request paths for a client with an engine boundary. Now add one 'harmless' browser-direct call to the upstream — maybe for a fast read that seemed not worth proxying. List every protection that call silently skips. Then decide: is there any read so cheap that skipping the guard, the validation, and the retry boundary is worth it? Write the rule you'd give a future contributor in one sentence.

Hint

The bypass always starts with a request that 'doesn't need' protection — until requirements change and it does, or someone copies the pattern for a request that always did. The one-sentence rule is usually 'every upstream call goes through the engine, no exceptions,' precisely because exceptions multiply.