Architecture
A deep-dive into how this site is built.
1 · Executive summary
One Next.js app on Vercel and six outside services, run by one person: mistakes are made to fail the build rather than reach visitors.
1 · Executive summary
One Next.js app on Vercel and six outside services, run by one person: mistakes are made to fail the build rather than reach visitors.
Visitor
any browser
Vercel
CDN · functions · cron
Next.js 16 app
pages, API routes, server actions
Neon Postgres
catalogue, Instagram queue, analytics
Vercel Blob
images, films, private backups
Resend
enquiry and alert email
Anthropic API
Instagram caption drafts
Meta Graph API
Instagram publishing
GA4
traffic, alongside the site’s own analytics
A storefront for paintings and photographs: a filterable gallery, a page per work with print sizes and prices, a map of where each work was made, time-lapse films of the paintings being made, a gift-shop builder, and an admin Content Management System behind a password. Prints are ordered by enquiry: the order form emails the artist and the sale completes by email, so the site takes no payments and holds no card data.
It runs on fully managed infrastructure (Next.js on Vercel, Postgres on Neon, media on Vercel Blob, email through Resend) and is run by one person with no developer on call. The design leans accordingly: mistakes are made to fail the build rather than reach production, and scheduled jobs email when something goes wrong rather than waiting on a dashboard someone has to watch.


