Shipeasy is built around one rule: the read path is fast and the write path is explicit. Reading a flag, an experiment assignment, or a translation should never block your request. Changing one should be visible globally within a second of the dashboard click.

That single rule decides almost every architectural choice — no per-request fetches, no TTL-based invalidation, no streaming sockets. Just config blobs at the edge, polled in the background, and purged on change.

The two-runtime split

Admin app

The admin app is a Next.js app that owns:

• The dashboard UI for feature flags, configs, experiments, profiles and labels.
• Server Actions and Route Handlers — the same endpoints the CLI calls.
• Stateless JWT sessions (short expiry, no session table).
• The KV rebuild + CDN purge pipeline. Whenever you change a flag, the admin app rebuilds the affected blob and purges the URL.

Writes never go straight to KV from the dashboard. They go to the database first (the row of truth), then a rebuild helper reassembles the blob and writes it back, then an explicit purge invalidates the CDN.

Edge worker

The edge worker is a separate, read-mostly, stateless service. Two endpoint groups matter:

• /sdk/* — what your SDK polls. Returns the config blob unchanged. Cached at the edge with a long TTL; the admin's purge step is what makes the cache eventually-consistent.
• /collect — fire-and-forget event intake. Returns 202 immediately. Your code path doesn't wait on it.

The same worker also handles the CLI device-auth flow and runs the cron + queue analysis pipeline.

Shared state

The lifecycle of a write

When you flip a flag, six things happen — all within about a second. The write path fans out from the admin app; the read path and event ingestion live entirely on the edge worker; analysis closes the loop back to the database overnight.

The lifecycle of a read

The other direction is much shorter — and on purpose.

There is no per-evaluation network call, no rate limit on getFlag(), and no async surface to wrap. The cost of an evaluation is approximately the cost of a hash plus a few comparisons.

Two SDK builds, one package

@shipeasy/sdk ships server and browser builds in the same npm package, picked by your bundler via conditional exports (node → dist/server, browser → dist/client). Both share the same evaluation core, but differ in their environment assumptions:

For the native server SDKs (Go, Python, Ruby, Java, Kotlin, PHP, Swift) the evaluation model is identical — same blob, same deterministic bucketing. See the SDKs reference.

Plan-driven knobs

A handful of behaviours are plan-derived rather than per-project. The big one is the SDK poll interval:

Bumping a plan propagates through the next KV rebuild — no per-project migration. See Plan limits & quotas for the full matrix.

Identity model

A two-tier identity is enough for almost every use case:

import { configure, Client } from "@shipeasy/sdk/client";

configure({
  clientKey: process.env.NEXT_PUBLIC_SHIPEASY_CLIENT_KEY ?? "",
  attributes: (u) => ({
    user_id: u.id, // your stable user ID, set after login
    plan: u.plan,
    country: u.country,
    beta_tester: u.betaTester,
  }),
});

// Bind a client to the current user; getters take no user argument.
const flags = new Client(currentUser);

Shipeasy buckets by user_id ?? anonymous_id, so a user gets a stable assignment before and after login. The anonymous_id is auto-managed by the browser SDK (first-party cookie). When identify(...) runs after anonymous activity, the SDK emits an internal alias record so the daily analysis stitches the pre-login exposures to the post-login user_id — no explicit alias call required.

For B2B, you can bucket by company_id instead, so all teammates see the same variant. See Identity & bucketing for the full guide.

What we deliberately don't do

Where to next