Edge functions

The server side is a set of Supabase edge functions (Deno) under packages/kit/supabase/functions, assembled into the site's supabase/functions beside the site's own (db/functions). _shared/ holds what they share: lib.ts (CORS, the clients), offers.ts (Stripe made to match the files), ledger.ts (what a payment writes) over ledger-rules.js (what it decides — who paid, which offer a line is, what it grants — plain objects in and out, so the most consequential decisions in the kit can be checked without a stack; Commerce internals), email.ts and emails/ (the compiled designs, fill.js, tags.js, rules.js, markdown), marketing.ts (the campaign sends and the tracked links), cal.ts (cal.com and the one judge), print.ts and printers/ (the printer modules), shipping.ts, payouts.ts (connecting an account and sending what is payable — the one place money moves outward), and roles.ts — what a person may do, asked as a capability. matrix/ is the Matrix surface: ids.js, events.js and state.js translate rows to Matrix and back as pure functions, errors.js holds every refusal in Matrix's shape with a reason a person can act on, keys.js is the key store an encrypted channel needs — device and cross-signing keys, one-time keys claimed exactly once, the to-device queue and the key backup, all of it public keys and opaque blobs and never a secret — and session.ts is the one place a client's token becomes that person's own database session — the only module in the kit that holds a refresh token, and the file to read before changing anything about that surface. atproto/ is the social network as an atproto server the same way: ids.js makes handles, DIDs and at:// URIs from a member's identity as it is now and says which methods may be asked at all (clientAllowed: other apps only where the config's network.apps allows them) (pure, read by the tests too), errors.js every refusal in XRPC's shape, media.js what a post may carry and how it goes over the protocol (plain JavaScript the browser and the tests read too), views.ts rows into the app view's shapes (a record assembled and its CID hashed, never stored), writes.ts a record from another app into a row through the person's own client, session.ts app passwords and the sessions made with them — again the one module of the surface that holds the auth server's refresh token — federation.ts a joined member's portable identity, their signed repository made from their public rows and the numbered event stream relays read, and appview.ts the world outside asked of an app view as that member, with a service token signed by their own key. A function never compares a role's name: it reads the set with rolesOf(userId) and asks isAdmin, isStaff, isCoach, isSupport, mayEditContent or maySeeFigures, which are the same words the database's own helpers and the browser's lib/auth.js use, so the three can never drift apart about what a role means.

Provider adapters use a generic Reddit User-Agent by default; REDDIT_USER_AGENT can override it. LINKEDIN_API_VERSION optionally pins the LinkedIn API version. The Bluesky OAuth client metadata is labeled Site Social Publisher.

_shared/compiled.ts is how a function reads anything the build compiled rather than wrote — the catalog, the forms, the funnels. It puts the row of public.compiled over the file the deploy shipped, so a deployment that cannot rebuild (cloud mode with git out of the cycle and no deploy hook) still answers from what was last published; where there is no row, which is everywhere that builds, it is the file exactly as before. One read per isolate, and fresh() re-reads within a few seconds for the functions that answer the public. A module holding a value from an artefact declares it export let and re-derives it in onRefresh, so no call site had to change shape.

Two things the functions read are written by the build from platformkit.config.js rather than from the database: _shared/cloud.json (where cloud mode publishes — the token stays a secret in app_settings) and _shared/webhooks.json (the subscriptions this deployment ships, naming the environment variable a secret is in and never the secret). The site's own scheduler also falls back to a session type's declared default hours where a host has set none.

The functions

The functions that take no JWT are listed in config.toml with verify_jwt = false; each trusts something else, named above.

create-checkout-session decides two things the page only displays: whether the shape is still in stock, and what this buyer pays. Both use the same pure modules the page used (_shared/stock.js, _shared/prices.js) over the same data, so the two cannot disagree — but the function is the door, and a tab open since this morning arrives there. A sold-out line is refused 409; a line a price list re-priced is charged inline rather than minting a second Stripe price. Guest session Checkout is a separate, opt-in exception: exactly one eligible paid-session line and its selected booking details are accepted, while mixed carts are refused. The ledger records a unique booking_checkout_fulfilments claim by Checkout Session before calling a scheduler, preventing webhook and confirmation replays from creating a second booking. A guest booking uses Stripe's server-returned email; matching booking and credit rows are claimed only after app-level email verification.

Coaching chat access is deliberately narrow: a provider can reply in their own coaching threads without a membership. A reader's session-only access is derived by chat_session_with from the paid booking and its coach, through one week after end_at; rescheduling updates that window and cancellation closes it. It is not a subscribed entitlement.

The admin function

In cloud mode the admin's backend is admin: one POST shaped as the dev server's middleware request — { seg, method, q, body } for collections, list, file (get · put · delete · rename), preview, options, action, upload, upload-image, asset, the library's media (over the content-assets bucket), and cloud mode's own drafts (what waits), publish ({ col, name } for one record, nothing for every draft, with a message) and keep (a draft removal called off) — answered by the same pipe (admin-pipe.mjs and build/models, assembled under _shared/pipe/ with the site's own models under pipe/site/ and the theme's string scopes as pipe/theme-strings.json) over the row store (build/store/rows.mjs: public.content and the content-assets bucket) with the service role — so every write goes through the pipe's checks and nothing is written from a client. The actions that need a machine (enrich, introduce, the print's render · save · set · quote · pdf, tts) answer 409 this runs from a checkout or the deploy. A coach who is not an editor is let in with a fence — only: { col: 'pages', field: 'owner', value: <their username> } — and the pipe then answers for the pages collection alone and for the records whose owner is their name, refusing every other record on every verb rather than hiding it (build/admin-fence.test.mjs). A file write is a draft and pushes nothing; after a successful publish the function pushes every pending row to the repository as one commit with the message given; github (op: get · put · retry) reads and writes Site → Publishing's settings in app_settings (github:repo, github:branch, github:token — service-role only, the token never sent back) and asks for a push; push-pending, called by run_content_push() every minute over pg_net with the service bearer, bundles whatever is still pending the same way.

