Architecture · as of v9.27, 10-11-2026
Everything inside the solid box runs in your tab. Cut the dashed box off entirely and what’s left is still a complete image editor — that isn’t a fallback mode, it’s the free editor everyone gets.
Everything, including the parts that aren’t built yet.
React 19 · TypeScript · Vite · Tailwind v4
where the pixels are touched
IndexedDB · Dexie
Plus localStorage for lightweight prefs, and a sync layer over both: a BroadcastChannel keeps every tab on this device in step, and — only when signed in — Convex carries the same three documents to your other devices. Your photos are not in it. A precache-only service worker is written and tested and still ships dark: it is blocked on eviction reach, not on the precache (ADR-049).
Annotation rendering has repeatable benchmarks at 10, 100 and 500 annotations. An opt-in dirty-region prototype is compared with full-frame and tiled rendering, including pixel parity and memory costs. It is disabled in the production editor.
identity
settings across devices · entitlements · gallery
the server holds the provider key
ShareViewer · view counts, timestamps only
Three words, kept apart since v8.90: a tier is what an account paid for, a role is what a person is trusted to do, and an entitlement is what this session may use. The server decides all three.
Vite + React 19 · Vercel static SPA
Engine worker · zero-copy blit to an OffscreenCanvas
11 stores · atomic selectors · prefs persisted to IndexedDB
ImageBuffer · layer stack · composite / mask
Brush / eraser / mask · blur / pixelate / redact
Live text & shape overlays · magic-wand, edge-aware and lasso selection
Clone brush · flip / rotate / resize / crop
Brightness · contrast · saturation · shadows / highlights · sharpen · gaussian blur
Black / white / midtones · a preset is a stack of filters · Adjustments worked out from an untouched copy · one shared preview slot
Four-corner warp for shapes, text and pixels · homography solved in Rust
Arrows / shapes / bézier · 3 typefaces, registered at runtime, rasterized in Rust
Local image description — names a photo from its content, no account
PNG encode (Rust) · undo snapshots · op log at format v11
Op log · tile buffer · Magic Eraser fill
v128/f32x4 kernels · scalar fallback
identity provider
entitlement: none · anonymous · 12 photos
entitlement: free · 24 photos
entitlement: paid · pro or team tier · Stripe
a role, not a tier — entitled to paid, from ADMIN_EMAILS on the server
account row · me() with tier, role and entitlement
the one ladder: none → free → paid · a preview may only take away
save / getEdit
dispatch to Replicate · 3 models wired
job status (useQuery) · daily and monthly caps
public share links · pause, view cap, expiry
recent texts
settings across devices · compare-and-set on rev
saved color palette · 32 per user
checkout / portal · plan status
webhook router · Replicate + Stripe, HMAC-verified
Originals · SHA-256 content-addressed · your machine
Edit archives · shares · AI frames · a server
background removal
text extract
object removal (masked, LaMa)
4× upscale
soonsubscription changes → subscriptions
AI complete → status + guarded reference cleanup
Clerk sign-in isn’t a webhook here — the client calls users.upsert once Convex’s own auth bridge comes up, and that is what actually creates the users row. Who is an admin is read from ADMIN_EMAILS on the deployment — never from the browser.
Every table the app reads or writes, with its fields and indexes. Each row hangs straight off users, keyed by the editor’s own photoKey. Never a pixel: edited images stay in the browser that made them.
by_clerkIdby_email
by_userIdby_stripeCustomerIdby_stripeSubId
by_storageIdby_userId_photoKey
Real per-photo edit persistence path (useEditPersistence.ts)
by_userIdby_userId_usedAt
Text-tool history, per signed-in user
by_userId_key
Settings and remembered UI choices, the same on every signed-in device — never pixels
by_userIdby_userId_createdAt
The saved “+” palette — capped at 32 per user, newest first
by_storageIdby_tokenby_userId
Public, no-auth read — anyone with the link can view or download
by_shareId
Timestamp only — no IP, no user agent, no viewer id. One row per counted view, deleted with its share
by_inputStorageIdby_outputStorageIdby_maskStorageIdby_referenceStorageId1by_referenceStorageId2by_referenceStorageId3by_userIdby_userId_photoKeyby_replicateIdby_status
Keyed by photoKey, not a server-side image row — the Replicate webhook updates status
useQuery hooks update when data changes. No polling — it is what carries a setting from a phone to a laptop.
ctx.auth in mutations, plus query filters for user-scoped data. Entitlement is computed server-side from tier + role.
Blob storage for edit archives, share snapshots and AI frames via storage.getUrl().
Replicate and Stripe post back to convex/http.ts, HMAC-verified. A scheduled shares.expire stops a link at its end date.
Because the boundary is the product. An editor that needs a server is an editor that can be switched off, rate-limited, or quietly trained on. The dashed box buys you sync, sharing and the AI passes — and it is the only place a photo of yours can travel. Signed out, you never cross it.
The map above is drawn by hand from system-architecture.mermaid, the flowchart the repo ships. Render the original wherever you like.
flowchart TB · 121 lines · the dashed subgraph is the plane you can cut