AI-native design editor. Open-source Figma alternative.
Cloud
Optional, self-hostable backend; the design is in packages/docs/development/cloud.md. The editor must keep opening, editing, and saving local documents without this package or a network.
Boundaries
- Consumers import the
contract,client,email,server, andruntime/nodesubpaths; browser code imports onlycontractandclient, which stay on the browser baseline (tests/app/shell/support/baseline.test.ts,compat/compatinoxlint.json). src/serverreceives its database, object store, auth adapter, and delivery through injection and never importspg, opens listeners, runs migrations, or starts timers; runtimes undersrc/runtime/own those (src/runtime/node/server.ts).- The package is published to npm; a directory imported as
#cloud/<dir>is listed inimportsinpackage.json, since the wildcard there names.tsfiles (bun run check:packages). @better-auth/coreis pinned to thebetter-authversion though nothing imports it:@better-auth/passkeyaccepts any later core, whose exact@better-fetch/fetchdiffers from its own, and npm then never finishes installing the package (bun run test:packages).- Errors no route handled, and failures of work a runtime owns, go through
reportCloudErrorwith the injectedCloudErrorReporter; only runtimes create one, from the optional[error_tracking]table, so a deployment without it sends nothing (src/runtime/posthog/errors.ts,tests/server/errors/handler.test.ts). - Runtime code runs on Node 22 and Bun alike: serve HTTP through
@hono/node-server, notBun.serveor otherBun.*APIs (tsdown.standalone.config.tstargetsnode22).
Data and security
- Sign-ins are recorded by the
accountActivityBetter Auth plugin from the hook context'snewSession, never by parsing tokens from responses (src/server/auth/activity.ts). - Code inside Better Auth's own callbacks must not query the database, which deadlocks its transaction on one connection (
tests/integration/server/account/routes.test.ts). - Name a table for what it holds, without a
cloud_prefix; only a name Better Auth already uses gets a qualifier, such asapi_rate_limit(src/server/db/migrations/025_table_names.ts). - Renaming a table that shipped migrations query gives them a type under the name they ran with, so their SQL stays the same (
LegacyAuthSchemaDatabaseinsrc/server/db/migrations/helpers.ts). user.imageonly ever holds an address this server serves; a picture from anywhere else is copied intouser_pictureor dropped, never linked, and a provider's picture comes from the ID token on its account row, never from the endpoint that wrote it (src/server/pictures/provider.ts,tests/integration/server/pictures/provider.test.ts).- Name a Better Auth endpoint by the object that declares it: a plugin's from the plugin the factory builds, a core one from
auth.api; only the core paths options need before Better Auth is built are written out, inCORE_AUTH_PATHS, where the type check holds them to the library's own. Match hook paths withisAuthEndpoint, and put endpoints clients must not reach indisabledPaths(src/server/auth/factory.ts,src/server/auth/endpoints.ts). - A route with a rate budget of its own mounts
createRouteRateLimiter, orcreateResourceRateLimiterfor a budget per resource, whose policy also caps the actor across resources; general limiters skip what either counts throughrouteHasOwnBudget, so never exempt routes by matching their paths (tests/integration/server/rate-limit/budgets.test.ts). - Database rows use
crypto.randomUUID(); secrets that leave the server userandomHexfrom@open-pencil/scene-graph/random, are stored as SHA-256 digests (a single-use OAuth continuation keeps a JWE copy), and travel in URL fragments (src/server/sharing/capabilities/service.ts). - An admin list takes
search,filter,limit, andoffsetthroughlistQueryand answers with its rows,total, and per-filtercounts; it declares its filters once asListFilters, which count in one query and page with the same condition (src/admin/list.ts,tests/integration/admin/lists.test.ts). - Every HTTP body goes through
validatedJSONwith a contract schema, and every response the client reads is parsed with Valibot (src/server/validation.ts,src/client/api.ts). - Every route parameter goes through a
validatedParamsvalidator such asdocumentParams, and handlers read it fromcontext.req.valid('param'); a malformed UUID then answers 404 instead of reaching a query (open-pencil/no-unvalidated-route-params,tests/integration/server/api/uuid-parameters.test.ts). - A revision's images live in
revision_image; code that makes a revision from another copies them withcopyRevisionImages, and a storage object aworkspace_imageholds is never unreferenced (src/server/documents/images.ts,tests/integration/server/documents/images.test.ts). - Add schema changes as a new numbered migration in
src/server/db/migrations/registered insrc/server/db/migrate.ts; never edit a migration that has shipped. Better Auth's tables have their own versioned migration (016_auth_schema.ts). - Raw SQL lives only in migrations and the reviewed helpers in
src/server/db/expressions.ts; everything else uses typed Kysely queries (open-pencil/no-cloud-raw-sql). - Cloud code keeps secrets out of query strings and logs, and the server never builds an HTML response from values (
open-pencil/no-secret-in-query,open-pencil/no-secret-logging,open-pencil/no-dynamic-html).
Collaboration relay
- The relay hub in
src/server/collaboration/relay/is runtime-neutral: runtimes hand it sockets throughRelaySocketand own listening (src/runtime/node/relay.ts). It joins every room as theserverpeer, so it must keep answeringsync-step1and saving the room document. - Viewers may send only the channels in
VIEWER_ACTIONS; every other channel from them is dropped, and presence is stamped from the ticket bystampAwareness(tests/server/collaboration/relay/hub.test.ts). - Decoders must consume exactly the frame's bytes and copy payloads out, since socket buffers are pooled (
src/contract/relay.ts,tests/contract/relay.test.ts). - Send frames through
relayServerMessagesandrelayClientMessages, which split anything pastRELAY_FRAGMENT_BYTESinto fragments, and read sockets through the matching assemblers; never send an encoded frame whole (tests/server/collaboration/relay/hub.test.ts).
AI relay
- The reference AI service in
src/ai-relay/is runtime-neutral likesrc/server; runtimes own listening and keys (src/runtime/node/ai-relay/server.ts). - It speaks only the contract in
src/contract/ai.ts(tests/contract/ai.test.ts). - It trusts nothing about a request beyond a token that verifies against Cloud's keys (
tests/integration/ai-relay/app.test.ts). - It forwards only the chat completion fields in
FORWARDED_FIELDS, so routing fields cannot reach models outside the catalog (tests/integration/ai-relay/app.test.ts). - The relay's tables are
ai_relay_*with their own migration history, so it can share Cloud's database (src/ai-relay/db/migrate.ts). - Neither the relay nor Cloud reads the other's tables (
src/ai-relay/db/schema.ts).
Portal
- The portal's pages live in the app (
cloud.html,src/views/cloud/,src/components/cloud-portal/); this package owns only their paths (src/contract/portal.ts) and serving them beside the editor (src/runtime/site/server.ts). Links the server sends to people point atpublicURL, its editor and portal alike (src/contract/links.ts,src/admin/enrollment/email.ts).
Configuration
- Deployment settings live in the schema-versioned TOML parsed by
src/server/config/deployment.ts; environment variables only resolve{ from_env }secret references and never override the file (tests/runtime/node/config.test.ts). - Technical limits are ceilings that policy can tighten but never raise (
src/server/config/limits.ts,src/server/policy/). - Feature and limit decisions go through the OpenFeature policy keys in
src/server/policy/keys.ts; never branch on a plan name.
Tests
- Unit tests mirror
srcundertests/{ai-relay,client,contract,email,runtime,server}; integration tests mirrorsrcundertests/integrationand run on PGlite throughtests/helpers/database.ts;tests/e2eholds Docker Compose runners thattestnever starts. - Tests import source through
#cloud/*and helpers through#cloud-tests/*, and read responses withresponseJSONfromtests/helpers/response.ts. bun run test:cloudtype-checks the package and runs unit and integration suites.