- Framework
- Next.js 16 · App Router
- Runtime
- React 19 · Node
- Data
- Prisma 7 · Neon Postgres
- Host
- Vercel · Crons · Blob
- Resend
- Styling
- Tailwind CSS v4
- Tests
- Vitest · fast-check · Playwright · axe · ZAP · Stryker
- Captions
- Claude API
2 · Operations
What runs by itself each week, and how the owner hears when something breaks.
2 · Operations
What runs by itself each week, and how the owner hears when something breaks.
Tests gate every deploy
Every pull request runs a dependency audit, the full unit suite, a production build and the Playwright suite against a throwaway Postgres. Every Sunday an active security scan attacks a CI build of the site. Vercel’s production build runs the unit suite again, so a failing test stops the deploy even if it slipped past review.
Four scheduled jobs
Vercel Crons: a health check every hour, a catalogue backup every six hours, a prune of old analytics events and expired rate-limit counters at 05:30 UTC, and Instagram publishing Mon/Wed/Fri at 15:00 UTC. Each route rejects any request without the CRON_SECRET bearer token.
Failures email the owner
Every hour the health check confirms the database answers and four real pages render on the live domain, and emails through Resend (lib/notify.ts) once when something breaks and once when it recovers, never on every run. After every production deploy a GitHub Action confirms the new commit is live and the key pages work, and opens an issue if not. Every uncaught server error (a page that fails to render, a route handler that throws) is counted in ErrorReport with its stack, emailed the first time and then once a day per kind (instrumentation.ts). So is one in a visitor’s browser (the gift-shop builder, the map, a click that throws), posted to /api/client-error; since anyone can post there, those emails are capped at ten a day. From outside Vercel, Better Stack checks the home page and /api/health every three minutes and emails if either stops answering, which catches what nothing on Vercel can: Vercel itself, the domain or the certificate going down. The Instagram job emails if its token is invalid, a publish fails, or a queued caption has gone stale; the backup job, if a snapshot can’t be written.
Two kinds of analytics
Google Analytics 4 on the production deployment only (CI’s browsers once counted as thousands of visitors), with advertising consent denied by default (no remarketing audiences, and no per-country Google domain the CSP could never list), plus a first-party tracker writing one row per event to Postgres (no raw IP stored), with its own dashboard. The owner’s browsers are excluded at ingest, not filtered afterwards.
3 · Runtime request path
How a page request travels from the browser through Vercel to the database, and what else it can touch.
3 · Runtime request path
How a page request travels from the browser through Vercel to the database, and what else it can touch.
Every page is a React Server Component rendered on request, reading through a single Prisma client. The catalogue pages say so (dynamic = "force-dynamic"); the prose pages (About, FAQ, this one) render per request anyway, because the root layout reads the request headers for the CSP nonce, and nothing below a layout that does so can be prerendered. Interactivity is confined to client-component islands (the gallery’s filter and sort, the size selector and order form, the map, the film player), and writes go through route handlers (public forms) or server actions (the admin).
Browser
Server-rendered HTML · client islands: gallery filter/sort, size selector + order form, Leaflet map, click-to-load film player · first-party analytics beacon
Next.js 16 on Vercel (Node runtime)
Proxy gives each page request a fresh CSP nonce · Server Components render every page per request · Route handlers /api/buy /api/contact /api/book /api/commissions /api/track /api/og-image /api/csp-report /api/version /api/health /api/cron/* · Server actions for the admin (session-checked)
Prisma 7 client (module singleton)
Adapter chosen by URL: PrismaNeonHttp for Neon (one HTTPS request per query, no connection pool to exhaust) or PrismaPg for a plain Postgres (CI and local E2E)
Neon Postgres (serverless)
Product · MakingOf · CommissionExample · InstagramPost · AnalyticsEvent · ExcludedVisitor · FormRateLimit · HealthState · CspViolation · ErrorReport · AdminPasskey
Alongside the database
Repository (/public)
catalogue images, served through the next/image optimiser
Vercel Blob
public: catalogue, films · private: uploads, collectors' photos, backups
Resend
order, contact and booking emails; failure alerts
Kit
newsletter sign-up, posted from the browser
OpenStreetMap tiles
the Locations map
Meta Graph API · Claude API
Instagram publishing · caption drafts
Every page renders per request, because the CSP nonce has to be fresh, but its catalogue reads come from Next’s data cache (lib/catalogue-cache.ts), not Neon. Each admin write expires the cache, so an edit is live on the next load; a script’s edit shows within the hour, or at once after Refresh site in the admin. Each deployment starts with an empty cache, since the data cache outlives a deploy: in October 2026 a new build served its predecessor’s image paths, which it had just deleted, until the cache was cleared by hand. Neon on the Free plan suspends after five idle minutes, and before the cache the first visitor after a quiet spell waited for it to wake; now Neon is asked only after a change. With the database stopped outright, a local production build still served every catalogue page from the cache in under 40 ms. Prerendering the prose pages was the alternative, and was rejected: a static page can’t carry a per-request nonce, so it would need a weaker policy for pages that do no database work anyway. Functions run in Vercel’s default region (Washington, D.C.), next to the database in AWS us-east-1.
4 · CI/CD & deployment topology
Branch, tests, merge, build, production, smoke test: nothing reaches the live site untested.
4 · CI/CD & deployment topology
Branch, tests, merge, build, production, smoke test: nothing reaches the live site untested.
All work lands through pull requests into main. GitHub Actions (.github/workflows/e2e.yml) runs on every pull request and every push to main; Vercel deploys main to production on merge.
Feature branch
local: unit tests, typecheck, E2E on a throwaway Postgres
GitHub Actions
Postgres 16 service → npm ci → audit-ci → lint → npm run build → seed → restore drill → Playwright + axe → ZAP scan (main only) · in parallel: Gitleaks, Semgrep
Merge to main
squash merge
Vercel build
prisma generate → vitest → test inventory → database check → prisma db push → image check → next build
Production
CDN + Node functions → Neon
Smoke test
new commit live? key pages, headers, sitemap
- One build script everywhere.
npm run buildisprisma generate && vitest run && (database check) && prisma db push && next build, in CI and on Vercel alike, so the unit suite gates production and not only pull requests. The tests run before the schema is pushed, so a change that fails them never reaches the production database. Between the tests and the build it writes the list of every test that/architecture/testsrenders; CI fails if the committed copy is stale. - Preview deployments are opt-in, and can’t reach production.
vercel.jsonbuilds a non-production branch only whenENABLE_PREVIEWS=1, and every preview sits behind Vercel Authentication. The risk is the database: the Neon integration hands previews the sameDATABASE_URLas production, so a preview would push its schema to, and its admin would write to, the live catalogue. The guard (lib/db-guard.ts) refuses a preview’s database unless it is a different Neon endpoint fromPRODUCTION_DATABASE_HOST, and a build step runs that check beforeprisma db push. With Neon’s preview branching on, each preview gets its own branch of production’s data. Instagram publishing is production-only. - Schema changes ship with the code.
prisma db pushruns on every build, after the unit tests, so the column exists before the code that reads it is served. There is no migrations directory: changes must be additive or nullable, and anything destructive needs a hand-written plan. - Every production deploy is checked after it lands. A failed Vercel build keeps serving the previous deployment, so every page still returns 200 and nothing looks wrong, which is how one broken deploy went unnoticed.
.github/workflows/smoke.ymlruns on Vercel’s deployment status: if the deploy failed it says so; if it succeeded,scripts/smoke.mjspolls/api/versionuntil the new commit is the one answering on the live domain, then checks nine pages render the storefront with their policy and headers, and the sitemap and robots file. Either failure opens a GitHub issue, since a run started by Vercel’s bot has nobody to email. Its first run found the photograph pages were being served with no Content-Security-Policy at all. - A red main opens an issue. Pull requests show their checks to whoever merges them; a failure on
mainshowed itself to nobody. The ZAP baseline runs onmainonly, and it failed every push from 15 October to 11 November 2026 while every pull request, deploy and smoke test stayed green..github/workflows/main-watch.ymlnow runs when the E2E, static analysis or performance workflow fails on a push tomain, and opens an issue, or comments on the one already open. - E2E cannot touch production. The Playwright suite creates, edits and deletes rows.
e2e/db-guard.tsrefuses to start unlessDATABASE_URLpoints at a local host (added after a local run once edited the live catalogue). - Nor can a laptop, by default. The Prisma singleton calls
lib/db-guard.tsbefore it connects: off Vercel, a remote database is refused unless its host is named inDATABASE_ALLOW_HOST. Local work uses a Neon dev branch named that way; running something against production means typing production’s host for that one command. “Off Vercel” isn’t read fromVERCEL=1alone, becausevercel env pullwrites that into the file it downloads: scripts ignore it, the build check also wants Vercel’sCI=1, and the dev server never counts as a deployment. - Mutation testing, scoped to the change.
mutation.yml(§8) runs on a pull request only for the critical modules it touches, and on all of them weekly. ZAP’s active scan (zap-full.yml, §10) is weekly only.
5 · Data model
The database tables behind the catalogue, the Instagram queue and the analytics.
5 · Data model
The database tables behind the catalogue, the Instagram queue and the analytics.
Product
a work: painting or photograph, its prices, images and visibility
ProductSlug
every URL a work has had; old ones redirect
MakingOf
the films; may arrive before their work
InstagramPost
the queue, captions and publish state
AnalyticsEvent
page views, some of them of a work
Admin
- AdminPasskey
Operations
- HealthState
- FormRateLimit
- ErrorReport
- CspViolation
Analytics
- ExcludedVisitor
Ten tables. Paintings and photographs share Product, distinguished by type. Other tables refer to a work by its id rather than a foreign key: a film can be published before its painting is in the catalogue and links itself up once the product exists, and analytics events outlive a deleted work.
Product
The catalogue, the site's source of truth
- id
- PK, permanent; Blob names, analytics and Instagram key on it
- slug
- the URL; null means the id is the URL. A rename moves it, never the id
- type
- "painting" | "photograph"
- title · category · description
- copy
- image · blurDataURL
- Blob URL · base64 placeholder
- mockupImage
- the "In a Room" mockup on Blob; cleared when the image is replaced
- sizeType · price
- keys into the size/price table in data/products.ts
- inspirationImage · Lat · Lng
- the source photo and where it was taken
- homePhoto · homePhotoCredit
- a collector's photo, stored stripped
- isNew · onSale · soldOut · visible
- merchandising flags
- sortOrder
- drag-to-reorder position
- naturalWidth · naturalHeight
- photographs: panorama detection
ProductSlug
Retired URLs, so a renamed work keeps its old links
- slug
- PK, an old /products/ or /photographs/ address
- productId
- the work it redirects to, permanently (308)
InstagramPost
A publishing queue with a state machine
- status
- pending → approved → posting → posted | skipped
- type · productId
- painting, photograph, reel, voting, press
- imageUrl · caption
- media and the approved text
- scheduledAt
- next free Mon/Wed/Fri slot, set on approval
- mediaFingerprint
- etag|content-length when the caption was written
- instagramId · postedAt
- set by the Graph API on publish
- containerId · postingStartedAt
- the attempt's media container, stored before publishing; the idempotency key
MakingOf
Time-lapse films of the paintings
- videoUrl · posterUrl
- Blob; too large to commit
- productId
- optional; links up when the work exists
- description · seconds
- caption and running time
- visible · sortOrder
- publishing and order
CommissionExample
Past commissions on /commissions; deliberately not a Product
- kind
- pet | portrait
- name · subject
- the subject's name and what they are; never the client
- medium · size
- free text for the caption
- image · blurDataURL
- private store, commissions/; metadata stripped, artist's copyright
- visible · sortOrder
- shown once the client agrees; admin order
AnalyticsEvent
One row per page view or action
- kind · action
- pageview | action (buy_open, product_click, …)
- path · productId · referrer
- what, and from where
- visitorId
- anonymous first-party cookie
- device · browser · os
- parsed server-side from the user agent
- country · city
- coarse, from Vercel edge headers; no IP
- indexes
- createdAt · kind+createdAt · action · productId · visitorId
ExcludedVisitor
Browsers not counted (the owner's)
- visitorId
- PK; the gba_vid cookie value
- label
- free text, e.g. "desktop Chrome"
FormRateLimit
Counters that stop the forms being a mail relay
- key
- PK; an HMAC of an IP or email address, never the raw value
- windowStart · count
- fixed window, reset in the same statement
HealthState
The health check's last result (one row)
- failing · changedAt
- so it emails on a change, and knows how long it lasted
- checkedAt · detail
- when it last ran, and its full report
CspViolation
Policy violations browsers report, aggregated
- directive · blocked · page
- what, from which origin, on which page
- count · firstSeen · lastSeen
- one row per kind; unseen for 30 days → pruned
ErrorReport
Uncaught errors, server and browser, one row per kind
- digest
- PK; Next's error digest, or a hash of the message
- message · path · kind
- what threw, where, and in a render, route, action or the browser
- stack
- the top of the stack from the first occurrence, capped at 2,000 characters
- count · alertedAt
- repeats are counted; the first is emailed at once, then once a day per kind
AdminPasskey
The admin's passkeys; once one exists, the password stops working
- id
- PK, the credential ID the authenticator presents
- publicKey · counter
- the public half only; the private key never leaves the device
- label · deviceType · backedUp
- which device, and whether it syncs (iCloud Keychain)
- lastUsedAt
- so a lost or unused device is easy to spot and remove
In code, not the database
Shared, versioned configuration
- data/siteConfig.ts
- brand, artist, domain, contacts, IDs
- data/products.ts
- SizeType union and the print price table
- data/giftShop.ts
- gift-shop products and image counts
- app/globals.css @theme
- brand colour tokens
6 · Key flows
Step by step: ordering a print, editing a work, publishing to Instagram, recording a visit.
6 · Key flows
Step by step: ordering a print, editing a work, publishing to Instagram, recording a visit.
pending
Claude drafts the caption
approved
scheduled
posting
container made, then published
posted
media id recorded
It goes back when
- approved → pendingits work was hidden, or the image changed since the caption was written
- posting → approvedthe container failed, or Meta confirms it never went live
- posting → postingMeta can’t say yet: the next run asks again
- pending → skippedyou skip it
Order a print, a card or a gift pack
The Buy Now form posts only ids and choices (which work, which size, framed or not, which images in a pack) to /api/buy. The server looks up the title and price itself (lib/order.ts) and refuses a hidden or sold-out work, a size the work isn’t sold in, or a pack with the wrong images, so no posted text can reach an email. It then sends the enquiry to the artist, with Reply-To set to the buyer, and a confirmation to the buyer. No payment is taken on the site. Contact, booking and the commission quote request (/api/contact, /api/book, /api/commissions) follow the same pattern. All four forms carry a hidden honeypot field; a submission that fills it gets a success response and sends nothing, so a bot learns nothing from being caught. Because that reply is identical, the page can’t tell a sent message from a caught bot, so the routes record the outcome themselves (lib/server-event.ts): “Contact form sent” and “Enquiry submitted” only once the artist’s email has gone, “Spam blocked” for the rest. When the page counted them, fourteen bots showed up as contact messages. Resend refuses an email by returning an error rather than throwing, so every route checks it (lib/form-send.ts). If the artist’s copy is refused, the visitor gets an error, not a confirmation for a message nobody received.
Add or edit a work (admin)
In the browser, the image is converted from HEIC if needed, downscaled to 2,400px JPEG and given a blur placeholder, which keeps uploads under the 4.5 MB server-action body limit. The server action checks the session, embeds the copyright notice in EXIF and XMP (pure JS; no exiftool in a serverless function), uploads to Blob under paintings/ or photographs/, and writes the row. The work is live on the next request.
Commissions: examples and quote requests
/commissions shows past commissions (pets and portraits), the terms and a quote request; nothing is priced, every commission is quoted. The examples are their own table, CommissionExample, not a kind of Product: the galleries, sitemap entries, Buy Now, the Instagram queue and the engagement ranking all read Product, and a commissioned portrait must never appear for sale because one of them forgot a filter. The admin adds, edits, hides and reorders them at /admin/commissions. Each image is re-encoded with sharp like a collector’s photo (the client’s own photo of their dog may carry their home’s GPS) and then stamped with the artist’s copyright, since the painting is the artist’s. An example names the subject, never the client. The quote request takes no uploads: the reply asks for photos, so nothing a stranger sends is stored.
Attach a collector’s photo
A photo of a work hanging in a buyer’s home replaces the generated room mockup on that work’s page. It is re-encoded with sharp, which drops all metadata (a phone photo taken at home carries that home’s GPS), and it fails closed: a file that can’t be read is refused, never published as-is. It gets no artist copyright, because it isn’t the artist’s photograph.
Delete a work or replace an image
Before deleting a Blob object, lib/blob-cleanup.ts counts references across products, Instagram posts and films; a file still in use elsewhere is kept.
Publish to Instagram
Captions are drafted by the Claude API into pending; approving one assigns the next free Mon/Wed/Fri slot. The cron checks the token, then puts the post back to pending if its work has since been hidden or deleted (so a work taken down never posts to a page that 404s), or if the file changed since the caption was written: it re-reads the media’s etag and length, because a repaint replaces the file behind an unchanged URL. Images outside Instagram’s 0.8–1.91 aspect range are letterboxed to a temporary Blob copy. Publishing is two Graph API calls (create a container, then publish it), with the row held in posting in between. The container’s id is stored on the row before publishing, and Meta publishes a container at most once, so it is the idempotency key: a publish that errors, or a row a previous run left behind, is settled by the container’s status (published is recorded, ready is published with the same container, expired goes back to the queue). Only when Meta can’t say does a row wait for a person. The sequence is pinned write by write (__tests__/instagram-publish-flow.test.ts): which post each step touches and what it sets, the order claim → container → publish → record, the retry waits on a fake clock, and who each alert reaches.
Record an analytics event
The tracker posts to /api/track, which drops the event if the host is localhost or a preview deployment, the user agent is a bot or headless browser, or the visitor is excluded. Otherwise it parses the user agent, takes coarse location from Vercel’s headers, sets an anonymous httpOnly gba_vid cookie and writes one row. A daily cron deletes events older than 25 months with a single deleteMany.
Sell out an edition
soldOut is distinct from visible: a sold-out work keeps its page and stays indexed, its JSON-LD availability becomes SoldOut, prices and the order form give way to an enquiry panel, and it moves to its own section at the end of the gallery and out of the gift shop.
7 · Media pipeline
How a photograph of a painting becomes the sized, fast-loading images visitors see, with its copyright notice.
7 · Media pipeline
How a photograph of a painting becomes the sized, fast-loading images visitors see, with its copyright notice.
Admin’s browser
resized to 2400 px; HEIC becomes JPEG
Server action
copyright notice stamped; collectors’ photos re-encoded without location
Private Blob store
kept as a /media/… path on the row
/media asks, on every request:
A visible work uses it
served to anyone; cached up to 10 min
The admin is signed in
served, never cached
Anything else
404, and the store isn’t even read
Image optimiser
resized per screen, cached for hours
Visitor
a picture sized for their device
- Two Blob stores, public and private. Admin uploads (a new work’s image, inspiration photos, collectors’ photos, commission examples) go to a private store and are held as
/media/…paths, served byapp/mediaonly while a visible work or commission example uses the file, or to the signed-in admin. A work uploaded hidden can’t be seen before it’s published, and hiding it, or removing a collector’s photo, stops the file being served instead of leaving it readable by anyone with the URL (within the caches: ten minutes at the CDN, a few hours in the image optimiser). The route serves only plain files in the upload folders, so the backups in the same store are out of its reach. Without the private store’s token, uploads go to the public store as before. - Blob is the catalogue’s one home. The original works used to be committed under
public/; in October 2026 a one-off script copied them to Blob undercatalogue/, repointed every row, and the 67 files left the repository. It replaced two homes and a manual commit step, and stopped git history growing with every revised image (it had reached about 250 MB for 44 MB of current images). A build step (scripts/assert-catalogue-on-blob.ts) stops the deploy if any row still names an old repository path, since a broken image fails nothing on its own. Nothing deletes acatalogue/file automatically: the pruner skips the folder, and an admin edit never releases one. Everything is served through thenext/imageoptimiser, resized per viewport. - Blur-up placeholders come from
data/blurs.tsfor the seeded catalogue, or the per-productblurDataURLmade at upload. The generated file is stripped of metadata, and a unit test fails the build if metadata returns. It once took the placeholder file from 46 KB to 200 KB without anyone noticing. - Copyright metadata has two writers that agree: an exiftool script for committed files (EXIF, IPTC, XMP) and a pure-JS writer for uploads (EXIF, XMP). Both change metadata only, never pixel data; the notice itself is defined once, in
lib/copyright.ts. - Films stay on Blob as MP4s with the index at the front (faststart), so playback begins before the file has fully arrived. The page renders a still poster; no
<video>element exists until the visitor presses play, so no film data is downloaded unless asked for. - Share images come from
/api/og-image, which composes a card with sharp from a work that is currently visible. A hard-coded image could name a work that has since been hidden. - Old URLs from the previous Squarespace site (
/home/p/<slug>) redirect permanently to works still for sale. The rest answer 410 Gone, so search engines drop them, rather than landing somewhere misleading; one that matches a work that is only hidden stays a 404, since it may come back.
8 · Tests & build guards
1,012 unit and 161 browser tests, plus guards that turn whole classes of mistake into build failures.
8 · Tests & build guards
1,012 unit and 161 browser tests, plus guards that turn whole classes of mistake into build failures.
- 1012 unit and component testsVitestevery build and pull request
- 161 end-to-end tests, with axePlaywrightevery pull request
- Static checksTypeScript, ESLint, audit-ci, Gitleaks, Semgrepevery pull request
- Restore drilla snapshot restored and compared row by rowevery pull request
- 1,108 planted bugsStryker mutation testingpull requests touching guarded code; all, weekly
- Security scanOWASP ZAP, passive then activeevery merge; active weekly
- Smoke testthe live site after each deployevery production deploy
1012 unit and component tests (Vitest and Testing Library) and 161 Playwright tests (one of them opt-in), every one listed by name in the test inventory, which the production build writes itself. Beyond ordinary behaviour tests, a set of guards turn whole classes of mistake into build failures. Most exist because the mistake happened once.
| Guard | Fails the build when… |
|---|---|
| Brand colour | a brand-green hex literal appears under app/, components/ or lib/ instead of the @theme token. There were 186, in four different hover greens. |
| Site identity | the brand, domain, email, phone, Instagram handle or analytics id is typed into code instead of read from data/siteConfig.ts. |
| Admin form fields | a server action reads a checkbox its form never renders, or tests one against "off". A browser never sends "off"; both mistakes once shipped at the same time. |
| Collector photo privacy | the home-photo path stops re-encoding, or starts stamping the artist’s copyright on someone else’s photograph. |
| Placeholder metadata | image metadata reappears in the blur placeholders shipped in the bundle. |
| Accessibility | axe finds a WCAG 2.1 A/AA violation on any public page, the open mobile menu or the order form (every rule, colour contrast and colour-only links included). |
| Visual regression | the gallery, a painting, the photographs, the gift shop or the about page, on a desktop or a phone, looks different from its reference screenshot by more than 1% of its pixels (e2e/visual.spec.ts). The references are rendered on CI’s own runner by a workflow run on the branch, since a laptop’s fonts differ. |
| Performance budget | the gallery, a painting, the photographs, the gift shop or the about page, loaded by Lighthouse as a simulated phone (median of five runs), passes its limit for the performance score, when the main image appears, layout shift, main-thread blocking or JavaScript size (lighthouserc.json). The limits sit a margin past today’s numbers, so they catch a real slowdown, not noise. |
| Keyboard | the first Tab doesn’t reach a working skip link, the phone menu doesn’t say whether it is open or close on Escape, or the image viewer stops being a dialog that takes focus, keeps it and gives it back (e2e/keyboard.spec.ts). A person checks the rest with VoiceOver twice a year (RUNBOOK.md). |
| Content-Security-Policy | any public page, the signed-in admin or a playing film raises a policy violation (e2e/csp.spec.ts), or a page is served without a fresh nonce. |
| Security headers | any response is missing the frame, sniffing, referrer or permissions header. |
| Dependency audit | a production dependency has a high or critical security advisory (audit-ci, the first step in CI). Nothing is allowlisted in audit-ci.jsonc. |
| Lint | ESLint reports an error. It wasn’t in CI until two dependency upgrades that broke it outright passed every other check. |
| Post-deploy smoke test | after a production deploy, the deployed commit isn’t the one live on the domain, or a key page fails to render with its headers; a GitHub issue is opened. |
| Secret scan | Gitleaks finds a credential anywhere in the git history, not only the latest commit, since a secret deleted later is still in it. |
| Code scan | Semgrep finds an issue under its TypeScript, React, Next.js, OWASP Top 10 or secrets rules, in the source, the workflows or the Dependabot config. |
| Server actions | an exported server action runs for a caller with no session, or reaches the database before checking for one. |
| Security scan | OWASP ZAP’s baseline scan of the CI build raises a finding not triaged in .zap/rules.tsv, where each accepted one carries its reason. Decided by scripts/zap-gate.mjs from ZAP’s summary, not its exit code. |
| E2E database | DATABASE_URL is not local; the suite refuses to start. |
| E2E image requests | a spec takes test from @playwright/test instead of e2e/test.ts, whose fixture keeps each optimized-image request running after its page has left. Without it, one spec leaving the admin mid-load hung next start’s image optimizer and failed a later, unrelated spec for weeks. |
| Archive before delete | a destructive script’s archive would overwrite an earlier one; the write fails and nothing is deleted. |
Tests that pick their own inputs
An ordinary test checks the examples someone thought of. A property-based test (fast-check, __tests__/properties.test.ts) states a rule that must hold for every input, such as “a title always becomes a slug the admin accepts” or “an order’s price always comes from the catalogue, never from the request”, then tries hundreds of generated inputs: empty, very long, Unicode, malformed. When one breaks the rule, it is shrunk to the smallest input that still does. They cover the code that turns outside input into something the site acts on: URL slugs, image shapes and prices, the public forms’ limits, Buy Now orders and browser error reports.
The first runs found two bugs the examples had missed. A title longer than 60 characters, cut just after a word, became an id ending in a hyphen (a second work with the same title got a double one), a form the site’s own slug rule refuses; the hyphen is now trimmed after the cut. And the “from” price of a size type named valueOf or __proto__ threw instead of being 0, because the lookup reached JavaScript’s built-in object properties (the admin form’s list of size types kept it from happening in practice). An ordinary test now pins each case. Random inputs don’t suit mutation testing, which needs the same score every time it runs, so under Stryker the properties use a fixed seed. Fixed, they caught no planted bug the examples missed: the edges they reach only now and then (a slug of exactly 80 characters, a form field of exactly its limit) are now ordinary tests, with the exact wording of each refusal. That took URL slugs from 84% to 100% and form input from 80% to 95.5%, and both floors went up with them.
Testing the tests: mutation testing
A passing test proves only that the code does what the test checks. Mutation testing checks the checking: Stryker (stryker.config.mjs) plants one small bug at a time (a < becomes <=, a line is deleted, true becomes false) and reruns the unit tests. A mutant the tests notice is killed; one they don’t survives, and marks behaviour nothing pins. It covers only the modules where an unnoticed bug costs money, data or security: order pricing, availability, form input, rate limits, the database guard, the private media store, backups, Instagram publishing, the URL rules and the admin sign-in (passkeys and the session cookie), 1,108 mutants in all.
The real code
lib/form-input.ts: if (value.length > max) refuse
A mutant
if (value.length >= max) refuse
Killed
a test failed, so this bug would be caught
Survived
every test passed: nothing pins this line yet
| Module | Score | Floor |
|---|---|---|
| Backups | 100% | 98% |
| Session cookie | 100% | 98% |
| URL slugs | 100% | 97% |
| Order pricing | 99.4% | 97% |
| Instagram publishing | 98.8% | 96% |
| Form input limits | 95.5% | 93% |
| Sold-out rules | 95.3% | 93% |
| Passkey sign-in | 94.9% | 92% |
| /media route | 93.6% | 91% |
| Passkey rules | 93.1% | 91% |
| Private media store | 91.8% | 89% |
| Login lockout | 84.2% | 82% |
| Database guard | 77.7% | 76% |
| Old Squarespace URLs | 73.8% | 71% |
A full run reruns the tests once per mutant, about 50 minutes, so a pull request gets a scoped one (.github/workflows/mutation.yml): only the modules it changes, or whose tests it changes, are mutated, and each mutant meets only the tests that import that module (vitest related, so no list of test files goes stale). Most pull requests touch none and finish in a minute; one module takes a few. Each module has a floor just under its score, and a pull request that leaves a module it touched below its floor fails, which is how new logic arrives with tests that pin it and how a weakened test gets noticed. Floors only go up. Every module runs weekly as well, for what a pull request can’t show: a change to code a module merely imports. No run reuses an earlier one’s results: Stryker’s cache can’t see a test change here, and would go on crediting a test that had been deleted.
How the scores got here
The first full run (October 2026, about 50 minutes) killed 630 of the 902: 69.8%. By module, from strongest: availability 95%, the private media store 92%, URL slugs and rate limits 84%, form input 80%, the database guard 75%, order pricing 74%, the retired URL rules 74%, backups 58%, Instagram publishing 53% and the media route 53%. Most survivors in order pricing had one cause. The tests checked that a bad order was refused, never why, so deleting a check passed whenever a later check refused the same order for a different reason. The duplicate-image rule for gift packs was one: delete it and a repeated image was still refused, but as “unavailable”. The reason is what the buyer reads, so the tests now pin each refusal to its own, and order pricing scores 99% (one survivor, which changes nothing a buyer could see). That took the whole to 74.4%.
The media route was next, at 53%, and its gap was the one that mattered most. The test’s fake database returned a work whatever it was asked, so deleting visible: true from the route’s query, which would have served a hidden work’s image to anyone, passed every test. The fake now answers the query against a small catalogue, and the route scores 98%: it also refuses an empty select, as Prisma does, after the commission examples showed one passing unnoticed. Adding the admin sign-in showed it was barely unit-tested at all: the passkey ceremonies scored 2% and the session cookie 0%, because only the end-to-end suite exercised them and every unit test faked the session. Their refusals are pinned now (a stale or reused challenge, an unknown passkey, a failed verification, the cookie’s flags), at 95% and 100%. When a weekly run finds a module below its floor, it opens an issue, since nobody is watching a scheduled run.
The last two were the weakest. Backups scored 58%: the restore test gave rows only to the catalogue and the retired URLs, so restoring a snapshot could have silently skipped the films, the Instagram queue and the excluded browsers. Every table is restored and checked now, and backups score 100%. Instagram publishing scored 53%, with the same blind spot as the media route: its fake database accepted any write without looking at which post or what changed. Deleting the production-only guard, the claim that stops a post going out twice, or the requeue after a failure all passed, as did sending a reel through the image path and emailing from the wrong caller. A new test records every write in full, runs the retry waits on a fake clock and checks who each alert reaches and what it says; publishing scores 99%. The three survivors left are two log lines and a wait of zero.
The first attempt scored about 5%. That was the tooling, not the tests: Stryker’s Vitest runner doesn’t switch mutants on under Vitest 5, so every test ran against the original code and passed. Switching a mutant on by hand showed the tests did catch it. Stryker now runs Vitest as a plain command, one run per mutant: slower, but honest. A score that looks too bad to be true deserves the same suspicion as one that looks too good.
9 · Security & privacy
Defences in rings, from every response down to the data, and what none of them covers.
9 · Security & privacy
Defences in rings, from every response down to the data, and what none of them covers.
Every response
HTTPS only · security headers · a Content-Security-Policy with a fresh nonce · cron routes need a secret
The public site
prices set by the server · forms rate-limited per address, recipient and day · honeypots · no IP addresses stored
The admin
passkey sign-in, bound to this domain · at most five failed sign-ins per 15 minutes · an encrypted 8-hour session · every server action checks it
The data
only production may touch production’s database · uploads private, served by /media · backups in a private store · secrets only in Vercel
What this defends against: the public forms being used as a mail relay, someone taking over the admin, a collector’s home location leaking through a photograph’s metadata, a poisoned dependency or workflow action, and a script injected into the page. What it doesn’t: a compromised Vercel, GitHub or Neon account, which hold everything (the Vercel one also holds the passkey break-glass); and volumetric DDoS beyond what Vercel absorbs.
1Admin opens sign-in
the browser asks the server to start
2Server sends a challenge
one-time, short-lived, held in the encrypted session cookie
3Device signs it
Touch ID, Face ID or a security key unlocks the passkey
4Server verifies
against stored public keys; only this site's domain counts
58-hour session
an http-only, same-site, secure cookie
- Admin authentication is a passkey (WebAuthn,
lib/passkey.ts): Touch ID, Face ID or a security key, verified with@simplewebauthn/serveragainst a one-time challenge held in the encrypted session cookie, with user verification required. It can’t be phished, since it is bound to this domain, and the server holds only public keys. Once one passkey is registered the password stops working; the break-glass for losing every device isADMIN_PASSWORD_LOGIN=1in Vercel, which needs the owner’s Vercel account. A successful sign-in becomes an iron-session cookie: encrypted, httpOnly, SameSite=Lax, Secure in production, eight hours. Every server action that changes data checks that session before doing anything. - Login attempts are limited to five failures per fifteen minutes per client IP, counted in Postgres so the limit holds across every serverless instance (until September 2026 it was a Map in one instance’s memory). The key is an HMAC of the address. It fails open: the admin locked out of a broken site is the one who has to fix it.
- Errors don’t hide. A visitor who hits a failing page sees a branded “try again” rather than a stack trace, and the owner is emailed, once a day per kind of error, counted in between. Errors in the browser are reported too, but only from this site’s own scripts, at most five per page, ten per address in ten minutes, and ten emails a day in all.
- The analytics endpoint is rate-limited per address, like the forms, so a script can’t write unbounded rows or skew the dashboard; the limiter fails open so an outage never loses a real visitor’s event.
- Cron routes require the
CRON_SECRETbearer token and return 401 without it. - Public forms validate names and emails server-side, and all three carry a honeypot. The booking form also rejects a submission made faster than a person could type it, and the contact form one with no spaces in it. The site stores no payment details because it takes no payments.
- The forms can’t be used as a mail relay. Each one emails a confirmation to the address typed in, from the site’s own domain, so each is rate-limited in Postgres across every serverless instance: per client IP and form, per recipient address, and a daily total (
lib/form-rate-limit.ts). The confirmations repeat nothing the visitor typed (not even their name), and the stored keys are HMACs, never raw IP or email addresses. Over the IP limit, nothing is sent; over the others, the artist still gets the enquiry and only the confirmation is held back. - Analytics stores no IP address: location is the coarse country and city Vercel supplies, and visitors are counted by a random httpOnly cookie. Headless browsers and bots are dropped at ingest.
- Other people’s photographs are re-encoded to remove location metadata, credited as their owners asked, and removable from the edit form.
- Secrets live in Vercel environment variables. The repository carries only
.env.local.example, with placeholder values.
10 · Security testing & resilience
Automated attacks, scans and outside checks that keep the defences honest.
10 · Security testing & resilience
Automated attacks, scans and outside checks that keep the defences honest.
Mozilla HTTP Observatory
A+
130 / 100 · 12 of 12 tests passed
View the report from Mozilla HTTP Observatory (opens in a new tab)Qualys SSL Labs
A
TLS 1.2 and 1.3 · post-quantum key exchange (X25519MLKEM768)
View the report from Qualys SSL Labs (opens in a new tab)Email authentication
SPF · DKIM · DMARC
all published; DMARC at p=none (monitoring)
View the report from Email authentication (opens in a new tab)
| Risk | Unit | E2E | ZAP | Semgrep | Gitleaks | audit-ci | Mutation |
|---|---|---|---|---|---|---|---|
| Script injection (XSS) | not checked | checked | checked | checked | not checked | not checked | not checked |
| SQL or command injection | not checked | not checked | checked | checked | not checked | not checked | not checked |
| Someone taking over the admin | checked | checked | not checked | not checked | not checked | not checked | checked |
| Forms used as a mail relay | checked | checked | not checked | not checked | not checked | not checked | checked |
| A price changed in the browser | checked | not checked | not checked | not checked | not checked | not checked | checked |
| An unpublished work leaking | checked | not checked | not checked | not checked | not checked | not checked | checked |
| Missing security headers | checked | checked | checked | not checked | not checked | not checked | not checked |
| A post going out twice | checked | not checked | not checked | not checked | not checked | not checked | checked |
| A backup that won’t restore | checked | not checked | not checked | not checked | not checked | not checked | checked |
| A secret committed to git | not checked | not checked | not checked | not checked | checked | not checked | not checked |
| A vulnerable dependency | not checked | not checked | not checked | not checked | not checked | checked | not checked |
What is in place, and what is not, stated plainly, including the things that haven’t been done.
Automated security tests
These run in CI on every pull request:
- Admin login rejects a wrong password, and locks out after five failed attempts (
e2e/admin.spec.ts,e2e/zz-rate-limit.spec.ts). - Admin pages redirect to the login page without a session.
- The order endpoint refuses a size the work isn’t sold in and a work that doesn’t exist; every form sends nothing once over its limit; and no confirmation repeats a submitted name or title (
__tests__/form-email-abuse.test.ts). - The order and contact endpoints reject requests with missing fields, accept honeypot submissions without sending anything, and the contact endpoint rejects a message with no spaces (
e2e/api-validation.spec.ts). A caught bot gets the same reply as a person and is counted as spam, never as a message, and a refused email is an error, not a success (__tests__/form-email-abuse.test.ts). - Collectors’ photos are re-encoded, never published with their location data, and never stamped with the artist’s copyright (unit tests).
- The E2E suite refuses to run against a database that isn’t local.
- Every form posts, so one sent before JavaScript loads keeps the visitor’s email and message out of the URL, and out of analytics (
e2e/forms.spec.ts). - Every server action, called for real with no session, is sent to sign in before it touches the database; only the sign-in flows are exempt, and a new action is checked automatically (
__tests__/server-actions-auth.test.ts). - Script put into the search box, a category or a URL is shown as text, never run, on the server’s HTML and in the browser (
e2e/abuse.spec.ts). - The public forms refuse a body over 32 KB, a field over its length limit and a field that isn’t text, and send nothing (
lib/form-input.ts, tested by handler and on the running server). - Passkey sign-in refuses a stale, missing or reused challenge, a passkey this admin never registered, an answer that fails verification and any host but this site’s, and counts each failure toward the lockout; registering or removing a passkey needs a session; the session cookie is http-only, same-site, secure in production and lasts eight hours (
__tests__/passkey-actions.test.ts,__tests__/session.test.ts). /mediaserves an upload only while a visible work uses it: a hidden work’s image and collector photo, and a file no work uses, are 404s that never read the store (__tests__/media-route.test.ts).- Instagram publishing refuses on any deployment but production, claims a post before anything irreversible so it can’t go out twice, and returns a failed post to the queue only when nothing went live (
__tests__/instagram-publish-flow.test.ts). - Mutation testing (§8) checks that these tests would notice: on a pull request that touches the sign-in, the media route, Instagram publishing, backups or the other guarded modules, it plants bugs in them and fails if too many go unnoticed.
Every push to main
1E2E suite passes
the build under test is the real one
2ZAP baseline scan
a spider crawls 1,000+ URLs; passive checks on every response
3Gate
any untriaged finding fails the run and opens an issue
Every Sunday
1Throwaway build
its own database; production is never touched
2ZAP full and API scans
injection, scripting, traversal on every page and form endpoint
3Gate
findings fail the run and open an issue
By hand, 11 Nov 2026
1Mozilla Observatory
A+, 130/100, 12 of 12 tests
2SSL Labs
A: TLS 1.3, post-quantum key exchange, CAA
3Email records
SPF and DKIM pass; DMARC published
Automated scanning (DAST)
On every push to main, after the E2E suite passes, CI starts the same production build again and runs the OWASP ZAP baseline scan against it: a spider crawls the site (over a thousand URLs) and ZAP’s passive rules check every response: headers, cookies, the policy, caching, information leaks. It sends no attack payloads and never touches production. The ZAP image is pinned by digest, so a new release can’t fail an unrelated change (the version tag alone is rebuilt every week). Pull requests skip it to save Actions minutes, since passive findings come from headers and markup that rarely change. Any finding fails the job unless .zap/rules.tsv records it as triaged, with the reason; the report is attached to the run.
Why the gate reads ZAP’s report
The verdict comes from scripts/zap-gate.mjs, which reads the summary ZAP prints, rather than from ZAP’s exit code. A rule accepted for particular URLs only (an OUTOFSCOPE line, such as Next’s empty trailing-slash redirects) has those matches dropped, but zap-baseline.py still exits with a warning whenever the rule fired at all, listing it as “x 0”: no instances. Whether it fired depended on how far the one-minute spider got, and from 15 October 2026 it got far enough every time: main failed for four weeks on a finding with nothing in it. The gate keeps ZAP’s verdict and ignores only a rule listed with no instances; the weekly active scan uses it too.
Its first run found four things, and all four were fixed rather than accepted. The contact form, sent before JavaScript loaded, put the visitor’s email and message in the URL; every form now posts. Responses announced X-Powered-By: Next.js. And the cross-origin opener and resource policies were missing. What it still reports is accepted on the record: GA4’s script can’t carry a subresource-integrity hash because Google changes it, and Cross-Origin-Embedder-Policy would block the map and analytics for an isolation the site doesn’t need. The public forms carry no anti-CSRF token because they act for no one (there is no session for a forged request to ride), while the admin’s server actions reject a request from another origin, behind a SameSite cookie.
Active scanning
Once a week (.github/workflows/zap-full.yml), CI builds the site against a throwaway database and attacks it. ZAP’s full scan crawls the pages and sends attack payloads to every one it finds: SQL injection, cross-site scripting, path traversal, header and command injection. Its API scan does the same to the JSON endpoints behind the forms, which a crawler can’t discover because JavaScript calls them; they are described for it in .zap/public-api.yaml. The rate limits are emptied every few seconds for the scan, or the scanner, being one address, would only ever meet a 429. Nothing is emailed and production is never touched. Findings fail the run and open an issue, and are triaged in the same .zap/rules.tsv. One is accepted for the admin alone: signed out, its pages redirect to sign in with a body of about 15 KB, which ZAP flags as a redirect that might carry the page it protects. It carries only the public header and footer, which Next sends before the redirect, and an E2E test fails if a product title or analytics figure ever appears in it.
That is the automated half of a penetration test. The targeted half is the abuse tests above, which pin the particular ways this site takes input; writing them found that the public forms had no size limits at all. What neither does is think like an attacker about this site’s logic. An attacker-style review of the code did that in October 2026 (docs/security-review-2026-10.md): nothing critical or high in the code, sixteen medium and low findings fixed, among them an admin cookie that stayed valid for two weeks after logout, a race that could publish an Instagram post twice, and no daily limit on the emails the forms send. It also found the private file store for backups and unpublished images had never been connected; it was connected on 22 October, and on 11 November a one-off script moved what the public store still held into it (three collectors’ photos of their homes). A manual test by a person is still the next step. /.well-known/security.txt tells anyone who finds a problem where to report it.
Three outside checks look at what any visitor’s browser or mail server sees, and were last run by hand on 16 November 2026 (the grades are in the figure at the top of this section). Mozilla’s HTTP Observatory gives the headers A+, 130 out of 100, all 12 tests passed. Its three suggestions were each declined for a reason: inline styles stay allowed because React and next/image write style attributes (scripts stay locked to a nonce); HSTS isn’t preloaded because that would commit every subdomain to HTTPS for good; and there is no Cross-Origin-Embedder-Policy because it would block the locations map and analytics. SSL Labs gives the TLS set-up an A: TLS 1.2 and 1.3 only, forward secrecy throughout, and post-quantum key exchange (X25519MLKEM768). It isn’t an A+ because its own request to the site is answered 403, by Vercel’s bot protection, and that answer carries no HSTS header; a browser’s does (two years). It also finds no CAA record: the bare domain has none, so any certificate authority may issue for it. For email, SPF covers both senders (Squarespace’s forwarding on the domain, Resend on its send. subdomain), Resend signs with DKIM, and DMARC is published with reports going to two monitors. Its policy stays at p=none, monitoring only, by choice: the site is the only sender and its mail passes, and the record belongs to Squarespace’s email-forwarding preset, which can’t be edited without risking the forwarding.
Static analysis
TypeScript runs in strict mode with noUncheckedIndexedAccess: reading an item from a list or a lookup table is typed as possibly missing, because it can be, so the code has to say what happens then. Switching it on (October 2026) raised 147 errors. Most were tests reading back what they had just built, but three were real: a backup script given --file without a path crashed with an unhelpful error, a size guess returned nothing when a work offered no sizes, and a hashtag pick returned nothing for a category with an empty list of sets.
Beside TypeScript and ESLint, a second workflow (.github/workflows/static-analysis.yml) runs on every pull request, in parallel with the E2E suite. Gitleaks scans every commit in the history for credentials, with its output redacted; Semgrep scans the source against its TypeScript, React, Next.js, OWASP Top 10 and secrets rules. Either fails the run on any finding. CodeQL and GitHub’s own secret scanning would need GitHub Advanced Security on a private repository; these are free and need no account.
Their first run found nothing in the application code or anywhere in the git history. What Semgrep did find was in the supply chain, and both were fixed: the workflows referenced actions by version tag, which can be moved to point at other code, so every action is now pinned to a commit hash; and Dependabot now waits seven days before offering a new release, the usual window in which a hijacked package is caught and pulled. One folder is excluded: a design handoff kept for reference, which the site never serves or imports.
Dependencies
Dependabot opens grouped update PRs weekly for npm packages and monthly for GitHub Actions, after a seven-day cooldown, and GitHub raises security alerts with automatic fix PRs, which skip the cooldown; each one runs the full CI like any other change. Installs are reproducible (package-lock.json is committed and CI uses npm ci), and CI runs audit-ci on production dependencies, failing on any high or critical advisory.
Major upgrades are held when the toolchain isn’t ready, with the reason in dependabot.yml: TypeScript 7 and ESLint 10 both broke linting on arrival, and @types/node follows the Node version the site runs on (22), not the newest one.
Nothing is allowlisted in audit-ci.jsonc. Until November 2026 two advisories in the Prisma CLI’s build-time dependencies (deepmerge-ts, mysql2) were, each pinned to its path under prisma so the same advisory arriving through anything else still failed; Prisma 7.10.1 dropped both. Before October 2026 the whole audit was held at critical to make room for them.
Not done yet
| Area | Status |
|---|---|
| Manual penetration test | None by a third party. An active scan runs weekly and abuse tests run on every pull request (above); a person probing this site’s own logic has not. |
| Load testing to failure | The load test is capped at 50 visitors on purpose, and the site was comfortable there, so where it stops coping is still unmeasured. |
External uptime monitoring
The health check runs on Vercel, so it can’t see Vercel itself, the domain or the certificate fail. Better Stack (free plan) watches from outside, every three minutes, and emails on failure: one monitor on the home page, and one on /api/health, which answers 200 only when the database does. The second one exists because the free plan checks only that a URL responds, and during a database outage the site still responds, with its error page; the keyword check that would catch that is a paid feature. /api/health says nothing but {"ok":true}, caches a healthy answer at the edge for 30 seconds so it can’t be used to hammer the database, and never caches a failure. Certificate and domain-expiry warnings are paid too; an expired certificate still fails the check.
DDoS and traffic spikes
Vercel applies automatic DDoS mitigation and system-level traffic filtering to every request before it reaches the application, and Attack Mode can be switched on for the project during an attack. It challenges browsers while letting known good bots through. The repository defines no firewall rules of its own. Because pages render per request against a serverless database over HTTP, a spike turns into more function invocations and queries rather than exhausted connections.
Load testing
load/visitors.js is a k6 script that simulates visitors: each one loads the gallery, a painting, a photograph or the photo gallery, then the gift shop, map or films, pausing one to three seconds between pages the way a person does. It reads the works from the sitemap, so it follows the live catalogue. It makes read-only GET requests for pages alone (no forms, no admin, nothing written), and k6 runs no JavaScript, so analytics never sees it. It stops itself if more than 1% of requests fail or the 95th percentile passes three seconds, and it has no default target, so nobody runs it against production by accident.
Against production on 28 September 2026 it ramped to 50 simultaneous visitors over three and a half minutes, about 24 page renders a second at the peak, every one a function invocation with its Neon queries:
| Measure | Result |
|---|---|
| Pages served | 2,849, none failed |
| Median | 135 ms |
| 95th percentile | 194 ms (slowest page type: the films, 251 ms) |
| 99th percentile | 275 ms |
| Slowest request | 852 ms |
The one slow request (852 ms) was not Neon waking up: at 24 renders a second the database never idled. It fits a new function instance starting during the ramp. Neon cold starts are real for the first visitor after five idle minutes, which is what the catalogue cache now absorbs. Response times stayed flat as the load rose, which says the ceiling is well above 50. How far above was not tested: the run is capped deliberately, because it runs against the live site.
HTTP security headers
Every response (pages, API routes, the admin) carries X-Frame-Options: DENY (no other site may frame the pages), X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, and a Permissions-Policy that switches off the camera, microphone, geolocation, payment and other features the site never uses, and Cross-Origin-Opener-Policy and Cross-Origin-Resource-Policy set to same-origin, so no other site gets a handle on its windows or can embed its images. Nothing announces the framework. They are set once, in lib/security-headers.ts, and checked by a unit test and by an E2E test that reads real responses. Strict-Transport-Security comes from Vercel, with a two-year max-age.
Content-Security-Policy
Nonce-based and strict. proxy.ts gives every page request a fresh nonce; a script runs only if it carries it, or was loaded by one that did ('strict-dynamic'); no 'unsafe-inline' for scripts and no host allowlist. Next.js stamps the nonce on its own scripts, and the GA4 tags take it from the layout. Nonces need every page rendered per request, which this site already does, so they cost nothing extra here. Each outside service is named once: analytics, the newsletter, the map tiles and iframe, stored images and films.
Two deliberate allowances. Styles allow inline, because React renders style attributes that nonces can’t cover. And the admin alone may use blob: workers and eval, for the converter that turns iPhone photos into JPEGs; the public site gets neither.
It is enforcing, since 28 September 2026. It was sent as report-only first, so a wrong guess couldn’t break the site; a day of real traffic reported only two things, the Vercel toolbar’s comments frame (the owner’s own browser, now allowed) and GA4’s per-country audience ping (stopped at the source by consent mode). Violations are still reported to /api/csp-report and aggregated into CspViolation (directive, blocked origin, page, count), so that table is where to look when something on a page stops working. API responses, which need no nonce and skip the proxy, carry a fixed policy that allows nothing at all (default-src 'none'). An E2E test loads every page, the signed-in admin and a playing film and fails on any violation, which turns a new third-party host into a CI failure rather than a broken page.
11 · Build & runtime notes
Specific facts about the build and the servers, most of them learned the hard way.
11 · Build & runtime notes
Specific facts about the build and the servers, most of them learned the hard way.
- The proxy skips files by extension, not by folder. It once excluded the
photographsimage folder by name, which also matched the/photographspages, so they shipped without a policy, and the CSP test passed, because a page with no policy raises no violations. That test now also requires the policy on every page it loads. - No interactive transactions. The Neon HTTP adapter runs single statements, so anything that must be atomic is written as one: the counters are single upserts, the analytics prune is one
deleteMany, and reordering the catalogue is oneUPDATE … FROM (VALUES …). It was a loop of single updates, and a failure halfway left an order nobody chose. Neon’s WebSocket driver does offer transactions on serverless; nothing has needed one yet. - Node is pinned (
engines.node,.nvmrc) so CI and Vercel build on the same major; they weren’t guaranteed to before. - Connection URL lives in
prisma.config.ts(Prisma 7), which loads.env.localover.envthe way Next.js does, and never overrides a variable already set, so an exported localDATABASE_URLalways wins. - Server-action body limit is raised to 4.5 MB, matching Vercel’s function request limit; images are downscaled in the browser to fit.
- Identity and theme are data. Whose site this is lives in
data/siteConfig.tsand the brand colours in Tailwind@themetokens, which is what makes the repository a template: a second artist forks it and followsFORKING.md. - CI’s image optimizer is not production’s.
next start, which CI serves, hangs for good on an optimized-image request whose browser has already disconnected, and every later request for that image queues behind it. Six of them take all of Chrome’s connections to the host. For weeks this looked like a database stall in the admin tests, while Postgres had no connections at all. The E2E suite now fetches those images on the page’s behalf, so they always finish. On Vercel,/_next/imageis served by Vercel’s own optimizer. - Locally, the database is a Neon dev branch or a local Postgres, not production.
lib/db-guard.tsrefuses any remote host not named inDATABASE_ALLOW_HOST, so a stale.envfails loudly rather than writing to the live catalogue.
12 · Backups & durability
Four ways back from a mistake, from any second of the last six hours to a week of snapshots.
12 · Backups & durability
Four ways back from a mistake, from any second of the last six hours to a week of snapshots.
Point-in-time restore
Neon, the whole database, analytics included
any second of the last 6 hours
Snapshots
catalogue, films’ rows, Instagram queue, old URLs; private store
every 6 hours, kept a week; drilled
The artwork
images on Blob and in git history; films from their source files
always
Secrets
Production’s variables, encrypted with age, kept off Vercel
after any change; RUNBOOK.md for the rest
- A snapshot every six hours, in a private store. A cron writes a JSON snapshot of
Product, the films’ rows, the Instagram queue, the excluded browsers, the retired URL slugs and the commission examples (lib/backup.ts) to a private Blob store, which can’t be read without its token, keeps a week, and emails the owner if a write fails. Six hours because that is exactly Neon’s point-in-time window on the Free plan: past it, a snapshot is the only way back, and a daily one could lose most of a day. The snapshots hold hidden works, collectors’ credits and the source photos’ coordinates; until September 2026 they sat in the public store at a guessable name, then at an unguessable one.npm run db:exporttakes one by hand. - Restores are drilled, not assumed.
scripts/backup-drill.tsrestores a snapshot into an empty throwaway database and fails unless every table reads back identical, row for row. CI runs it on every pull request against the seeded database, so a change that breaks restoring can’t ship; against the newest production snapshot, into a Neon branch, it is a monthly task inRUNBOOK.md. The 44-work catalogue restores in under a second. A unit test restores every table from its own rows and checks each one (__tests__/backup-format.test.ts); until October 2026 it gave rows to only two, so a restore that skipped the other three would have passed. The restore code is mutation-tested at 100% (§8). - The artwork has more than one copy. The catalogue’s images are on Blob and in git history; films are uploaded from their local source files by
scripts/publish-films.ts. - Destructive scripts archive first and default to a dry run. The Blob pruner checks every product, film and Instagram post, and every Blob URL written in the repository, for references before deleting, and archives each file it removes. It covers every folder the admin writes to and names any folder it doesn’t, since nine unused files once built up unseen in two folders it skipped; the analytics purge writes the rows it will delete to a file named to the second, and refuses to overwrite an earlier one.
- Not in the snapshots: the films themselves, which are re-uploaded from their source files, and analytics, which is a record rather than an asset. Neon’s point-in-time restore covers the whole database, analytics included, for six hours (Free plan, capped at 1 GB of history; seven days on Launch, thirty on Scale). Snapshots and media are still all with one provider, Vercel, in two stores.
- Secrets have a copy off Vercel. Every credential lives in Vercel’s environment variables, so losing that account would mean going back to each provider.
npm run secrets:backuppulls Production’s variables and encrypts them withageunder a passphrase kept apart from the file. The plaintext exists only in a private temporary folder, and the script refuses to write inside the repository.RUNBOOK.mdis the one-page handover: every account, where each secret comes from, and what to do when something breaks.
13 · Decisions & trade-offs
The main choices, why they were made, and what each one costs.
13 · Decisions & trade-offs
The main choices, why they were made, and what each one costs.
| Decision | Why | Cost |
|---|---|---|
| Render per request, read the catalogue from a tagged cache | Fresh CSP nonce on every page; Neon is woken by changes, not by visitors | Every admin write must expire the tag; script edits wait for the hour or Refresh site; each deploy starts empty |
| Neon over HTTP | Serverless-friendly: no pool to exhaust, no connection storms | Single statements only; no interactive transactions |
| prisma db push, no migrations | Schema ships with the code in the same build | Additive changes only; destructive ones need a manual plan |
| Catalogue images on Blob only | One home for every image, whether seeded or uploaded through the admin | The deploy refuses to build while any row still names an old repo path |
| Previews opt-in, each on its own Neon branch | A shareable URL behind Vercel Authentication, never on production data | Three settings to turn on; a preview without its branch refuses to build |
| First-party analytics beside GA4 | Owns the data; excludes the owner at ingest | Another table to prune and a dashboard to maintain |
| Orders by email, not checkout | No payment data, no PCI scope, a personal sale | Every order is handled by hand |
| Functions and database in US-East | Vercel's default region sits beside Neon's; one round trip is the whole page | A Georgian Bay visitor is served from Virginia, ~20 ms further than Toronto |
| A nonce on every page | Strict CSP with no inline-script allowance | Even the prose pages render per request; nothing is prerendered, by choice |
| Errors go to email, not a vendor | One owner, one inbox; the same channel as the health check | No stack-trace browser, no release tracking, one email a day per error |
| Passkeys instead of the admin password | Phishing-proof, and Touch ID or Face ID makes it two factors in one step | Losing every device means the Vercel break-glass; register a second device |
14 · Repository map
Where everything lives in the code.
14 · Repository map
Where everything lives in the code.
app/
page.tsx · HomeClient.tsx gallery (server page + client filter/sort)
products/[id] photographs/[id] a work: sizes, order form, JSON-LD, room view
locations/ making-of/ map of where works were made · films
gift-shop/ calendar, card and postcard pack builders
about/ faq/ contact/ book/ static and form pages
commissions/ examples, terms and the quote request
for-artists/ architecture/ the pitch · this page (+ /tests, the inventory)
admin/ Content Management System, Instagram queue,
analytics dashboard, commission examples,
security (passkeys)
actions/ server actions: admin, passkey, instagram,
analytics, commissions
api/ buy · contact · book · commissions · track · og-image ·
csp-report · client-error · version ·
health · cron/*
home/p/[slug]/ legacy Squarespace URLs: redirect, or 410 Gone
media/[...path]/ private uploads, only for a visible work or the admin
sitemap.ts · robots.ts generated from siteConfig
proxy.ts per-request CSP nonce for every page
instrumentation.ts uncaught server errors → lib/error-report.ts
app/error.tsx · global-error.tsx what a visitor sees when a page throws
components/ Navigation, ProductCard, GalleryGrid,
BuyNowButton, MakingOfVideo, LocationMap, …
lib/
db.ts Prisma singleton; adapter by URL
db-guard.ts off Vercel, only a local or named database
private-blob.ts the private store: uploads as /media paths
backup.ts the snapshot: build, fingerprint, restore
catalogue-images.ts catalogue on Blob: paths, mockups, absolute URLs
product-path.ts · product-lookup.ts a work's URL (slug); old slugs redirect
csp.ts · csp-report.ts the policy · parsing violation reports
error-report.ts count errors, keep a stack; email first, then daily
client-error.ts check a browser's error report before it is recorded
passkey.ts the admin's passkeys: relying party, password rule
session.ts · rate-limit.ts admin session · login limiter
order.ts what an order is: server-side titles and prices
form-rate-limit.ts Postgres-backed limits for the public forms
form-input.ts size and type limits on what the forms accept
analytics.ts UA parsing, bot and host filters
engagement-rank.ts gallery order from visitor engagement
instagram.ts caption drafting, price ranges, scheduling
instagram-publish.ts two-step Graph API publish, reconciled by container
blob-cleanup.ts reference counting before delete
home-photo.ts re-encode collectors' photos (strips GPS)
commissions.ts commission kinds, terms, captions, field rules
image-copyright.ts stamp the artist's notice on uploads
availability.ts · json-ld.ts sold-out rules · structured data
data/ siteConfig, price table, seed catalogue, blurs
prisma/ schema.prisma · seed.ts
RUNBOOK.md one-page handover: accounts, secrets, incidents
scripts/ films, mockups, blurs, copyright, backups, backup-drill.ts,
secrets-backup.sh,
assert-catalogue-on-blob.ts,
Blob pruner, analytics purge, smoke.mjs,
test-inventory.mjs, zap-gate.mjs
__tests__/ Vitest unit, component and source-scan tests
e2e/ Playwright specs, shared fixture (test.ts), axe scans, db-guard
.github/workflows/e2e.yml audit-ci, lint, build, E2E on every PR; + ZAP scan on main
audit-ci.jsonc the audit's settings (high and above; no exceptions)
.github/workflows/static-analysis.yml Gitleaks (history) + Semgrep (source), every PR
data/test-inventory.json every test by name, written by the build
.github/workflows/smoke.yml post-deploy check of production, opens an issue on failure
.github/workflows/main-watch.yml opens an issue when CI fails on main
.github/workflows/zap-full.yml weekly active scan (pages + JSON endpoints)
.github/workflows/mutation.yml mutation test (Stryker): modules a PR touches; all, weekly
stryker.config.mjs the mutated modules and each one's score floor
.zap/rules.tsv ZAP findings triaged as accepted, with reasons
.zap/public-api.yaml the JSON endpoints, described for the API scan
.semgrepignore what Semgrep skips, and why
load/visitors.js k6 load test: simulated visitors, read-only
.github/dependabot.yml weekly npm and monthly Actions updates
vercel.json branch deploy rules · crons