When to use Zuplo (architecture decision)

Status: Accepted, 2026-10-23.
Decision: Food Truck Nerdz does not need Zuplo today. The gateway in this repo is parked until FTN offers a public or partner API.

Context

This repo holds a Zuplo API gateway (Places search, trucks and check-ins backed by Firestore, a legacy Google sign-in JWT check, and a Business Profile lookup) plus its Zudoku developer portal.

An audit of the current apps found:

  • Only ftn-site server actions and its client check-in store call the gateway.

  • ftn-app never calls it.

  • The gateway’s auth (legacy Google sign-in JWT) does not match the Better Auth sessions the apps now use.

  • The /api/trucks route returned HTTP 500 during the audit.

What already covers the gateway’s jobs

Need Covered by Notes

Hide third-party API keys

Next.js server routes and server actions on Vercel; Convex actions

Keys stay in Vercel or Convex environment variables and never reach the browser.

Rate limiting

Vercel Firewall rate-limit rules and @vercel/firewall; @convex-dev/rate-limiter

Limits can be set per route at the edge or per user inside Convex functions.

Authentication

Better Auth, integrated with Convex through ctx.auth

One identity across web and mobile; a gateway with its own JWT scheme would duplicate it.

Vercel has no general-purpose API gateway. Its AI Gateway only routes requests to LLM providers, so it is not a replacement for Zuplo, and it is not needed for this either.

Decision

  1. Do not put Zuplo in front of the apps' own traffic.

  2. Never proxy Convex calls through Zuplo. Clients talk to Convex directly; Convex handles auth, validation and rate limits itself.

  3. Move Places search into a Convex action, and move trucks and check-ins from Firestore into Convex.

  4. After that, retire or park the gateway. Keep this repo and its portal as a starting point for a future public API.

When Zuplo becomes the right tool

Revisit this decision when FTN offers an API to outside developers or partners and needs any of these:

  • Issued API keys for third parties, with self-serve key management.

  • Per-consumer quotas and rate limits.

  • Monetization (metered or tiered API plans).

  • A public developer portal (Zuplo’s Zudoku-based Dev Portal).

In that setup, Zuplo would front a small, versioned public surface (for example read-only truck and schedule data) and forward to Convex HTTP actions or Next.js routes. The first-party apps would still call Convex directly.

Related