_shared/github.js is the push, plain JavaScript on fetch alone so a kit test runs it under Node with the API mocked: commitFiles through GitHub's git data API — the branch's head, its tree, a blob per file, one tree over the head with a removed file's entry gone, one commit, the ref moved — and pushPending over every pending row: only once the ref has moved are the rows cleared of pending together (a removed one is gone for good) and github:last_push set; a failure anywhere leaves every row pending with the reason in push_error, github:error says so, and the next minute tries the lot again. A branch with no commit yet is refused with a line saying to push an initial commit first.

What a payment writes

ledger.ts is the one writer: purchases, subscriptions, entitlements (the classes and tiers the client reads through get_my_entitlements), a paid session's credit and its booking, a print order sent to the printer, the order's email. The webhook calls it with Stripe's objects; confirm-checkout with the session retrieved from Stripe; the mock (STRIPE_MOCK=1) with the same objects made up. Nothing on the client writes to any of those tables.

Secrets

Server-only settings are never VITE_-prefixed (those reach the browser bundle). In production they are function secrets (supabase secrets set, which the deploy does from its environment); locally they live in supabase/functions/.env, which platformkit dev generates from .env with the run's APP_URL so every link comes back to the port the app is on. The service-role key is injected by the platform.

The functions on the site's own domain

Every user-facing link to a function — a tracked click, the open pixel, unsubscribe — is written as https://<site>/v1/<function>/… when PUBLIC_FUNCTIONS_URL (the functions' side) and VITE_PUBLIC_FUNCTIONS_URL (the client's) are set, and the host rewrites /v1/* to the project's functions/v1/* — same origin, one short address. Without them the site's shell forwards /v1/… to the function before anything loads, so clicks and unsubscribes work either way; only the pixel is written against the function's own address.

Running them locally

platformkit dev serves them (supabase functions serve) against the local stack; platformkit functions serves them alone; platformkit functions deploy deploys them (the deploy does). The push function uses npm:web-push, which runs in the edge runtime the stack ships, not under an old local Deno CLI.

Adding a function to a site

A folder under db/functions/<name>/ with an index.ts; the assembler places it beside the kit's (a site function of a kit's name is refused), and it imports the kit's _shared by relative path as the kit's do. Its verify_jwt line goes in the site's config.toml.