Sketch-to-CAD Floorplan Generator

Sketch-to-CAD Floorplan Generator — Product Specification #

Overview #

Sketch-to-CAD Floorplan Generator is a desktop-first web app for estate agents. The agent uploads one hand-drawn JPG sketch of a property, with room labels and dimensions written on it. An AI vision model reads the sketch, a deterministic solver turns that reading into an editable plan, and the agent checks and corrects the plan in a browser editor. The app then draws a clean black-and-white floorplan with standard door and window symbols, kitchen and bathroom fixtures, room dimensions in metres and feet, a north arrow, the area under each floor, and an area summary at the top of the page. It exports the floorplan as PDF, PNG and JPG and emails all three to the agent, who forwards them to their client.

This document is the complete build specification. An AI coding agent or a development team can build the product from it without asking questions. Each concern has one owning section, and other sections refer to that section by number. Section 1 lists the few settings an operator may change before the build, each with a default that applies if nobody answers. Section 20 explains how the build should proceed.

Table of Contents #

1. Before You Start
2. Product Overview
3. Technology Stack & Architecture
4. Conventions & Configuration
5. Data Model & Storage
6. Authentication & Access Control
7. Properties & Sketch Upload
8. AI Sketch Reading Pipeline
9. Plan Geometry, Units & Areas
10. Review & Correction Editor
11. Plan Rendering & Drawing Standards
12. Export & Email Delivery
13. API Reference
14. User-Facing Copy
15. Security, Privacy & Compliance
16. Background Jobs, Reliability & Observability
17. Testing Strategy & Quality Gates
18. Deployment & Operations
19. Milestones & Execution Plan
20. Executor Instructions

1. Before You Start #

This section lists the few product and deployment choices that an operator may want to set before the build starts. Each question has a working default. If a question is not answered, its default is binding and the build goes ahead with it. Do not stop the build to wait for answers.

1.1 How to use this section #

1. Read the question table in Section 1.2. If the operator has given answers (in the task prompt, an issue or a message), use them. Otherwise use the defaults.
2. Write every answer and every default you rely on to DECISIONS.md at the repository root before you write any code. Use the entry format in Section 4.12. Mark each entry Source: operator or Source: default.
3. Apply each answer where the "Applied in" column says. Answers that map to environment variables go into .env.example as the example value, and also become the default in src/server/config.ts where the Section 4.9 table allows a default. Answers that map to code constants change only that constant.
4. An answer can never override the fixed constraints in Section 1.3. If an answer conflicts with them, keep the constraint, use the default, and record the conflict in DECISIONS.md.

1.2 Customization questions #

1.3 Fixed constraints that answers cannot change #

These rules are part of the product contract. No answer to Section 1.2 changes them:

1.4 What happens with the answers #

• .env.example is committed. It contains every variable from Section 4.9 with a safe local-development value, including the defaults above. It never contains a real secret.
• Each answer that changes a code constant changes only that constant. No feature may branch on the product name or the defaults.
• The first DECISIONS.md entries, D-001 to D-015, are always the fifteen answers or defaults from Section 1.2, in question order (D-001 = Q1 … D-015 = Q15).
• Values that are deployment facts rather than product choices (secrets, hostnames, the optional PRIVACY_NOTICE_URL) are set per environment (Section 4.9 and Section 18.6). They are not questions and get no DECISIONS.md entry.

2. Product Overview #

2.1 Vision #

Estate agents sketch floorplans by hand at a valuation or listing appointment: a pen drawing of each floor with room names and measurements. Having each sketch redrawn in CAD is slow and costly. The Sketch-to-CAD Floorplan Generator turns a photo of that sketch into a clean, professional black-and-white floorplan in minutes:

1. The agent uploads one JPG of the hand-drawn sketch for a property.
2. An AI vision model reads it: rooms and walls, room names, written dimensions, doors, windows, and kitchen and bathroom fixtures.
3. A deterministic solver turns that reading into an editable plan with real millimetre geometry.
4. The agent checks and corrects the plan in a browser editor, with the sketch shown beside it.
5. The app renders one black-and-white page with door and window symbols, fixtures, metric and imperial dimensions, a north arrow, per-floor areas and an area summary. It exports the page as PDF, PNG and JPG and emails all three to the agent.
6. The agent forwards the files to their client.

The AI saves the drawing work. The agent stays responsible for the result.

2.2 The user #

There is exactly one persona.

Job to be done: "When I come back from a viewing with a hand-drawn floorplan, I want a clean, accurate, professional plan with correct areas in a few minutes and without CAD skills, so that I can send it to my client the same day."

2.3 End-to-end user journey #

Each step lists what the user does, what the system does and which section owns the details.

2.4 What "done" looks like for a plan #

A plan is done when it has been exported and emailed. At that point all of the following are true:

1. The property has a PlanDocument with at least one part, and every part has at least one room.
2. Plan validation (Section 9) reports zero blocking errors. Warnings may remain, but the agent has seen them in the Issues list.
3. Each room has the correct name and type. The dimension lines match the sketch, or differ on purpose after the agent checked them.
4. Doors, windows, and kitchen and bathroom fixtures are where the sketch shows them.
5. The north arrow points where the agent set it.
6. An export for the current revision has status = rendered and email_status = sent. The PDF, PNG and JPG are downloadable in the app.
7. The page has the area summary at the top, each part's name and area under it, room labels in both units with the primary unit first, the north arrow and the disclaimer. It is pure black on white.

2.5 Scope summary: core features and owning sections #

2.6 Glossary #

Each term below has one meaning across the whole specification, the code and the UI. The code identifiers in the third column are binding.

2.7 Success measures #

All measures are computed server-side from database timestamps and stored records, or by automated tests. The browser has no analytics. Section 16 defines the operational queries, and Section 17 defines the test-time measurements.

2.8 Non-goals #

The following are out of scope. Do not build them, stub them, or leave UI hooks, database columns or API endpoints for them:

1. Payments, subscriptions, billing, plans, quotas for sale or invoices. The app is free.
2. Multi-user agency accounts, teams, roles, invitations, shared workspaces, or transferring properties between accounts.
3. DXF, DWG, SVG or any other editable or CAD export. Output is PDF, PNG and JPG only.
4. 3D models, virtual tours, elevations or sections.
5. Furniture layouts (beds, sofas, tables, chairs, wardrobes). Kitchen and bathroom fixtures and stairs are drawn. Furniture is not.
6. Publishing to property portals (Rightmove, Zoopla or others) and any portal-specific formats.
7. Reading typed, printed or CAD-generated plans. Uploads are treated as hand-drawn sketches.
8. Uploads other than JPG (no PNG, HEIC, PDF or TIFF), and more than one sketch per property.
9. Native mobile apps, and phone-optimised editing. The editor needs a desktop-sized screen.
10. Share links, client portals or any access for the agent's end clients.
11. Analytics, tracking pixels, third-party scripts, cookie banners for trackers, and marketing pages. The sign-in page is the only public page.
12. Password sign-in, social sign-in, SSO and two-factor authentication.
13. Real-time collaboration or merging edits from several tabs. A second tab gets revision_conflict (Section 10 owns how it is handled).
14. Logos, branding, watermarks or scale bars on plans.
15. Localisation. The UI is in UK English (en-GB) only.
16. An admin UI. The operator works with environment variables, the operations CLI and the runbook (Section 18).
17. A public API or API keys. The /api/v1 endpoints exist only for the app's own browser UI.

2.9 Product principles #

These principles settle design questions this specification does not answer directly. When two of them conflict, the one higher in the list wins.

1. Privacy by default. Files live in one private bucket and are only streamed to their signed-in owner after an ownership check. The app displays only the metadata-free AI copy of a sketch; the original is returned only by an explicit download. Deletion is a hard delete. Logs never contain personal content (Section 4.6). Nothing leaves the system except the model call (Section 8) and the email to the account's own address.
2. AI proposes, the human confirms. The AI result is a draft. Nothing is emailed until the user presses Finish & email. Uncertain items are flagged, never hidden. Anything the solver cannot place becomes a review flag or a warning instead of being silently dropped. Text written by the model is never shown to the user as a message.
3. What you see is what exports. The editor canvas, the Preview and the exported files are all drawn by the same pure rendering code (src/plan/render/). There is no second renderer.
4. One page per property. All parts are laid out on one page at one common scale, so their relative sizes are true. Paper size and orientation are the only page choices.
5. Areas are approximate and say so. Areas come from sketch dimensions. They are calculated exactly in mm² and rounded only for display. Every page carries the disclaimer.
6. Black and white, no decoration. Pure black (#000) on white (#FFF). No colour, no grey, no logos.
7. Deterministic after the AI. Given the same SketchReading and the same id generator, the solver always produces the same PlanDocument. Wall derivation, areas, validation and rendering are pure functions of the PlanDocument.
8. Rooms are the source of truth. Users edit rooms. Walls and areas follow.
9. Fail visibly and recoverably. Each failure has a stable error code (Section 13), a clear message (Section 14) and a recovery path: Try again, Start from a blank plan, Keep my previous plan, Re-export or Resend email.

3. Technology Stack & Architecture #

3.1 Dependency table #

This is the only place in this specification where versions appear. Other sections name dependencies without versions.

These version lines are a known-good floor, not a lockfile. At build time, install the current stable release of each dependency (npm install <pkg>@latest, or your ecosystem's equivalent), confirm the major line still matches, and let the lockfile record the exact resolved versions.

Packages whose version starts with 0. (pre-1.0) treat a minor bump as breaking. For these, keep the minor line shown and install with a tilde range (~0.45.0). They are marked "pin minor". Where a 0.x package shows no minor (esbuild), install the current release with a tilde range on its minor line and record that minor in DECISIONS.md.

Container images are never referenced by latest or without a tag. Node, PostgreSQL and Caddy use the official images' major-line tags from the tables below. Every other image (Mailpit, MinIO, the AWS CLI) uses a full release tag chosen at build time. The Playwright base image uses the exact lockfile version. All values live in docker/images.env (Section 18.2.1) and are recorded in DECISIONS.md.

3.1.1 Runtime platform and services #

3.1.2 Production npm dependencies #

3.1.3 Development dependencies #

Development dependencies are never imported by runtime code under src/. The lint boundary in Section 4.4 enforces this.

Note on TypeScript 6.x and 7.x. Both lines are installed, each for one job, and they never disagree about the code because both check the same tsconfig.json:

• TypeScript 7.x (the native compiler, installed under the alias typescript-native) is the type checker of record. npm run typecheck runs it, and it gates CI and the Docker build.
• TypeScript 6.x (the typescript package) is installed only because TypeScript 7.x does not ship the JavaScript compiler API that some tools load as a library: typescript-eslint's type-aware rules, and Next.js's build-time TypeScript setup check. It is never used to gate the build.

// package.json (devDependencies excerpt)
{
  "typescript": "^6",                      // TypeScript 6.x: library API for typescript-eslint and Next.js
  "typescript-native": "npm:typescript@^7" // TypeScript 7.x: the type checker of record
}

// package.json (scripts excerpt)
{
  "typecheck": "node node_modules/typescript-native/bin/tsc -p tsconfig.json --noEmit && node node_modules/typescript-native/bin/tsc -p tsconfig.plan.json --noEmit"
}

In next.config.ts set typescript: { ignoreBuildErrors: true }, because npm run typecheck (TypeScript 7.x) runs before next build in CI and in the Docker build. This avoids a second, slower type check. At build time, check whether typescript-eslint and Next.js have added TypeScript 7.x library support. If both have, drop the 6.x line, make typescript the 7.x line, remove the alias, and record the change in DECISIONS.md.

Note on ESLint 9.x. eslint-config-next 16.x depends on eslint-plugin-react and eslint-plugin-jsx-a11y, and their peer ranges end at ESLint 9.x. Use ESLint 9.x until both list ESLint 10.x in their peer ranges. When they do, move to 10.x and record it in DECISIONS.md.

Packages that are deliberately absent. There is no uuid package (ids come from uuidv7() in src/plan/ids.ts), no @aws-sdk/lib-storage (uploads are buffered and stored with one PutObject), and no server-only package (it throws outside the React Server Components build, which would break the worker, scripts and tests; the lint boundary in Section 4.4 keeps browser code out of src/server/** instead).

Adding dependencies. Any package not listed in Section 3.1 needs a DECISIONS.md entry that names the package, its purpose and its licence, and explains why existing dependencies are not enough. Licences must be MIT, ISC, BSD-2/3-Clause, Apache-2.0 or SIL OFL 1.1. Packages that send telemetry, load remote code, or add browser-side third-party requests are forbidden. Next.js telemetry is turned off with NEXT_TELEMETRY_DISABLED=1 in every image (Section 4.9).

3.2 Component diagram #

 ┌──────────────────────────────────────────────┐
 │ Desktop browser (Chrome / Edge / Firefox /   │
 │ Safari, latest 2 versions)                   │
 │                                              │
 │  React UI (src/components, src/app pages)    │
 │  Editor (src/editor) ── React SVG canvas     │
 │  src/plan (same code as server): schema,     │
 │  geometry, areas, validation, render         │
 └───────────────┬──────────────────────────────┘
                 │ HTTPS: HTML pages + JSON /api/v1/*  (cookie `sid`)
                 │ file downloads and images streamed through /api/v1/*
                 ▼
 ┌──────────────────────────────────────────────┐
 │ Caddy reverse proxy (production; TLS,        │
 │ replaces X-Forwarded-For, strips `token`     │
 │ from its access log)                         │
 └───────────────┬──────────────────────────────┘
                 ▼
 ┌──────────────────────────────────────────────┐        SMTP (magic links, via after())
 │ web — Next.js server (node .next/standalone) │──────────────────────────────┐
 │  src/proxy.ts: request id, security headers  │                              │
 │  pages (server-rendered)                     │                              │
 │  Route Handlers /api/v1 (withApi wrapper)    │                              │
 │  auth, CSRF, validation, rate limits/quotas  │                              │
 │  upload admission + checks (sharp)           │                              │
 │  file streaming, on-the-fly previews         │                              │
 │  pg-boss send-only (in the same DB tx)       │                              │
 └──────┬───────────────────────┬───────────────┘                              │
        │ SQL (pg)              │ S3 API (PutObject / GetObject stream)        │
        ▼                       ▼                                              ▼
 ┌──────────────────┐   ┌────────────────────────┐                 ┌───────────────────┐
 │ PostgreSQL 18    │   │ S3-compatible bucket   │                 │ SMTP server       │
 │  app tables      │   │ (private, one bucket)  │                 │ (any provider;    │
 │  schema pgboss   │   │ sketches/… exports/…   │                 │  Mailpit locally) │
 │                  │   │ thumbnails/… erasures/…│                 │                   │
 └──────┬───────────┘   └───────────┬────────────┘                 └─────────▲─────────┘
        │ SQL (pg) + job fetch      │ S3 API                                 │
        ▼                           ▼                                        │ SMTP (plan emails,
 ┌───────────────────────────────────────────────────────────────┐           │  fallback magic links)
 │ worker — Node.js process (node dist/worker.mjs)               │───────────┘
 │  pg-boss: sketch.read · plan.export · email.send ·            │
 │           maintenance.purge (03:00 UTC) ·                     │
 │           maintenance.cleanup (every 5 min) · *.dlq handlers  │
 │  sharp preprocessing · solver (src/plan/solver)               │
 │  export: renderPageSvg → HTML → Playwright Chromium           │
 │          → PDF / PNG / JPG + thumbnail                        │
 │  heartbeat file /tmp/worker-heartbeat (no HTTP server)        │
 └───────┬─────────────────────────────────┬─────────────────────┘
         │ HTTPS                           │ in-process (CDP)
         ▼                                 ▼
 ┌──────────────────────┐        ┌────────────────────────────┐
 │ Anthropic Messages   │        │ Headless Chromium          │
 │ API (vision model,   │        │ (Playwright) page.pdf()    │
 │ forced tool call)    │        │ page.screenshot()          │
 └──────────────────────┘        └────────────────────────────┘

 One-shot steps on deploy (worker image): node dist/migrate.mjs (Drizzle migrations, then the
 pg-boss schema and queues) · node dist/storage-init.mjs (bucket check). Operator commands:
 node dist/ops.mjs <command> (Section 18.11).

There is no Redis, no CDN, no public bucket and no presigned URL. The browser only ever talks to the web process (through Caddy in production).

3.3 Process responsibilities #

Why the first magic-link send happens in web. Sending from after() keeps the plaintext token only in the web process's memory for the duration of one request, and responding before the send makes the response time the same for allowed and not-allowed emails. The worker fallback never receives a plaintext token: its job payload carries only tokenId, and it mints a new token whose plaintext exists only in the worker's memory while it sends.

3.4 Repository layout #

There is one npm package and one repository. There are no workspaces and no monorepo tooling. The @/* path alias maps to ./src/*. This tree is canonical: every other section uses these paths. File names inside a folder that this tree does not list are owned by the section that specifies that code (for example Section 9.1.1 for src/plan/geometry/). A new file goes into the folder that owns its concern; no new top-level folder is added under src/ without a DECISIONS.md entry.

/
├── .env.example                  # every variable from Section 4.9, with safe local values
├── .env.test                     # committed, non-secret test configuration (Section 17.3.1)
├── .gitignore                    # node_modules, .next, dist, .env, .env.*, !.env.example, !.env.test,
│                                 # test-results, playwright-report, coverage
├── .prettierrc.json              # Section 4.3
├── .prettierignore               # drizzle/, .next/, dist/, coverage/, playwright-report/, test-results/, *.woff2
├── .github/workflows/            # ci.yml, images.yml (Section 17.15)
├── eslint.config.mjs             # Section 4.3
├── eslint.boundaries.mjs         # Section 4.4
├── tsconfig.json                 # Section 4.2 (whole project)
├── tsconfig.plan.json            # Section 4.2 (src/plan only, no DOM or Node types)
├── next.config.ts                # Section 3.4.3
├── postcss.config.mjs            # { plugins: { '@tailwindcss/postcss': {} } }
├── drizzle.config.ts             # schema: ./src/server/db/schema/index.ts, out: ./drizzle, dialect: postgresql
├── vitest.config.ts              # Section 17.2.4
├── playwright.config.ts          # Section 17.8
├── docker-compose.yml            # local stack (Section 18.3)
├── docker-compose.e2e.yml        # E2E overrides (Section 17.8.1)
├── docker-compose.prod.yml       # staging and production stack (Section 18.4)
├── package.json
├── package-lock.json
├── README.md                     # how to run locally, test and deploy (Section 18)
├── CHANGELOG.md                  # release entries with quality-gate evidence (Section 17.16)
├── DECISIONS.md                  # decision log (Section 4.12)
├── docs/                         # ai-eval.md and other operator-facing notes (Section 17.12)
├── docker/
│   ├── images.env                # pinned base-image tags (Section 18.2.1)
│   ├── web.Dockerfile            # Section 18.2.3
│   ├── worker.Dockerfile         # Section 18.2.4 (also runs migrate, storage-init and ops)
│   ├── test.Dockerfile           # Section 18.2.5
│   ├── caddy/Caddyfile           # Section 18.5
│   └── postgres/init/01-test-db.sql
├── drizzle/                      # generated SQL migrations + meta/ (never edited after merge)
├── dist/                         # esbuild output (git-ignored, Section 3.4.2)
├── public/                       # static files served as-is (favicon only; never user data)
├── scripts/
│   ├── build-worker.mjs          # esbuild bundles of the five Node entrypoints (Section 18.2.2)
│   ├── migrate.ts                # → dist/migrate.mjs: Drizzle migrations, then pg-boss schema and queues
│   ├── storage-init.ts           # → dist/storage-init.mjs: bucket check/creation (Section 18.3)
│   ├── worker-healthcheck.ts     # → dist/worker-healthcheck.mjs: heartbeat-file check (Section 16.7.3)
│   ├── seed-dev.ts               # npm run db:seed (Section 5.9)
│   ├── gen-font-metrics.ts       # npm run gen:font-metrics (Section 11.14.3)
│   ├── render-sample.ts          # npm run render:sample (Section 19)
│   ├── check-env-example.ts      # npm run check:env-example (Section 17.15.2)
│   ├── check-migrations.ts       # part of npm run db:check (Section 17.15.2)
│   ├── docker/sync-playwright-version.mjs   # postinstall (Section 18.2.1)
│   ├── visual/run-in-docker.mjs  # npm run test:visual (Section 17.9.3)
│   └── eval/ golden/ readings/ perf/        # evaluation and fixture tooling (Section 17.2.2)
├── fixtures/                     # sketches/ (golden set), readings/, plans/, uploads/, units/, e2e/ (Section 17.2.2)
├── tests/                        # unit/, integration/, e2e/, visual/, setup/, factories/, helpers/ (Section 17.2.2)
└── src/
    ├── instrumentation.ts        # Next.js boot hook: validates web config (Section 4.9.2)
    ├── proxy.ts                  # Next.js 16 request proxy: X-Request-Id, cookie-presence redirects,
    │                             # CSP nonce and security headers (Sections 4.7, 6, 15.4)
    ├── assets/
    │   └── fonts/inter/          # Inter-Regular.woff2, Inter-SemiBold.woff2, Inter-Bold.woff2, OFL.txt
    ├── app/                      # Next.js App Router (server components only; no 'use client' here)
    │   ├── layout.tsx            # <html lang="en-GB">, Inter via next/font/local, providers, skip link
    │   ├── globals.css           # Tailwind import, base styles, focus ring, reduced-motion rules,
    │   │                         # .plan-svg text { font-family: var(--font-inter) } (Section 3.8)
    │   ├── page.tsx              # "/" → /properties if signed in, else /sign-in
    │   ├── not-found.tsx
    │   ├── error.tsx             # 'use client' (Next.js requires it; exempt from the no-'use client' rule)
    │   ├── global-error.tsx      # 'use client' (same exemption)
    │   ├── (signed-out)/
    │   │   ├── sign-in/page.tsx
    │   │   └── auth/verify/page.tsx
    │   ├── (signed-in)/
    │   │   ├── layout.tsx                            # requirePageSession(); signed out → 307 /sign-in?next=<path>
    │   │   ├── properties/page.tsx                   # dashboard (Section 7.3)
    │   │   ├── properties/new/page.tsx               # create + upload (Section 7.4)
    │   │   ├── properties/[propertyId]/page.tsx      # property page (Section 7.1.1)
    │   │   ├── properties/[propertyId]/reading/page.tsx
    │   │   ├── properties/[propertyId]/edit/page.tsx # editor (Section 10)
    │   │   └── settings/page.tsx                     # Section 6.12
    │   └── api/
    │       ├── health/route.ts                       # GET /api/health (Section 16.8)
    │       ├── ready/route.ts                        # GET /api/ready
    │       └── v1/                                   # one route.ts per path in Section 13.12
    │           ├── auth/{request-link,verify,sign-out,sign-out-all}/route.ts
    │           ├── me/route.ts
    │           ├── properties/route.ts
    │           ├── properties/[propertyId]/route.ts
    │           ├── properties/[propertyId]/sketch/route.ts            # POST upload, GET original download
    │           ├── properties/[propertyId]/sketch/preview/route.ts
    │           ├── properties/[propertyId]/sketch/discard/route.ts
    │           ├── properties/[propertyId]/readings/route.ts
    │           ├── properties/[propertyId]/readings/latest/route.ts
    │           ├── properties/[propertyId]/plan/route.ts              # GET, PUT
    │           ├── properties/[propertyId]/plan/blank/route.ts
    │           ├── properties/[propertyId]/exports/route.ts           # POST create, GET list
    │           ├── properties/[propertyId]/thumbnail/route.ts
    │           ├── exports/[exportId]/route.ts
    │           ├── exports/[exportId]/files/[format]/route.ts
    │           └── exports/[exportId]/resend-email/route.ts
    ├── components/               # client and shared React components (PascalCase .tsx)
    │   ├── ui/                   # Button, TextField, Dialog, Toast, Spinner, FileDrop …
    │   ├── layout/               # AppHeader, PageShell, SkipLink
    │   ├── auth/                 # SignInForm, VerifyForm
    │   ├── properties/           # PropertyList, PropertyCard, StatusBadge, PropertyHeader, dialogs (Section 7.1.2)
    │   ├── upload/               # SketchDropZone, clientChecks, useSketchUpload (Section 7.5)
    │   ├── reading/              # ReadingProgress, ReadingFailed, useLatestReading (Sections 7.6–7.7)
    │   ├── exports/              # ExportsList, export status content (Section 12.9)
    │   ├── settings/             # AccountSettings, DeleteAccountDialog
    │   └── system/               # ErrorBoundary, OfflineBanner, SmallScreenNotice
    ├── editor/                   # the review & correction editor (Section 10.27 places files in these folders)
    │   ├── EditorRoot.tsx
    │   ├── store/                # Zustand store, actions, selectors, UI preferences
    │   ├── canvas/               # Canvas.tsx, viewport.ts, SvgNodeView.tsx, hit testing, layers
    │   ├── panels/               # top bar, part tabs, tool palette, properties panel, Issues panel,
    │   │                         # sketch reference view, dialogs
    │   ├── tools/                # select, room rectangle, room polygon, opening, fixture, label, pan; shortcuts
    │   ├── autosave/             # debounced plan PUT, revision handling, local backup, unload guard
    │   ├── history/              # undo/redo (100 steps)
    │   └── preview/              # PreviewPage.tsx (full page via renderPageSvg)
    ├── plan/                     # PURE, ISOMORPHIC domain core (Section 4.4): no DOM, no Node, no I/O
    │   ├── index.ts              # public barrel: re-exports the stable API of the subfolders
    │   ├── env.d.ts              # declares globalThis.crypto.getRandomValues only (Section 4.2)
    │   ├── ids.ts                # uuidv7(): string — the ONLY id helper (Web Crypto getRandomValues)
    │   ├── defaults.ts           # ROOM_TYPE_DEFAULTS, DEFAULT_PAGE, DEFAULT_DISPLAY_UNIT, DEFAULT_WALL_SETTINGS,
    │   │                         # fixture default sizes, createBlankPlanDocument(ctx, newId) (Section 5.10)
    │   ├── schema/               # planDocument.ts (PlanDocumentSchema, PLAN_LIMITS), parse.ts (parsePlanDocument),
    │   │                         # reviewFlags.ts (ReviewFlagsSchema, pruneReviewFlags), sketchReading.ts (Section 8)
    │   ├── geometry/             # polygon, segments, clipper, polylabel, walls, openings, areas, edit, snap (Section 9.1.1)
    │   ├── units/                # formatLength.ts, formatArea.ts, parseDimension.ts (Section 9.1.1)
    │   ├── validation/           # validatePlan.ts, rules/index.ts (RULES) + rule-group files, autofix.ts,
    │   │                         # strings.ts (Section 9.1.1)
    │   ├── layout/               # pageLayout.ts: computePageLayout — part arrangement, common scale, zones (Section 11)
    │   ├── render/               # renderPage.ts (renderPageSvg), renderPart.ts (renderPartSvgElements),
    │   │                         # svgNode.ts (SvgNode, serializeSvg, escaping), style.ts, symbols/, labels.ts,
    │   │                         # pageFurniture.ts, text.ts, fontMetrics.generated.ts, disclaimer.ts (Section 11)
    │   └── solver/               # solveReading, its steps, reading normalisation, review-flag generation (Section 8.11–8.12)
    ├── client/                   # browser-only helpers
    │   ├── apiClient.ts          # api(), ApiError (Section 4.5.4)
    │   ├── planBackups.ts        # localStorage plan-backup keys and clearPlanBackups() (Sections 10.20.7, 15.11)
    │   └── queryKeys.ts          # TanStack Query keys
    ├── lib/                      # tiny isomorphic helpers that are not plan domain
    │   ├── api/dto.ts            # zod DTO schemas shared by server and client (Section 13.3)
    │   ├── copy/                 # en.ts → COPY (key → text, exactly Section 14); t.ts → t(key, params?)
    │   │                         # (fills {name} placeholders; throws in tests on a missing key or placeholder)
    │   ├── env.ts                # IS_DEV — the only browser-safe environment flag (Section 4.4.2)
    │   ├── product.ts            # PRODUCT_NAME
    │   └── time.ts               # DISPLAY_TIME_ZONE, formatDateTime, formatDate, formatCalendarDate (Section 4.8)
    ├── server/                   # Node-only code (never imported by browser code — Section 4.4)
    │   ├── config.ts             # env schemas, loadConfig(role), getWebConfig() (Section 4.9)
    │   ├── clock.ts              # now(): Date — single app-side time source, frozen in tests
    │   ├── retention.ts          # deletesOn() — the one "Deletes on" helper (Section 5.13.3)
    │   ├── log/                  # logger.ts (pino), context.ts (AsyncLocalStorage), maskEmail.ts
    │   ├── http/                 # withApi.ts, securityHeaders.ts, streamFile.ts, afterResponse.ts
    │   │                         # (runAfterResponse) (web-only, Section 4.4);
    │   │                         # errors.ts (AppError, ERROR_CODES, ERROR_HTTP_STATUS; shared with the worker)
    │   ├── db/                   # client.ts (pg Pool + Drizzle), schema/index.ts + per-table files (Section 5),
    │   │                         # queries/*.ts
    │   ├── auth/                 # email, accessPolicy, tokens, magicLink, sessions, requireSession, csrf,
    │   │                         # clientIp, redirectPath (Section 6.1)
    │   ├── storage/              # objectStore.ts (S3 adapter), keys.ts (object key builders, Section 5.12)
    │   ├── jobs/                 # boss.ts, names.ts, payloads.ts (zod), sendJob.ts (Section 16)
    │   ├── ai/                   # SketchReader.ts (interface + createSketchReader), AnthropicSketchReader.ts,
    │   │                         # FakeSketchReader.ts, prompt.ts, toolSchema.ts, preprocess.ts (Section 8)
    │   ├── email/                # transport, magic-link and plan email builders and templates (Sections 6, 12)
    │   ├── export/               # export HTML host, Playwright browser pool, rasterising, embeddedFonts.ts,
    │   │                         # slug.ts (Section 12)
    │   ├── ratelimit/            # limit specs and consume() (Section 15.7)
    │   ├── ops/                  # cli.ts → dist/ops.mjs (Section 18.11)
    │   └── services/             # use-case functions called by route handlers, jobs and ops:
    │                             # properties.ts, sketches.ts, readings.ts, plans.ts, exports.ts,
    │                             # accounts.ts (deleteAccount)
    └── worker/
        ├── index.ts              # worker entry: loadConfig('worker'), logger, pg-boss start, handlers, heartbeat
        ├── heartbeat.ts          # writes /tmp/worker-heartbeat every 30 s (Section 16.7.3)
        └── handlers/             # sketchRead.ts, planExport.ts, emailSend.ts, maintenancePurge.ts,
                                  # maintenanceCleanup.ts, deadLetter.ts (Section 16)

Fonts in the web app. src/app/layout.tsx loads the three Inter files with next/font/local (weight 400, 600 and 700, variable: '--font-inter', display: 'swap') and applies font-family: var(--font-inter) to the UI. next/font generates a scoped family name, so globals.css also maps renderer output to it with .plan-svg text { font-family: var(--font-inter); }. Every element that displays renderer output (editor canvas, Preview) carries the class plan-svg. A CSS property outranks the font-family="Inter" presentation attribute that the renderer writes for export, where the embedded @font-face rules are named Inter. Both paths use the same three files, so text metrics match.

Canonical module paths. Every section uses exactly these paths and names.

src/plan cannot import src/lib, so the validation, review-flag, edit-reject and auto-fix texts live in src/plan (RULES, the flag templates, EDIT_REJECT_MESSAGES, AUTO_FIX_LABELS); src/lib/copy/en.ts imports them under their validation.*, reviewFlag.*, editReject.* and autofix.* keys, and copy-coverage.test.ts asserts each equals Section 14's text.

3.4.1 Layering rules #

Route handlers stay thin. They parse input with zod, call one function in src/server/services/, and return the envelope. Database access goes only through src/server/db/queries/ and src/server/services/. Because the worker and the ops CLI never import next/* or the web-only modules, their esbuild bundles never contain Next.js. Shared server modules therefore work on the standard Request/Response objects: for example, session cookie helpers read the Cookie request header and build Set-Cookie values themselves, and only requireSession.ts uses next/headers (for server components).

3.4.2 npm scripts #

This is the complete list of general scripts. Test and CI scripts are listed in Section 17.2.3, which is canonical for them. Scripts marked "dev" run TypeScript through tsx; production containers run only node on built output.

3.4.3 next.config.ts #

import type { NextConfig } from 'next';

const config: NextConfig = {
  output: 'standalone',
  poweredByHeader: false,
  reactStrictMode: true,
  typescript: { ignoreBuildErrors: true }, // TypeScript 7.x `npm run typecheck` is the gate (Section 3.1.3)
  serverExternalPackages: ['pino', 'pg', 'pg-boss', 'sharp', 'nodemailer'],
  // The sketch upload route is excluded from the src/proxy.ts matcher (Section 7.5.3), so the proxy's
  // request-body buffering never applies to it; the route handler enforces MAX_UPLOAD_BYTES itself.
};

export default config;

All pages are dynamic, because every page depends on the session. The root layout exports export const dynamic = 'force-dynamic';, so next build never prerenders a page and never needs runtime configuration.

3.5 Data flow: upload and reading #

1. Browser: the user drops a JPG on the upload area — on the new-property page, on a draft property's page, from Replace sketch… on a ready property, or from Upload a different sketch on a reading_failed property. The browser checks the extension, the MIME type (image/jpeg) and the size (≤ MAX_UPLOAD_BYTES) before sending, and compares the file's SHA-256 with the property's current and plan-source sketch hashes to spot an identical file. If a check fails it shows the matching message (Section 14) and sends nothing.
2. Browser → web: it sends the file to POST /api/v1/properties/{propertyId}/sketch (Section 13.6.1) with the sid cookie and the header X-Requested-With: fetch. When the property already has a plan, the URL carries the query parameter ?confirmReplace=true.
3. web (withApi): takes or creates the request ID, checks the CSRF header and Origin, resolves the session (unauthenticated if there is none), applies the per-account request limit, loads the property and checks ownership (not_found for a missing or foreign property, Section 6.10). Nothing in this step reads the body.
4. web: checks the property state. A property in reading gets invalid_state. A property that has a plan but no confirmReplace=true gets invalid_state with details.reason: 'confirm_replace_required'.
5. web: checks the upload frequency limit and, without consuming, the AI reading quotas: per account (AI_DAILY_LIMIT_PER_ACCOUNT), per property (AI_DAILY_LIMIT_PER_PROPERTY) and deployment-wide (AI_DAILY_LIMIT_GLOBAL). A reached quota returns 429 limit_reached with details: { limit, max, resetAt, retryAfterSeconds } and a Retry-After header when the reset time is known (Section 15.7, Section 13.2).
6. web: admission control. At most 4 upload bodies are read at once per web process and at most 1 per account. A request waits up to 10 s for a slot, then gets 429 rate_limited with details: { limit: 'C2', retryAfterSeconds: 5 } and Retry-After: 5.
7. web: reads the request body into memory, stopping at MAX_UPLOAD_BYTES + 1 bytes (payload_too_large, details: { maxBytes }). It then checks the magic bytes FF D8 FF (unsupported_media_type, details: { expected: 'image/jpeg', detected }), decodes the metadata with sharp (failOn: 'truncated', limitInputPixels: 50_000_000, at most 2 decodes at once per process), and checks the pixel limits after EXIF orientation: shortest side ≥ SKETCH_MIN_SHORT_SIDE_PX, longest side ≤ SKETCH_MAX_LONG_SIDE_PX, total ≤ SKETCH_MAX_MEGAPIXELS million. A failure gives sketch_unreadable with details: { reason, widthPx, heightPx }. It also computes the SHA-256 and the image-quality warnings (Section 7.5.4).
8. web: if the SHA-256 equals the current sketch or the current plan's source sketch, it returns 200 with duplicate: true and creates nothing (Section 7.5.6). A duplicate is not an error and consumes no quota.
9. web → S3: writes the original to sketches/<accountId>/<propertyId>/<sketchId>.jpg with one PutObject and ContentType: image/jpeg.
10. web → Postgres in one transaction: inserts the sketches row (the previous sketch and the existing plan are kept according to Section 7's replace rules, so Keep my previous plan stays possible), consumes the three AI quota counters, inserts a sketch_readings row with status queued, sets the property to reading and last_activity_at = now(), and sends sketch.read { readingId, requestId } through sendJob('sketch.read', …, { db: tx }), so the job exists if and only if the transaction commits (Section 16). If the transaction fails, the web process deletes the object written in step 9 and returns internal_error.
11. web → browser: 202 with UploadSketchResponse = { duplicate, duplicateOf, property, sketch, reading, qualityWarnings } (Section 13.6.1). The browser opens /properties/{propertyId}/reading and polls GET /api/v1/properties/{propertyId}/readings/latest (Section 7.6 sets the interval and UI).
12. worker (sketch.read): checks the reading's deadline (created_at + 10 min), marks it running with stage preparing, reads the original from S3, preprocesses it with sharp (EXIF auto-rotate, sRGB, metadata stripped, longest side ≤ 2048 px, JPEG quality 85), and writes the AI copy …/<sketchId>-ai.jpg.
13. worker → Anthropic (stage reading): calls SketchReader.read() with the AI copy. This is one forced record_sketch_reading tool call with a timeout of AI_TIMEOUT_MS. The output is validated with SketchReadingSchema. If validation fails, one repair call is made with the validation errors. There are at most 2 model calls per reading (Section 8). During retry backoff the reading stays running with stage reading.
14. worker (stage building): stores the raw validated JSON, timings, token counts and model_id on the reading. It runs solveReading(reading, { …, newId: uuidv7 }) to produce { document, flags, stats }, then checks document with parsePlanDocument(document, 'write').
15. worker → Postgres in one transaction: inserts or replaces the property's plan_documents row (revision = 1 on insert, revision + 1 on replace; source_sketch_id = the reading's sketch), stores review_flags, marks the reading succeeded, and sets the property to ready and last_activity_at = now().
16. Failure path: on a provider error, a second validation failure, a solver exception or the 10-minute deadline, the worker marks the reading failed with an error code and the property reading_failed. Section 16 decides which failures are retried automatically before the final failure. The AI quota is refunded (the bucket of the reading's creation hour is decremented) only when the reading made zero billable model calls or failed with solver_error or internal_error. Readings that pass the deadline without finishing are marked timeout by maintenance.cleanup; until then ReadingDto.stale is true and the screen shows the slow-reading message. GET endpoints never change state.
17. Browser: polling sees succeeded and navigates to /properties/{propertyId}/edit, or sees failed and shows Try again, Upload a different sketch, Start from a blank plan and, when a previous plan exists, Keep my previous plan (Section 7.7).

3.6 Data flow: edit and autosave #

1. Browser: the editor page loads the plan (GET …/plan: document, revision, reviewFlags) and, for the side-by-side sketch reference, the AI copy through GET …/sketch/preview, which web streams after an ownership check (generating the AI copy on the fly if it does not exist yet). The original upload is never displayed. A property with no sketch shows the "No sketch uploaded" state with an Upload sketch button (Section 10.15).
2. Browser: every user operation is an immutable update to the Zustand store. Each completed operation (a drag on pointer-up, a field on commit, marking a review flag as checked) pushes one undo history entry, with at most 100 (Section 10).
3. Browser: derived data is computed in the browser by src/plan: walls per part (memoised inside src/plan; callers never pass walls), room and part areas, and validation issues (validatePlan(doc, { reviewFlags })). The canvas draws renderPartSvgElements(doc, partId, { placement: 'plan', layout }) — plan-millimetre coordinates with every paper style token scaled by the layout's scale denominator — through SvgNodeView, and keeps its own plan-millimetre viewBox.
4. Browser: 1500 ms after the last change, the autosave sends PUT /api/v1/properties/{propertyId}/plan with { revision, document, reviewFlags }. Only one save is in flight at a time. Changes made during a save start a new 1500 ms debounce after it completes. The editor also keeps a local backup of unsaved changes in localStorage (Section 10.20.7); backups are removed on save, sign-out, account deletion, account switch at verify and property deletion.
5. web: authenticates, checks CSRF and ownership, and rejects bodies over 1,500,000 bytes (payload_too_large). It parses the body with z.strictObject({ revision: z.int().min(1), document: PlanDocumentSchema, reviewFlags: ReviewFlagsSchema }) (document ≤ 1 MB serialised, at most 600 review flags) through parsePlanDocument(…, 'write'). A structural failure gives validation_failed, with zod issues in details. Semantic validation rules (Section 9) do not block saving. A plan with blocking errors is still a valid work in progress. Only export is blocked. The server drops review flags whose target no longer exists (pruneReviewFlags, Section 5.11).
6. web → Postgres in one transaction: UPDATE plan_documents SET document = $1, review_flags = $2, revision = revision + 1, updated_at = now() WHERE property_id = $3 AND revision = $4 RETURNING revision. If no row is updated, the response is revision_conflict with details: { currentRevision }. The same transaction sets properties.last_activity_at = now() and mirrors document.displayUnit into properties.display_unit (document.title is not mirrored). The editor never calls PATCH /api/v1/properties/{propertyId}.
7. web → browser: the new revision. The store records it, and the status shows "Saved".
8. Failures: on a network failure the editor keeps all changes, shows "Offline – changes kept", and retries with backoff. On revision_conflict it stops autosaving and offers Reload and a two-step Overwrite… (Section 10.20.5). On 401 it shows the session-expired modal and keeps the backup. On 404 the property is gone and the backup is removed. On 403 the save is blocked: the editor shows an error state, keeps the backup and retries only when the user asks.

3.7 Data flow: export and email #

1. Browser: the user clicks Finish & email. The editor flushes any pending autosave first, then sends POST /api/v1/properties/{propertyId}/exports with { revision }.
2. web: authenticates, checks CSRF and ownership, then runs the checks in this order (Section 12.3.1): the property must be ready (invalid_state); revision must equal the stored revision (revision_conflict); no other export of this property may be queued or rendering (invalid_state); the export quota (EXPORT_DAILY_LIMIT_PER_ACCOUNT in any 24 h) must not be used up (429 limit_reached, limit: 'exports_per_day'); and validatePlan(document, { reviewFlags, includePageFit: true }) must report no blocking error (plan_invalid, with the issue list in details; the editor opens the Issues panel).
3. web → Postgres in one transaction: consumes the export quota, inserts an exports row with status = queued, email_status = not_sent, the revision, the resolved export title and a document snapshot (document_snapshot), so that later edits cannot change what is rendered (Section 5). It sets last_activity_at = now() (not updated_at) and sends plan.export { exportId, requestId } through sendJob(…, { db: tx }).
4. web → browser: 202 with the export. The editor shows the export status dialog and the top-bar chip and polls the export (Sections 10.19 and 12.9).
5. worker (plan.export): sets status = rendering and calls renderPageSvg(snapshot, { fontFaceCss: getEmbeddedFontCss() }) to produce one SVG string. It wraps the SVG in a minimal HTML page with the three Inter weights embedded as base64 @font-face rules and no external requests. It opens the page in Playwright Chromium, then:
   • page.pdf() at the true paper size → PDF (vector)
   • page.screenshot() at the 200 DPI pixel size of the paper (A4 landscape 2339×1654) → PNG
   • sharp converts the PNG to JPG (quality 90, sRGB) and resizes it to the 480 px-wide thumbnail PNG. Section 12 owns the exact parameters.
6. worker → S3: uploads exports/<accountId>/<propertyId>/<exportId>/<slug>-floorplan.{pdf,png,jpg} and thumbnails/<accountId>/<propertyId>.png. worker → Postgres (recordRendered, one transaction): inserts three export_files rows (byte_size, content_type), sets status = rendered, sets properties.thumbnail_updated_at, and sends email.send { kind: 'plan', exportId, requestId } through sendJob(…, { db: tx }).
7. worker (email.send): sets email_status = sending, loads the files from S3, and composes the email (Section 12 owns the subject, body and attachment rules, including PDF only when the attachments exceed 15 MB). It sends through Nodemailer to the account email only. On success it sets email_status = sent with the sent time. A retryable failure is retried: the first attempt plus up to 5 retries (6 sends in total), on the schedule in Section 12.7.5. The final failure sets email_status = failed. The user may resend up to 5 times per export (exports.email_resend_count).
8. Render failure: status = failed with an error code. The UI shows "Export failed" and offers re-export (Section 12).
9. Browser: shows the status: queued, rendering, sending, sent, render failed or email failed. The property page's Exports list shows every export. Download links stream each file through web after a session and ownership check. There are never direct storage URLs.

3.8 Rationale for key choices #

3.9 Browser support #

Rules:

1. The app does not sniff user agents and never blocks a browser. Older browsers may work, but they are not tested.
2. The app uses only web platform features that are available in all four supported browsers (Baseline "widely available" or "newly available" across them). It ships no polyfills.
3. The editor needs a viewport at least 1024 px wide and is designed for 1280×720 and above. Below 1024 px it shows the "use a larger screen" notice (Section 10). Other pages work from 360 px wide (Section 4.10).
4. Automated end-to-end tests run in Chromium (Section 17.8). Firefox, Safari and Edge are covered by the manual release smoke test (Section 17.16, gate 6).
5. JavaScript is required. Without JavaScript, the sign-in page shows a <noscript> message (copy in Section 14).

4. Conventions & Configuration #

4.1 General code rules #

1. All source code is TypeScript (.ts and .tsx). The only JavaScript files are tool configs that need it (eslint.config.mjs, eslint.boundaries.mjs, postcss.config.mjs) and the two launcher scripts that must run without tsx (scripts/docker/sync-playwright-version.mjs, run by postinstall, and scripts/visual/run-in-docker.mjs).
2. ES modules only (import/export). No require.
3. Named exports only, except where Next.js requires a default export (page.tsx, layout.tsx, not-found.tsx, error.tsx, global-error.tsx, next.config.ts) and in tool config files that require one.
4. No any. Use unknown and narrow it, usually with zod. Non-null assertions (!) are allowed only with a comment that explains why the value cannot be null.
5. No classes except AppError and its subclasses, the ApiError client error class, and adapters that wrap a stateful SDK client or provider (AnthropicSketchReader, FakeSketchReader, the S3 object store). Everything else is functions and plain data.
6. Pure functions are preferred everywhere and are mandatory in src/plan.
7. Numeric unit suffixes. Every number that carries a unit has the unit in its name: widthMm, areaMm2, timeoutMs, sizeBytes, rotationDeg, sizePt, widthPx, dpi. Bare names such as width are only allowed for unitless values.
8. Time. App-side server code never calls new Date() or Date.now() for the current time. It uses now() from src/server/clock.ts (and now().getTime() for epoch milliseconds), which tests can freeze. SQL that stamps or compares against the current time uses the database now(); tests of those rules age rows instead of freezing a clock (Section 17.3.2). src/plan never reads the time.
9. IDs are UUIDv7 strings created by uuidv7() from src/plan/ids.ts, the only id helper, in the browser (new rooms, openings and so on) and on the server (rows). Code that must be deterministic (the solver, PlanDocument factories) takes an injected newId: () => string instead of calling uuidv7() itself. Database uuid columns have no default generator, because the application always supplies the id.
10. Every external input is parsed with zod at the boundary: env (Section 4.9), request bodies, query strings, route params, job payloads, AI output, stored JSON read from the database, and API responses in the browser (DTO schemas from src/lib/api/dto.ts). PlanDocuments are always parsed through parsePlanDocument(input, 'read' | 'write') from src/plan/schema/parse.ts (Section 5.10.6); direct calls of PlanDocumentSchema.parse outside src/plan/schema/ are a lint error (Section 4.4).
11. No console.* in src/ (lint error). Use the logger (Section 4.6). Browser code does not log in production builds.
12. Comments explain why, not what. Each rule taken from this specification links to its section in a comment, for example // Spec 9: closing tolerance = internalWallMm/2 + 50.

4.2 TypeScript configuration #

tsconfig.json (whole project):

{
  "compilerOptions": {
    "target": "ES2024",
    "lib": ["ES2024", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",                      // keep whatever value Next.js writes here if it rewrites this field
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noPropertyAccessFromIndexSignature": true,
    "useUnknownInCatchVariables": true,
    "forceConsistentCasingInFileNames": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "resolveJsonModule": true,
    "allowJs": false,
    "skipLibCheck": true,
    "noEmit": true,
    "incremental": true,
    "paths": { "@/*": ["./src/*"] },
    "plugins": [{ "name": "next" }]
  },
  "include": ["next-env.d.ts", "src/**/*.ts", "src/**/*.tsx", "tests/**/*.ts", "tests/**/*.tsx",
              "scripts/**/*.ts", ".next/types/**/*.ts", "*.ts"],
  "exclude": ["node_modules", "drizzle", "dist", ".next/standalone"]
}

tsconfig.plan.json (enforces the purity of src/plan at the type level, Section 4.4):

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "lib": ["ES2024"],           // no DOM types
    "types": [],                 // no @types/node
    "plugins": []
  },
  "include": ["src/plan/**/*.ts"]
}

src/plan/env.d.ts declares only the single Web Crypto function that ids.ts needs, and nothing else:

// Isomorphic Web Crypto: available in all supported browsers and in Node.js as globalThis.crypto.
declare global {
  // eslint-disable-next-line no-var -- a global declaration must use var
  var crypto: { getRandomValues<T extends ArrayBufferView>(array: T): T };
}
export {};

If the installed polylabel line ships no type declarations, add src/plan/geometry/polylabel.d.ts declaring its default export ((polygon: number[][][], precision?: number) => [number, number] & { distance: number }) and nothing else.

Rules:

• exactOptionalPropertyTypes stays off. It conflicts with React and library prop types and adds friction without much benefit here.
• Optional values are T | null in stored data and API payloads. Never leave a JSON field out: required-but-nullable fields keep the JSON shapes exact. undefined is used only for optional function parameters, in-memory options objects and optional request-body fields that Section 13 marks optional.
• enum and namespace are not used. Use string literal unions derived from zod (z.enum([...])) and as const objects.
• satisfies is preferred over type annotations for constant tables, so literal types are kept.

4.3 Lint and format #

Prettier (.prettierrc.json):

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "jsxSingleQuote": false,
  "trailingComma": "all",
  "bracketSpacing": true,
  "arrowParens": "always",
  "endOfLine": "lf"
}

ESLint (eslint.config.mjs, flat config). The rules below are required. Section 4.4 adds the boundary rules.

import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import nextVitals from 'eslint-config-next/core-web-vitals';
import prettier from 'eslint-config-prettier';
import { boundaryConfigs, NO_ENUM, NO_DIRECT_PLAN_PARSE } from './eslint.boundaries.mjs'; // Section 4.4

export default tseslint.config(
  { ignores: ['.next/**', 'dist/**', 'drizzle/**', 'coverage/**', 'playwright-report/**', 'test-results/**', 'next-env.d.ts'] },
  js.configs.recommended,
  ...nextVitals,
  ...tseslint.configs.strictTypeChecked,
  ...tseslint.configs.stylisticTypeChecked,
  {
    languageOptions: { parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname } },
    rules: {
      'no-console': 'error',
      eqeqeq: ['error', 'always'],
      'no-restricted-syntax': ['error', NO_ENUM, NO_DIRECT_PLAN_PARSE],
      'no-restricted-properties': ['error',
        { object: 'process', property: 'env', message: 'Read configuration through src/server/config.ts (Section 4.9).' }],
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/no-floating-promises': 'error',
      '@typescript-eslint/no-misused-promises': ['error', { checksVoidReturn: { attributes: false } }],
      '@typescript-eslint/consistent-type-imports': ['error', { fixStyle: 'inline-type-imports' }],
      '@typescript-eslint/switch-exhaustiveness-check': 'error',
      '@typescript-eslint/restrict-template-expressions': ['error', { allowNumber: true }],
      'import/no-default-export': 'error',
    },
  },
  {
    // Next.js and tool files that must default-export
    files: ['src/app/**/{page,layout,not-found,error,global-error,loading,template,default}.tsx',
            '*.config.{ts,mjs}', 'next.config.ts', 'playwright.config.ts', 'vitest.config.ts', 'drizzle.config.ts'],
    rules: { 'import/no-default-export': 'off' },
  },
  {
    // The only src/ files allowed to read process.env (Section 4.9; src/lib/env.ts reads NODE_ENV only)
    files: ['src/server/config.ts', 'src/instrumentation.ts', 'src/lib/env.ts'],
    rules: { 'no-restricted-properties': 'off' },
  },
  {
    // Outside src/, scripts, tests and tool configs may read process.env (for example DATABASE_URL in tests/setup)
    files: ['scripts/**/*.{ts,mjs}', 'tests/**/*.{ts,tsx}', '*.config.{ts,mjs}'],
    rules: { 'no-console': 'off', 'no-restricted-properties': 'off' },
  },
  {
    // Schema unit tests exercise PlanDocumentSchema directly
    files: ['tests/unit/plan/schema/**/*.ts'],
    rules: { 'no-restricted-syntax': ['error', NO_ENUM] },
  },
  ...boundaryConfigs,
  prettier,
);

Rules:

• npm run lint uses --max-warnings=0, so every rule is effectively an error.
• eslint-disable comments must name the rule and give a reason (// eslint-disable-next-line rule-name -- reason). Disabling a whole file is not allowed.
• Formatting is never a lint concern. Prettier owns it, and eslint-config-prettier comes last.

4.4 Module boundaries #

The boundary rules are defined in eslint.boundaries.mjs at the repository root and spread into the main config. They use ESLint's core no-restricted-imports, no-restricted-globals, no-restricted-properties and no-restricted-syntax rules, so they need no extra plugin. Section 3.4.1 states the same rules as a table.

4.4.1 src/plan is pure and isomorphic #

src/plan/** runs unchanged in the browser (editor), in the web process (export pre-check, plan save) and in the worker (solver, export render). It must:

• have no I/O: no network, file system, database, timers, randomness other than ids.ts, or reading the clock;
• use no DOM: no window, document, DOMParser or getBBox, and no text measurement through the browser (text is measured with fontMetrics.generated.ts, Section 11.14);
• use no Node APIs: no node:* modules, process, Buffer or __dirname;
• import nothing except zod, clipper2-js, polylabel and relative or @/plan/** paths.

It is enforced in three places:

1. ESLint (eslint.boundaries.mjs):

export const NO_ENUM = { selector: 'TSEnumDeclaration', message: 'Use a z.enum or a string literal union (Section 4.2).' };
export const NO_DIRECT_PLAN_PARSE = {
  selector: "CallExpression[callee.object.name='PlanDocumentSchema'][callee.property.name=/^(parse|safeParse|parseAsync|safeParseAsync)$/]",
  message: 'Use parsePlanDocument(input, mode) from src/plan/schema/parse.ts (Section 5.10.6).',
};
const NO_CLOCK = { selector: "NewExpression[callee.name='Date']", message: 'src/plan must not read the clock.' };
const USE_CLIENT = { selector: "Program > ExpressionStatement[directive='use client']", message: 'Client components live in src/components or src/editor (Section 4.4).' };

const NODE_BUILTINS = ['fs', 'path', 'os', 'crypto', 'stream', 'http', 'https', 'url', 'util', 'buffer',
  'child_process', 'worker_threads', 'events', 'zlib', 'net', 'tls', 'dns', 'async_hooks', 'perf_hooks'];

// Import pattern groups. Every no-restricted-imports array repeats DEV_ONLY, because a later config
// object that sets the same rule replaces the earlier setting for the files it matches.
const DEV_ONLY = { group: ['vitest', 'vitest/*', '@vitest/*', '@playwright/test', '@testing-library/*', 'jsdom',
  'fast-check', 'fast-xml-parser', 'pixelmatch', 'pdfjs-dist', 'pdfjs-dist/*', 'fontkit', 'esbuild', 'tsx', 'tsx/*'],
  message: 'Development-only packages must not be imported by src/ (Section 3.1.3).' };
const SERVER_CODE = { group: ['@/server/*', '@/server/**', '@/worker/*', '@/worker/**'], message: 'Browser code must not import server code (Section 3.4.1).' };
const WORKER_CODE = { group: ['@/worker/*', '@/worker/**'], message: 'web must not import the worker.' };
const UI_CODE = { group: ['@/app/*', '@/app/**', '@/components/*', '@/components/**', '@/editor/*', '@/editor/**',
  '@/client/*', '@/client/**', 'react', 'react/*', 'react-dom', 'react-dom/*'], message: 'Server code must not import UI code (Section 3.4.1).' };
const NEXT = { group: ['next', 'next/*'], message: 'Only web-only modules may import Next.js (Section 3.4.1).' };
// Web-only server modules: the only src/server files that may import next/*. errors.ts is shared.
const WEB_ONLY_FILES = ['src/server/http/withApi.ts', 'src/server/http/securityHeaders.ts',
  'src/server/http/streamFile.ts', 'src/server/http/afterResponse.ts', 'src/server/auth/requireSession.ts'];
const WEB_ONLY_SERVER = { group: ['@/server/http/withApi', '@/server/http/securityHeaders',
  '@/server/http/streamFile', '@/server/http/afterResponse', '@/server/auth/requireSession'],
  message: 'The worker and the ops CLI must not import web-only modules (Section 3.4.1).' };
const NODE_PROTOCOL = { regex: '^node:', message: 'Browser code must not import Node built-ins.' };

export const boundaryConfigs = [
  {
    files: ['src/**/*.{ts,tsx}'],
    rules: { 'no-restricted-imports': ['error', { patterns: [DEV_ONLY] }] },
  },
  {
    files: ['src/plan/**/*.ts'],
    rules: {
      'no-restricted-imports': ['error', {
        patterns: [
          { regex: '^(?!zod$|clipper2-js$|polylabel$|@/plan/|\\.{1,2}/).*', message: 'src/plan may import only zod, clipper2-js, polylabel and src/plan modules (Section 4.4).' },
        ],
        paths: NODE_BUILTINS.map((name) => ({ name, message: 'No Node APIs in src/plan (Section 4.4).' })),
      }],
      'no-restricted-globals': ['error',
        'window', 'document', 'navigator', 'localStorage', 'sessionStorage', 'fetch', 'XMLHttpRequest',
        'process', 'Buffer', 'require', '__dirname', '__filename', 'setTimeout', 'setInterval',
        'requestAnimationFrame', 'performance'],
      'no-restricted-properties': ['error',
        { object: 'Date', property: 'now', message: 'src/plan must not read the clock.' },
        { object: 'Math', property: 'random', message: 'Use an injected newId or ids.ts.' },
        { object: 'process', property: 'env', message: 'Read configuration through src/server/config.ts (Section 4.9).' }],
      'no-restricted-syntax': ['error', NO_ENUM, NO_DIRECT_PLAN_PARSE, NO_CLOCK],
    },
  },
  {
    // parse.ts and the schema modules are the only places that call PlanDocumentSchema directly
    files: ['src/plan/schema/**/*.ts'],
    rules: { 'no-restricted-syntax': ['error', NO_ENUM, NO_CLOCK] },
  },
  {
    files: ['src/lib/**'],
    rules: { 'no-restricted-imports': ['error', { patterns: [DEV_ONLY, SERVER_CODE, UI_CODE, NEXT, NODE_PROTOCOL] }] },
  },
  {
    files: ['src/components/**', 'src/editor/**', 'src/client/**'],
    rules: { 'no-restricted-imports': ['error', { patterns: [DEV_ONLY, SERVER_CODE, NODE_PROTOCOL] }] },
  },
  {
    files: ['src/app/**'],
    rules: { 'no-restricted-imports': ['error', { patterns: [DEV_ONLY, WORKER_CODE] }] },
  },
  {
    files: ['src/app/**'],
    ignores: ['src/app/**/error.tsx', 'src/app/global-error.tsx'], // Next.js requires these to be client components
    rules: { 'no-restricted-syntax': ['error', NO_ENUM, NO_DIRECT_PLAN_PARSE, USE_CLIENT] },
  },
  {
    files: ['src/server/**'],
    ignores: [...WEB_ONLY_FILES, 'src/server/ops/**'],
    rules: { 'no-restricted-imports': ['error', { patterns: [DEV_ONLY, UI_CODE, NEXT, WORKER_CODE] }] },
  },
  {
    // Web-only server modules: may use next/headers, next/navigation and next/server
    files: WEB_ONLY_FILES,
    rules: { 'no-restricted-imports': ['error', { patterns: [DEV_ONLY, UI_CODE, WORKER_CODE] }] },
  },
  {
    files: ['src/worker/**', 'src/server/ops/**'],
    rules: { 'no-restricted-imports': ['error', { patterns: [DEV_ONLY, UI_CODE, NEXT, WEB_ONLY_SERVER] }] },
  },
];

When an ESLint config object sets a rule that an earlier object also sets, the later setting replaces the earlier one for the matching files. For that reason every no-restricted-imports array repeats DEV_ONLY, every no-restricted-syntax array repeats NO_ENUM (and NO_DIRECT_PLAN_PARSE wherever direct parsing stays forbidden), and the src/plan object's no-restricted-properties array repeats the process.env restriction from Section 4.3. Any future boundary object that sets one of these rules must repeat the shared entries in the same way, and must be placed after the broader object it narrows.

1. Types: npm run typecheck also checks tsconfig.plan.json, which has no DOM types and no Node types (Section 4.2). Any use of document or Buffer in src/plan fails to compile.
2. Test: tests/unit/plan/purity.test.ts imports @/plan in a Vitest node environment that has no DOM, and runs a full pipeline (solveReading → validatePlan → renderPageSvg) on a fixture. This catches runtime-only leaks.

4.4.2 Client vs server code #

• Files under src/app/** are server components or route handlers. They must not contain 'use client', and lint enforces this. Client components live in src/components/** and src/editor/**, and start with 'use client' when they use state, effects or event handlers.
• Browser code cannot import src/server/** because of the lint boundary above, and Next.js also fails the build if a client bundle pulls in a Node-only package such as pg or sharp. The server-only package is not used (Section 3.1.3).
• No environment variable reaches the browser. No NEXT_PUBLIC_* variables exist. Data the browser needs (for example the "Deletes on" date or the privacy-notice link) comes through API responses or server-rendered props. The one exception is the build mode: src/lib/env.ts exports IS_DEV = process.env.NODE_ENV !== 'production', which Next.js inlines at build time. It is the only file outside src/server/config.ts and src/instrumentation.ts that may touch process.env, and browser code that needs a development-only check imports IS_DEV from it.

4.5 Error handling #

4.5.1 Server: AppError #

// src/server/http/errors.ts
export const ERROR_CODES = [/* exactly the canonical codes of Section 13.2, in table order */] as const;
export type ErrorCode = (typeof ERROR_CODES)[number];
export const ERROR_HTTP_STATUS = { /* one entry per code, copied from Section 13.2 */ } as const satisfies Record<ErrorCode, number>;

export class AppError extends Error {
  readonly code: ErrorCode;
  readonly details: Record<string, unknown> | null;
  /** Optional override of the user-facing message; defaults to the Section 14 message for `code`. */
  readonly publicMessage: string | null;

  constructor(
    code: ErrorCode,
    opts: { message?: string; details?: Record<string, unknown> | null; cause?: unknown } = {},
  ) {
    super(opts.message ?? code, { cause: opts.cause });
    this.name = 'AppError';
    this.code = code;
    this.details = opts.details ?? null;
    this.publicMessage = opts.message ?? null;
  }
}

export const isAppError = (e: unknown): e is AppError => e instanceof AppError;

• src/server/http/errors.ts is the only place that lists error codes. ERROR_CODES is a const array of exactly the codes in Section 13.2, and ERROR_HTTP_STATUS maps each one to the HTTP status in that table. No other code strings may be thrown or returned. The file imports nothing from next/*, so the worker, job handlers and the ops CLI import AppError and ErrorCode from it directly; the other files under src/server/http/ are web-only (Section 4.4).
• Code throws AppError for every expected failure: not found, validation, state, limits, and so on. Unexpected failures (bugs, driver errors) are not wrapped. They propagate to the boundary and become internal_error.
• details must be JSON-serialisable and must never contain secrets, tokens, emails, file contents or stack traces. Allowed contents: zod issues (path, code, message), currentRevision, reason values, the limit details of Section 13.2 (limit, max, resetAt, retryAfterSeconds), the validation issue list (Section 9 shape) and upload detail fields (maxBytes, expected, detected, widthPx, heightPx).

4.5.2 Route boundary: withApi #

Every Route Handler is wrapped:

// src/server/http/withApi.ts (shape — behaviour is normative)
type ApiContext = {
  requestId: string;
  account: { id: string; email: string } | null; // non-null when auth: 'required'
  params: Record<string, string>;                // e.g. { propertyId } or { exportId, format }
};
type ApiOptions = { auth: 'required' | 'none'; csrf?: boolean /* default: true for non-GET/HEAD */ };

export function withApi(
  opts: ApiOptions,
  handler: (req: Request, ctx: ApiContext) => Promise<Response>,
): (req: Request, routeCtx: { params: Promise<Record<string, string>> }) => Promise<Response>;

Order of operations inside withApi:

1. Take the request ID from the x-request-id request header, which src/proxy.ts sets on every request it handles (Section 4.7). If the header is absent — routes excluded from the proxy matcher, such as the sketch upload route (Section 7.5.3) — generate a new uuidv7(). Open an AsyncLocalStorage log context { requestId }.
2. If csrf applies, check X-Requested-With: fetch and the Origin header against APP_URL's origin. If either fails, throw AppError('forbidden').
3. If auth: 'required', resolve the session from the sid cookie (Section 6), which also re-checks the allowlist. If there is no valid session, throw AppError('unauthenticated'). Add accountId to the log context, then consume the per-account request limit (RL4, Section 15.7).
4. Await the handler. Handlers parse bodies, query strings and params with their zod schemas and size limits (Section 13.1.4).
5. On success, return the handler's Response with X-Request-Id set, plus Cache-Control: no-store for JSON (file routes set their own caching, Section 15.3.6).
6. On error, map it with toErrorResponse(err, requestId):

1. On every response, success or error, apply the Section 15.4 security headers (src/server/http/securityHeaders.ts), so routes that bypass the proxy carry them too.

The error envelope shape is canonical in Section 13: { "error": { "code", "message", "details", "requestId" } }. The requestId in the body always equals the X-Request-Id response header. Headers for limits:

• rate_limited (frequency limits RL1–RL6 and upload admission C2): details: { limit, retryAfterSeconds }, and withApi always sets Retry-After: <retryAfterSeconds>.
• limit_reached (quotas): details: { limit, max, resetAt, retryAfterSeconds }, and withApi sets Retry-After only when retryAfterSeconds is not null.

4.5.3 Worker jobs #

• Every job payload carries requestId: string | null: the ID of the request that sent the job, or null for scheduled jobs (Section 16). Job handlers run inside a log context { jobId, requestId }; when requestId is null the field is omitted.
• Handlers throw AppError for known failures and let unexpected errors propagate. Section 16 owns the mapping from failure to retry-or-fail, and the final status written to sketch_readings or exports.
• A job never leaves its entity in a non-final state. When retries run out, the handler's final-failure path sets the reading to failed (and the property to reading_failed), the export to failed, or email_status = failed, and stores the error code. maintenance.cleanup repairs anything a crashed process left behind (Section 16).
• Jobs that a handler sends (for example email.send after a render) are sent inside the handler's own database transaction through sendJob(name, data, { db: tx }), exactly like web.

4.5.4 Browser #

// src/client/apiClient.ts (shape)
export class ApiError extends Error {
  constructor(
    readonly status: number,
    readonly code: string,           // one of the Section 13 codes, or 'network_error' (browser-only, never from the server)
    message: string,
    readonly details: Record<string, unknown> | null,
    readonly requestId: string | null,
  ) { super(message); this.name = 'ApiError'; }
}

export async function api<T>(path: `/api/v1/${string}`, init?: RequestInit & { json?: unknown }): Promise<T>;

• It always sends credentials: 'same-origin', and sends X-Requested-With: fetch on every request. JSON bodies are sent with Content-Type: application/json.
• A 2xx returns body.data (and 204 returns undefined). A non-2xx with a valid envelope throws ApiError with the envelope fields. A fetch rejection throws ApiError(0, 'network_error', …). Responses that carry DTOs are parsed with the schemas in src/lib/api/dto.ts.
• 401 handling. api() itself never redirects. For /api/v1/auth/* calls the page handles every status itself (for example the verify page shows the details.reason state). The editor handles a 401 with its session-expired modal, after writing the local backup (Section 10.20.5). Every other page reacts to 401 unauthenticated by navigating to /sign-in?next=<current path>.
• In the editor, only 404 not_found means the property is gone. A 403 forbidden is shown as an error state; the local backup is kept and the save is retried only when the user asks (Section 10.20.5).
• Error messages shown to the user come from the code-to-message table in Section 14, not from message. The request ID is shown in small text on unexpected errors ("Reference: ") so problems can be traced.
• React error boundaries (src/components/system/ErrorBoundary.tsx) catch render errors and show the Section 14 generic error with a Reload button.

4.6 Logging #

4.6.1 Logger #

Both processes use one pino logger factory and write JSON lines to stdout only. In production, transports, files and log shipping in-process are not used. Section 18 collects the container output.

// src/server/log/logger.ts
import pino from 'pino';
import { getLogContext } from './context';

export function createLogger(service: 'web' | 'worker', level: string) {
  return pino({
    level,
    base: { service },                     // no pid/hostname
    messageKey: 'msg',
    timestamp: () => `,"ts":"${new Date().toISOString()}"`,
    formatters: { level: (label) => ({ level: label }) },
    mixin: () => getLogContext(),          // { requestId?, accountId?, jobId? } from AsyncLocalStorage
    redact: {
      paths: [
        'password', '*.password', 'token', '*.token', 'secret', '*.secret', 'apiKey', '*.apiKey',
        'authorization', '*.authorization', 'cookie', '*.cookie', 'headers.cookie', 'headers.authorization',
        'req.headers.cookie', 'req.headers.authorization', 'email', '*.email', 'to', '*.to',
        'image', '*.image', 'data', '*.data', 'base64', '*.base64', 'document', '*.document',
      ],
      censor: '[REDACTED]',
    },
    serializers: { err: pino.stdSerializers.err },
  });
}

The new Date() call in timestamp is the one permitted exception to Section 4.1 rule 8, because log timestamps must show real wall-clock time even when tests freeze the clock. The one-shot entrypoints (dist/migrate.mjs, dist/storage-init.mjs, dist/ops.mjs) log with service: 'worker'.

4.6.2 Fields #

The web process writes one access log line per API request at info, with event: 'http.request', method, route pattern (for example /api/v1/properties/[propertyId], never the raw URL or its query string), status and durationMs.

4.6.3 What is never logged #

4.6.4 Levels #

4.6.5 Development #

npm run worker:dev pipes output through pino-pretty. For web, start it with npm run dev | npx pino-pretty when readable output is needed. Production output is always raw JSON.

4.7 Request IDs #

1. src/proxy.ts (the Next.js request interception file of the Section 3.1.2 line) runs on every request to pages and /api/v1/* except the routes its matcher excludes (the sketch upload route, Section 7.5.3). It reads the incoming X-Request-Id header. If the value matches ^[A-Za-z0-9._:-]{8,128}$ it is kept, otherwise a new uuidv7() is generated.
2. The proxy forwards the ID to the route as the request header x-request-id and sets the response header X-Request-Id. For routes the proxy does not run on, withApi generates the ID and sets the header itself (Section 4.5.2).
3. withApi reads it, puts it in the log context, and adds it to every error envelope.
4. When a request sends a job, the payload includes requestId. The worker logs it with jobId, so one user action can be traced from the browser to the email. Scheduled jobs carry requestId: null.
5. Emails do not contain request IDs.
6. The browser shows the request ID only on unexpected errors (Section 4.5.4).

4.8 Time handling #

src/lib/time.ts:

export const DISPLAY_TIME_ZONE = 'Europe/London';

const dateTimeFmt = new Intl.DateTimeFormat('en-GB', {
  timeZone: DISPLAY_TIME_ZONE, day: 'numeric', month: 'short', year: 'numeric',
  hour: '2-digit', minute: '2-digit', hourCycle: 'h23',
});
const dateFmt = new Intl.DateTimeFormat('en-GB', {
  timeZone: DISPLAY_TIME_ZONE, day: 'numeric', month: 'short', year: 'numeric',
});
// Calendar dates carry no time zone: format the date as written, never shifted.
const calendarFmt = new Intl.DateTimeFormat('en-GB', {
  timeZone: 'UTC', day: 'numeric', month: 'short', year: 'numeric',
});

// en-GB ICU data prints September as "Sept"; the UI always uses 3-letter months.
const sep = (s: string): string => s.replace(/\bSept\b/, 'Sep');

/** "31 Oct 2026, 14:05" (DISPLAY_TIME_ZONE) */
export const formatDateTime = (iso: string): string => sep(dateTimeFmt.format(new Date(iso)));
/** "31 Oct 2026" (DISPLAY_TIME_ZONE date of an instant) */
export const formatDate = (iso: string): string => sep(dateFmt.format(new Date(iso)));
/** "31 Oct 2027" from "2027-10-31" (a calendar date such as deletesOn) */
export const formatCalendarDate = (ymd: string): string => sep(calendarFmt.format(new Date(`${ymd}T00:00:00Z`)));

Rules:

• The time zone is always passed explicitly, so server rendering and browser hydration produce the same string whatever time zone the user's machine is set to. The UI never uses the machine's local time zone.
• The UI never shows relative times ("5 minutes ago"). It shows absolute times (for example "Edited 31 Oct 2026, 14:05", or a quota reset time) in DISPLAY_TIME_ZONE (Europe/London by default, Section 1.2 Q15); only "Deletes on" dates are always Europe/London calendar dates. Absolute times avoid hydration differences and ambiguity.
• If Intl produces a different separator in some runtime (for example "31 Oct 2026 at 14:05"), formatDateTime must normalise the output to the exact pattern D MMM YYYY, HH:mm. Unit tests pin all three examples above.
• formatDate, formatDateTime and formatCalendarDate replace Sept with Sep. The unit tests also pin 7 Sep 2026 and 7 Sep 2026, 09:05.

4.9 Configuration: environment variables #

4.9.1 The environment variable table #

This is the one canonical list. Inside src/, no code reads process.env except src/server/config.ts, NEXT_RUNTIME in src/instrumentation.ts, and NODE_ENV in src/lib/env.ts (Section 4.4.2). Lint enforces this with no-restricted-properties (Section 4.3). Scripts, tests and tool configs outside src/ are exempt. The "Process" column says which process validates and uses each variable; a variable not marked for a process is ignored by that process. The one-shot entrypoints (dist/migrate.mjs, dist/storage-init.mjs, dist/ops.mjs, and their tsx equivalents in development) run with the worker's environment and validate it with loadConfig('worker').

A hostname is local when it is exactly localhost or 127.0.0.1. Several rules below depend on whether the hostname of APP_URL is local.

Variables that do not exist, on purpose: there is no SESSION_SECRET, because sessions are random tokens stored hashed (Section 6); no NEXT_PUBLIC_* variable (Section 4.4.2); and no worker health port, because worker health is a heartbeat file checked by dist/worker-healthcheck.mjs (Section 16.7.3). Plan structure limits (8 parts, 60 rooms, 200 openings, 150 fixtures and 50 labels per part, 1 MB document) are not environment variables. They are the PLAN_LIMITS constants in src/plan/schema/planDocument.ts (Section 5.10), because the browser and the server must enforce exactly the same limits. Upload admission (4 bodies per process, 1 per account, 10 s wait), decode concurrency (2 in web, 1 in worker) and database pool sizes are code constants (Sections 15 and 16). Product defaults (paper, units, walls, disclaimer, display name, time zone) are code constants (Section 1.2).

4.9.2 Parsing and boot behaviour #

// src/server/config.ts (normative shape)
import { z } from 'zod';
import { PRODUCT_NAME } from '@/lib/product';

type Env = Record<string, string | undefined>;
export type ProcessRole = 'web' | 'worker';

/** Empty or whitespace-only values are treated as unset. */
function cleanEnv(env: Env): Record<string, string> {
  return Object.fromEntries(
    Object.entries(env)
      .filter((e): e is [string, string] => typeof e[1] === 'string' && e[1].trim() !== '')
      .map(([k, v]) => [k, v.trim()]),
  );
}

const LOCAL_HOSTNAMES = new Set(['localhost', '127.0.0.1']);
const isLocalUrl = (s: string): boolean => LOCAL_HOSTNAMES.has(new URL(s).hostname);

const intVar = (min: number, max: number) =>
  z.string().regex(/^\d+$/, 'must be a whole number')
    .transform(Number)
    .pipe(z.number().int().min(min, `must be ≥ ${min}`).max(max, `must be ≤ ${max}`));

const boolVar = z.string().toLowerCase()
  .pipe(z.enum(['true', 'false', '1', '0'], { error: 'must be true or false' }))
  .transform((v) => v === 'true' || v === '1');

const httpUrl = z.string().refine((s) => {
  try { const u = new URL(s); return u.protocol === 'http:' || u.protocol === 'https:'; } catch { return false; }
}, 'must be an absolute http(s) URL');

const httpsUrl = z.string().refine((s) => {
  try { return new URL(s).protocol === 'https:'; } catch { return false; }
}, 'must be an absolute https URL');

const appUrl = httpUrl
  .refine((s) => { const u = new URL(s); return (u.pathname === '/' || u.pathname === '') && u.search === '' && u.hash === ''; },
    'must have no path, query or fragment')
  .refine((s) => new URL(s).protocol === 'https:' || isLocalUrl(s), 'must use https:// (http:// only for localhost or 127.0.0.1)')
  .transform((s) => s.replace(/\/+$/, ''));

const emailList = z.string()
  .transform((s) => [...new Set(s.split(',').map((e) => e.trim().toLowerCase()).filter(Boolean))])
  .pipe(z.array(z.email({ error: 'contains an invalid email address' })));

const shared = {
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  APP_URL: appUrl,
  DATABASE_URL: z.string().regex(/^postgres(ql)?:\/\//, 'must start with postgres:// or postgresql://'),
  S3_ENDPOINT: httpUrl.optional(),
  S3_REGION: z.string().regex(/^[a-z0-9-]{1,32}$/, 'must be a region id').default('us-east-1'),
  S3_BUCKET: z.string().regex(/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/, 'must be a valid bucket name'),
  S3_ACCESS_KEY_ID: z.string().optional(),
  S3_SECRET_ACCESS_KEY: z.string().optional(),
  S3_FORCE_PATH_STYLE: boolVar.default(false),
  AI_PROVIDER: z.enum(['anthropic', 'fake']).default('anthropic'),
  SMTP_HOST: z.string().min(1),
  SMTP_PORT: intVar(1, 65535).default(587),
  SMTP_SECURE: boolVar.default(false),
  SMTP_USER: z.string().optional(),
  SMTP_PASSWORD: z.string().optional(),
  EMAIL_FROM: z.string().optional(),
  ACCESS_MODE: z.enum(['allowlist', 'open']).default('allowlist'),
  ALLOWED_EMAILS: emailList.default([]),
  RETENTION_DAYS: intVar(30, 3650).default(365),
  LOG_LEVEL: z.enum(['fatal', 'error', 'warn', 'info', 'debug', 'trace']).default('info'),
};

const webOnly = {
  PORT: intVar(1, 65535).default(3000),
  TRUST_PROXY: boolVar.default(false),
  PRIVACY_NOTICE_URL: httpsUrl.optional(),
  AI_DAILY_LIMIT_PER_ACCOUNT: intVar(1, 1000).default(30),
  AI_DAILY_LIMIT_PER_PROPERTY: intVar(1, 100).default(3),
  AI_DAILY_LIMIT_GLOBAL: intVar(1, 100_000).default(500),
  EXPORT_DAILY_LIMIT_PER_ACCOUNT: intVar(1, 1000).default(50),
  PROPERTY_LIMIT_PER_ACCOUNT: intVar(1, 10000).default(500),
  MAGIC_LINK_LIMIT_PER_EMAIL_PER_HOUR: intVar(1, 100).default(5),
  MAGIC_LINK_LIMIT_PER_IP_PER_HOUR: intVar(1, 1000).default(20),
  MAX_UPLOAD_BYTES: intVar(1_048_576, 20_971_520).default(20_971_520),
  SKETCH_MIN_SHORT_SIDE_PX: intVar(100, 4000).default(600),
  SKETCH_MAX_LONG_SIDE_PX: intVar(1000, 20000).default(12000),
  SKETCH_MAX_MEGAPIXELS: intVar(1, 50).default(50),
};

const workerOnly = {
  ANTHROPIC_API_KEY: z.string().min(20, 'must be an Anthropic API key (at least 20 characters)').optional(),
  AI_MODEL: z.string().regex(/^[a-z0-9][a-z0-9.\-]{2,99}$/, 'must be a model id').default('claude-sonnet-5-5'),
  AI_TIMEOUT_MS: intVar(10_000, 270_000).default(120_000),
  WORKER_CONCURRENCY_READ: intVar(1, 16).default(2),
  WORKER_CONCURRENCY_EXPORT: intVar(1, 8).default(2),
};

const SharedSchema = z.object(shared);
type Ctx = z.RefinementCtx;
type SharedConfig = z.infer<typeof SharedSchema>;

function sharedChecks(c: SharedConfig, ctx: Ctx) {
  const issue = (path: string, message: string) => ctx.addIssue({ code: 'custom', path: [path], message });
  const pair = (a: string | undefined, b: string | undefined, names: [string, string]) => {
    if ((a === undefined) !== (b === undefined))
      issue(names[0], `${names[0]} and ${names[1]} must be set together or both left unset`);
  };
  const localApp = isLocalUrl(c.APP_URL);
  pair(c.S3_ACCESS_KEY_ID, c.S3_SECRET_ACCESS_KEY, ['S3_ACCESS_KEY_ID', 'S3_SECRET_ACCESS_KEY']);
  pair(c.SMTP_USER, c.SMTP_PASSWORD, ['SMTP_USER', 'SMTP_PASSWORD']);
  if (c.S3_ENDPOINT?.startsWith('http://') && !localApp)
    issue('S3_ENDPOINT', 'must use https:// unless APP_URL is a localhost URL');
  if (c.EMAIL_FROM !== undefined && !isValidMailbox(c.EMAIL_FROM))
    issue('EMAIL_FROM', 'must be "Name <address>" or a bare email address');
  if (c.ACCESS_MODE === 'allowlist' && c.ALLOWED_EMAILS.length === 0)
    issue('ALLOWED_EMAILS', 'must list at least one email when ACCESS_MODE=allowlist');
  if (c.AI_PROVIDER === 'fake' && !localApp)
    issue('AI_PROVIDER', 'fake is allowed only when APP_URL is a localhost URL');
  if (c.NODE_ENV === 'production' && c.RETENTION_DAYS !== 365)
    issue('RETENTION_DAYS', 'must be 365 in production');
}

export const WebConfigSchema = z.object({ ...shared, ...webOnly }).superRefine((c, ctx) => {
  sharedChecks(c, ctx);
  if (c.NODE_ENV === 'production' && !c.TRUST_PROXY)
    ctx.addIssue({ code: 'custom', path: ['TRUST_PROXY'], message: 'must be true in production (the app runs behind the reverse proxy)' });
  if (c.SKETCH_MAX_LONG_SIDE_PX <= c.SKETCH_MIN_SHORT_SIDE_PX)
    ctx.addIssue({ code: 'custom', path: ['SKETCH_MAX_LONG_SIDE_PX'], message: 'must be greater than SKETCH_MIN_SHORT_SIDE_PX' });
});

export const WorkerConfigSchema = z.object({ ...shared, ...workerOnly }).superRefine((c, ctx) => {
  sharedChecks(c, ctx);
  if (c.AI_PROVIDER === 'anthropic' && c.ANTHROPIC_API_KEY === undefined)
    ctx.addIssue({ code: 'custom', path: ['ANTHROPIC_API_KEY'], message: 'must be set when AI_PROVIDER=anthropic' });
});

type Derived = { IS_LOCAL_APP_URL: boolean; EMAIL_FROM_RESOLVED: string };
export type WebConfig = z.infer<typeof WebConfigSchema> & Derived;
export type WorkerConfig = z.infer<typeof WorkerConfigSchema> & Derived;

/** Parses env for one process. On failure: prints every problem (names and reasons, never values) and exits 1. */
export function loadConfig(role: 'web', env?: Env): WebConfig;
export function loadConfig(role: 'worker', env?: Env): WorkerConfig;
export function loadConfig(role: ProcessRole, env: Env = process.env): WebConfig | WorkerConfig {
  const schema = role === 'web' ? WebConfigSchema : WorkerConfigSchema;
  const result = schema.safeParse(cleanEnv(env));
  if (!result.success) {
    const lines = result.error.issues.map((i) => `  - ${i.path.join('.') || '(config)'}: ${i.message}`);
    process.stderr.write(
      `Invalid configuration for the ${role} process:\n${lines.join('\n')}\n` +
      `Fix the environment variables above (see .env.example) and start again.\n`,
    );
    process.exit(1);
  }
  const c = result.data;
  const host = new URL(c.APP_URL).hostname;
  return {
    ...c,
    IS_LOCAL_APP_URL: LOCAL_HOSTNAMES.has(host),
    EMAIL_FROM_RESOLVED: c.EMAIL_FROM ?? `${PRODUCT_NAME} <no-reply@${host}>`,
  };
}

let webConfig: WebConfig | null = null;
/** Called once by src/instrumentation.ts; safe to call again. */
export function initWebConfig(): WebConfig { webConfig ??= loadConfig('web'); return webConfig; }
/** The only way web code reads configuration. */
export function getWebConfig(): WebConfig { return webConfig ?? initWebConfig(); }

isValidMailbox(s) is a small function in the same file. It accepts ^[^<>"\r\n]+ <address>$ or a bare address, and validates the address part with z.email().

Boot rules:

1. web: src/instrumentation.ts register() returns immediately unless process.env.NEXT_RUNTIME === 'nodejs'. Otherwise it calls initWebConfig(), which runs loadConfig('web') once and stores the result. Web code reads configuration only through getWebConfig(), which returns that stored result and runs initWebConfig() first if it has not run yet. A configuration error therefore stops the server at start, before it accepts any request.
2. worker: the first statement in src/worker/index.ts is const config = loadConfig('worker');. Nothing else (logger, database, pg-boss) starts before it. The worker passes config (or the parts a module needs) down to handlers and services explicitly; no worker module imports getWebConfig() or reads the environment itself.
3. One-shot entrypoints: scripts/migrate.ts, scripts/storage-init.ts, src/server/ops/cli.ts and scripts/seed-dev.ts call loadConfig('worker') first, exactly like the worker.
4. Build time: next build does not load the configuration. All pages are dynamic (Section 3.4.3), and no module reads configuration at import time. Modules read configuration inside functions.
5. Messages: one line per invalid variable, giving the variable name and the reason. Values are never printed, including for non-secret variables, so the rule stays simple.
6. Exit: exit code 1. The logger is not used for this message, because it is not configured yet. The message goes to stderr as plain text.
7. Tests: loadConfig takes an env object, so unit tests pass their own. Integration, visual and E2E-support code loads the committed .env.test (Section 17.3.1): NODE_ENV=test, local Postgres and MinIO, Mailpit SMTP and AI_PROVIDER=fake, so no real model is ever called and no real key is needed.
8. .env.example lists every variable in Section 4.9.1 in table order, with a one-line comment each and safe local values (APP_URL=http://localhost:3000, S3_ENDPOINT=http://localhost:9000, S3_FORCE_PATH_STYLE=true, S3_BUCKET=floorplans, SMTP_HOST=localhost, SMTP_PORT=1025, AI_PROVIDER=fake, ACCESS_MODE=allowlist, ALLOWED_EMAILS=agent@example.com, NEXT_TELEMETRY_DISABLED=1). npm run check:env-example fails when its variable names differ from the keys of WebConfigSchema and WorkerConfigSchema together (plus NEXT_TELEMETRY_DISABLED). Real secrets are never committed. .env is git-ignored.

4.10 Accessibility baseline (all non-canvas UI) #

This baseline covers every page and component except the editor's drawing canvas. The editor's own accessibility rules, including keyboard alternatives for canvas operations and the scoping of single-key shortcuts, are in Section 10.

4.11 Git and commit conventions #

4.12 DECISIONS.md #

DECISIONS.md at the repository root is the decision log. Section 20 owns the process for using it. This section fixes its purpose and its single entry format.

When to write an entry. Write one whenever the builder:

1. uses an answer or a default from Section 1.2 (entries D-001 to D-015, one per question in question order, written before coding starts);
2. chooses anything this specification leaves to the implementation: a library detail, an internal data shape, a UI micro-copy gap, or a tolerance not stated here;
3. deviates from this specification because something does not work as written (a library change, a platform limit). The entry must name the section and say what was done instead;
4. adds a dependency not in Section 3.1, changes a dependency's major line, pins a 0.x minor line or a container image tag (Section 3.1), or adopts the TypeScript or ESLint upgrades described in Section 3.1.3.

Entry format (one ### heading per entry, append-only, newest at the bottom, never renumber). Every entry has exactly these fields, in this order:

### D-016 — Move ESLint to the 10.x line
- Date: 2026-11-03
- Milestone: M0                # the milestone being worked on (Section 19)
- Source: builder              # operator | default | builder
- Spec section: 3.1.3
- Decision: eslint and @eslint/js moved to 10.x because eslint-plugin-react and eslint-plugin-jsx-a11y now list ESLint 10 in their peer ranges.
- Rationale: Section 3.1.3 says to move once both plugins support it.
- Alternatives considered: stay on 9.x (rejected: the condition in Section 3.1.3 is met).

Rules:

• An entry never contradicts the fixed constraints in Section 1.3 or the out-of-scope list in Section 2.8.
• If a later decision replaces an earlier one, add a new entry that says Supersedes D-0NN. Old entries are never edited or deleted.
• Code that relies on an entry cites it in a comment: // DECISIONS D-016.

5. Data Model & Storage #

This section is the canonical definition of every database table, every enum, the PlanDocument and ReviewFlag schemas, the object storage layout and the data-retention rules. Where another section mentions a column, a key, a numeric range or a document field, this section wins.

5.1 Storage principles #

5.2 Enumerated types #

All enums are Postgres enum types. New values are added only by appending (ALTER TYPE … ADD VALUE), never by renaming or removing.

The UI-level export states are queued, rendering, sending, sent, render_failed and email_failed. They are derived from exports.status + exports.email_status; the derivation is owned by Section 12.

5.3 Table reference #

Every table below is given as a column reference (meaning and rules). The Drizzle definition (5.4) and the SQL DDL (5.5) express exactly the same columns, constraints and indexes. The Drizzle schema is the source of truth for migrations.

5.3.1 accounts #

One row per person. Created on the first successful magic-link verification (Section 6).

Indexes: unique accounts_email_key (email).

5.3.2 magic_link_tokens #

One row per sign-in link issued. Rows exist only for emails that were allowed at the time of the request (Section 6). Not linked to accounts by FK, because the account may not exist yet.

Indexes: unique magic_link_tokens_token_hash_key (token_hash); magic_link_tokens_email_idx (email); magic_link_tokens_expires_at_idx (expires_at) (cleanup, 5.13.4).

5.3.3 sessions #

Indexes: unique sessions_token_hash_key (token_hash); sessions_account_id_idx (account_id); sessions_expires_at_idx (expires_at).

No user agent or IP address is stored on sessions (data minimisation, Section 15). The table has no updated_at (5.1).

5.3.4 properties #

Indexes:

• properties_account_updated_idx (account_id, updated_at DESC, id DESC) — dashboard list and cursor pagination (Section 13).
• properties_last_activity_idx (last_activity_at) — purge scan.
• properties_current_sketch_idx (current_sketch_id) — makes the ON DELETE SET NULL from sketches an index lookup.

Title search is title ILIKE '%' || $q || '%' (with %, _ and \ in $q escaped) inside account_id = $accountId. No trigram index: one account holds at most PROPERTY_LIMIT_PER_ACCOUNT (default 500) properties, so the account index bounds the scan.

5.3.5 sketches #

One row per uploaded JPG. A property normally has one sketch; during a replacement it briefly has two (the current one and the new one being read). Section 7 owns when the old one is deleted.

Indexes: sketches_property_idx (property_id, created_at DESC); sketches_account_idx (account_id); unique sketches_original_key_key (original_key); unique sketches_ai_key_key (ai_key).

The original filename is not stored (data minimisation: it often contains a client's address). The download filename is always <slug>-sketch.jpg, where the slug follows the Section 12 slug rule applied to the property title (fallback property-<first 8 hex of the property id>).

5.3.6 sketch_readings #

One row per AI run (a "Reading"). Pipeline semantics are owned by Section 8.

Table checks:

• status = 'succeeded' ⇒ finished_at IS NOT NULL AND error_code IS NULL.
• status = 'failed' ⇒ finished_at IS NOT NULL AND error_code IS NOT NULL.
• status IN ('queued','running') ⇒ finished_at IS NULL.
• stage IS NULL OR status = 'running'.

Indexes:

• sketch_readings_property_idx (property_id, created_at DESC) — "latest reading" lookups.
• sketch_readings_account_idx (account_id, created_at DESC).
• sketch_readings_sketch_idx (sketch_id).
• Partial unique sketch_readings_one_active_idx (property_id) WHERE status IN ('queued','running') — at most one active reading per property; a second insert fails and maps to invalid_state (Section 13).
• Partial sketch_readings_active_created_idx (created_at) WHERE status IN ('queued','running') — the stale-reading rule of maintenance.cleanup (created_at < now() − 10 min, Section 16) and the ReadingDto.stale flag.

5.3.7 plan_documents #

Exactly one row per property once a plan exists.

Indexes: unique plan_documents_property_key (property_id); plan_documents_reading_idx (reading_id); plan_documents_source_sketch_idx (source_sketch_id).

Write rule used by the plan PUT (body { revision, document, reviewFlags }, Section 13). The service parses the document with parsePlanDocument(body.document, 'write'), prunes the flags with pruneReviewFlags, and runs, in one transaction:

UPDATE plan_documents
   SET document = $doc, review_flags = $prunedFlags, revision = revision + 1, updated_at = now()
 WHERE property_id = $propertyId AND revision = $expectedRevision
RETURNING revision;
-- 0 rows → 409 revision_conflict (after confirming the row exists; if it does not → 404 not_found)

UPDATE properties SET display_unit = $doc.displayUnit WHERE id = $propertyId;  -- I6
-- then touchProperty(tx, propertyId, { edited: true })                         -- 5.13.2

document.title is not copied to properties.title (5.7). The editor never calls PATCH /api/v1/properties/{propertyId}.

5.3.8 exports #

One row per render of a PlanDocument revision into PDF + PNG + JPG. Flow and state machine owned by Section 12.

Table checks:

• status = 'rendered' ⇒ rendered_at IS NOT NULL.
• status = 'failed' ⇒ error_code IS NOT NULL.
• email_status <> 'not_sent' ⇒ status = 'rendered'.
• email_status = 'sent' ⇒ email_sent_at IS NOT NULL.

Indexes:

• exports_property_idx (property_id, created_at DESC, id DESC) — exports list per property.
• exports_account_idx (account_id, created_at DESC).
• Partial unique exports_one_active_idx (property_id) WHERE status IN ('queued','rendering') — enforces the one-active-export-per-property rule of Section 12; a conflicting insert maps to invalid_state.

The daily export allowance is counted in rate_limits (15.7), not from this table. Creating an export changes properties.last_activity_at only, never properties.updated_at (5.13.2).

5.3.9 export_files #

Checks: (format = 'pdf') = (width_px IS NULL) and (format = 'pdf') = (height_px IS NULL).

Indexes: unique export_files_export_format_key (export_id, format); unique export_files_object_key_key (object_key).

Re-running a render (job retry) upserts on (export_id, format). Every insert supplies format, object_key, content_type, byte_size and, for PNG/JPG, width_px/height_px.

5.3.10 rate_limits #

DECISION: a fixed-window counters table rate_limits(key, window_start, count) is the single mechanism for every rate limit and every quota: request-frequency limits, AI reading allowances (per account, per property and deployment-wide) and the daily export allowance. Rationale: no extra infrastructure (no Redis), counters live in the same transaction as the action they guard (a rolled-back action rolls back its count), and rows are tiny and short-lived. Rolling 24-hour quotas are computed by summing the last 24 hourly windows (accuracy within one hour). The property cap is counted from properties, and the email resend cap from exports.email_resend_count. The limits themselves, the key formats, the consume algorithm and the refund rule are canonical in Section 15.7.

Primary key (key, window_start). Index rate_limits_window_idx (window_start) for cleanup (rows whose window_start is older than 25 hours are deleted by maintenance.cleanup, 5.13.4).

Keys never contain a raw email address or raw IP address; those are SHA-256 hashed first (Section 15).

5.4 Drizzle definitions #

File: src/server/db/schema/index.ts. This is the file drizzle-kit reads (5.8). It may be split into per-area files that index.ts re-exports; the definitions below are normative either way.

// src/server/db/schema/index.ts
import { sql } from 'drizzle-orm';
import {
  type AnyPgColumn,
  bigint,
  check,
  index,
  integer,
  jsonb,
  pgEnum,
  pgTable,
  primaryKey,
  text,
  timestamp,
  uniqueIndex,
  uuid,
} from 'drizzle-orm/pg-core';
import type { PlanDocument } from '@/plan/schema/planDocument';
import type { ReviewFlag } from '@/plan/schema/reviewFlags';

// ---------- helpers ----------
const tsz = (name: string) => timestamp(name, { withTimezone: true, mode: 'date' });
const createdAt = () => tsz('created_at').notNull().defaultNow();
const updatedAt = () =>
  tsz('updated_at').notNull().defaultNow().$onUpdate(() => new Date());

const HEX64 = sql.raw(`'^[0-9a-f]{64}$'`);
const ERROR_CODE = sql.raw(`'^[a-z][a-z0-9_]{0,63}$'`);

// ---------- enums ----------
export const displayUnitEnum = pgEnum('display_unit', ['metric', 'imperial']);
export const propertyStatusEnum = pgEnum('property_status', ['draft', 'reading', 'ready', 'reading_failed']);
export const readingStatusEnum = pgEnum('reading_status', ['queued', 'running', 'succeeded', 'failed']);
export const readingStageEnum = pgEnum('reading_stage', ['preparing', 'reading', 'building']);
export const readingTriggerEnum = pgEnum('reading_trigger', ['upload', 'retry']);
export const planSourceEnum = pgEnum('plan_source', ['ai', 'blank']);
export const exportStatusEnum = pgEnum('export_status', ['queued', 'rendering', 'rendered', 'failed']);
export const emailStatusEnum = pgEnum('email_status', ['not_sent', 'sending', 'sent', 'failed']);
export const emailAttachmentModeEnum = pgEnum('email_attachment_mode', ['all', 'pdf_only', 'none']);
export const exportFormatEnum = pgEnum('export_format', ['pdf', 'png', 'jpg']);
export const pageSizeEnum = pgEnum('page_size', ['A4', 'A3']);
export const pageOrientationEnum = pgEnum('page_orientation', ['landscape', 'portrait']);

// ---------- accounts ----------
export const accounts = pgTable(
  'accounts',
  {
    id: uuid('id').primaryKey(),
    email: text('email').notNull(),
    defaultDisplayUnit: displayUnitEnum('default_display_unit').notNull().default('metric'),
    lastSignInAt: tsz('last_sign_in_at'),
    createdAt: createdAt(),
    updatedAt: updatedAt(),
  },
  (t) => [
    uniqueIndex('accounts_email_key').on(t.email),
    check(
      'accounts_email_normalised',
      sql`${t.email} = lower(btrim(${t.email})) AND char_length(${t.email}) BETWEEN 3 AND 254 AND position('@' in ${t.email}) > 1`,
    ),
  ],
);

// ---------- magic_link_tokens ----------
export const magicLinkTokens = pgTable(
  'magic_link_tokens',
  {
    id: uuid('id').primaryKey(),
    email: text('email').notNull(),
    tokenHash: text('token_hash').notNull(),
    redirectPath: text('redirect_path'),
    expiresAt: tsz('expires_at').notNull(),
    usedAt: tsz('used_at'),
    createdAt: createdAt(),
  },
  (t) => [
    uniqueIndex('magic_link_tokens_token_hash_key').on(t.tokenHash),
    index('magic_link_tokens_email_idx').on(t.email),
    index('magic_link_tokens_expires_at_idx').on(t.expiresAt),
    check('magic_link_tokens_token_hash_hex', sql`${t.tokenHash} ~ ${HEX64}`),
    check(
      'magic_link_tokens_email_normalised',
      sql`${t.email} = lower(btrim(${t.email})) AND char_length(${t.email}) BETWEEN 3 AND 254`,
    ),
    check(
      'magic_link_tokens_redirect_path_valid',
      sql`${t.redirectPath} IS NULL OR (char_length(${t.redirectPath}) <= 200 AND left(${t.redirectPath}, 1) = '/' AND left(${t.redirectPath}, 2) <> '//')`,
    ),
  ],
);

// ---------- sessions ----------
export const sessions = pgTable(
  'sessions',
  {
    id: uuid('id').primaryKey(),
    accountId: uuid('account_id').notNull().references(() => accounts.id, { onDelete: 'cascade' }),
    tokenHash: text('token_hash').notNull(),
    expiresAt: tsz('expires_at').notNull(),
    lastSeenAt: tsz('last_seen_at').notNull().defaultNow(),
    createdAt: createdAt(),
  },
  (t) => [
    uniqueIndex('sessions_token_hash_key').on(t.tokenHash),
    index('sessions_account_id_idx').on(t.accountId),
    index('sessions_expires_at_idx').on(t.expiresAt),
    check('sessions_token_hash_hex', sql`${t.tokenHash} ~ ${HEX64}`),
  ],
);

// ---------- properties ----------
export const properties = pgTable(
  'properties',
  {
    id: uuid('id').primaryKey(),
    accountId: uuid('account_id').notNull().references(() => accounts.id, { onDelete: 'cascade' }),
    title: text('title').notNull().default(''),
    status: propertyStatusEnum('status').notNull().default('draft'),
    displayUnit: displayUnitEnum('display_unit').notNull(),
    currentSketchId: uuid('current_sketch_id').references((): AnyPgColumn => sketches.id, {
      onDelete: 'set null',
    }),
    thumbnailUpdatedAt: tsz('thumbnail_updated_at'),
    lastActivityAt: tsz('last_activity_at').notNull().defaultNow(),
    createdAt: createdAt(),
    updatedAt: updatedAt(),
  },
  (t) => [
    index('properties_account_updated_idx').on(t.accountId, t.updatedAt.desc(), t.id.desc()),
    index('properties_last_activity_idx').on(t.lastActivityAt),
    index('properties_current_sketch_idx').on(t.currentSketchId),
    check('properties_title_length', sql`char_length(${t.title}) <= 120`),
  ],
);

// ---------- sketches ----------
export const sketches = pgTable(
  'sketches',
  {
    id: uuid('id').primaryKey(),
    propertyId: uuid('property_id').notNull().references(() => properties.id, { onDelete: 'cascade' }),
    accountId: uuid('account_id').notNull().references(() => accounts.id, { onDelete: 'cascade' }),
    originalKey: text('original_key').notNull(),
    aiKey: text('ai_key'),
    mimeType: text('mime_type').notNull().default('image/jpeg'),
    byteSize: bigint('byte_size', { mode: 'number' }).notNull(),
    widthPx: integer('width_px').notNull(),
    heightPx: integer('height_px').notNull(),
    aiWidthPx: integer('ai_width_px'),
    aiHeightPx: integer('ai_height_px'),
    sha256: text('sha256').notNull(),
    createdAt: createdAt(),
    updatedAt: updatedAt(),
  },
  (t) => [
    index('sketches_property_idx').on(t.propertyId, t.createdAt.desc()),
    index('sketches_account_idx').on(t.accountId),
    uniqueIndex('sketches_original_key_key').on(t.originalKey),
    uniqueIndex('sketches_ai_key_key').on(t.aiKey),
    check('sketches_mime_jpeg', sql`${t.mimeType} = 'image/jpeg'`),
    check('sketches_byte_size_positive', sql`${t.byteSize} > 0`),
    check('sketches_dims_positive', sql`${t.widthPx} > 0 AND ${t.heightPx} > 0`),
    check(
      'sketches_ai_dims_positive',
      sql`(${t.aiWidthPx} IS NULL OR ${t.aiWidthPx} > 0) AND (${t.aiHeightPx} IS NULL OR ${t.aiHeightPx} > 0)`,
    ),
    check('sketches_sha256_hex', sql`${t.sha256} ~ ${HEX64}`),
  ],
);

// ---------- sketch_readings ----------
export const sketchReadings = pgTable(
  'sketch_readings',
  {
    id: uuid('id').primaryKey(),
    propertyId: uuid('property_id').notNull().references(() => properties.id, { onDelete: 'cascade' }),
    sketchId: uuid('sketch_id').notNull().references(() => sketches.id, { onDelete: 'cascade' }),
    accountId: uuid('account_id').notNull().references(() => accounts.id, { onDelete: 'cascade' }),
    trigger: readingTriggerEnum('trigger').notNull(),
    status: readingStatusEnum('status').notNull().default('queued'),
    stage: readingStageEnum('stage'),
    attemptCount: integer('attempt_count').notNull().default(0),
    modelCalls: integer('model_calls').notNull().default(0),
    modelId: text('model_id'),
    inputTokens: integer('input_tokens').notNull().default(0),
    outputTokens: integer('output_tokens').notNull().default(0),
    durationMs: integer('duration_ms'),
    qualityWarnings: text('quality_warnings').array().notNull().default(sql`'{}'::text[]`),
    rawResponse: jsonb('raw_response').$type<unknown>(),
    errorCode: text('error_code'),
    errorMessage: text('error_message'),
    startedAt: tsz('started_at'),
    finishedAt: tsz('finished_at'),
    createdAt: createdAt(),
    updatedAt: updatedAt(),
  },
  (t) => [
    index('sketch_readings_property_idx').on(t.propertyId, t.createdAt.desc()),
    index('sketch_readings_account_idx').on(t.accountId, t.createdAt.desc()),
    index('sketch_readings_sketch_idx').on(t.sketchId),
    uniqueIndex('sketch_readings_one_active_idx')
      .on(t.propertyId)
      .where(sql`${t.status} IN ('queued', 'running')`),
    index('sketch_readings_active_created_idx')
      .on(t.createdAt)
      .where(sql`${t.status} IN ('queued', 'running')`),
    check(
      'sketch_readings_counters_non_negative',
      sql`${t.attemptCount} >= 0 AND ${t.modelCalls} >= 0 AND ${t.inputTokens} >= 0 AND ${t.outputTokens} >= 0 AND (${t.durationMs} IS NULL OR ${t.durationMs} >= 0)`,
    ),
    check('sketch_readings_model_id_length', sql`${t.modelId} IS NULL OR char_length(${t.modelId}) <= 100`),
    check('sketch_readings_error_code_format', sql`${t.errorCode} IS NULL OR ${t.errorCode} ~ ${ERROR_CODE}`),
    check(
      'sketch_readings_error_message_length',
      sql`${t.errorMessage} IS NULL OR char_length(${t.errorMessage}) <= 2000`,
    ),
    check(
      'sketch_readings_quality_warnings_known',
      sql`${t.qualityWarnings} <@ ARRAY['image_dark', 'image_low_contrast', 'image_small']::text[]`,
    ),
    check('sketch_readings_stage_only_running', sql`${t.stage} IS NULL OR ${t.status} = 'running'`),
    check(
      'sketch_readings_status_consistency',
      sql`(${t.status} = 'succeeded' AND ${t.finishedAt} IS NOT NULL AND ${t.errorCode} IS NULL)
       OR (${t.status} = 'failed' AND ${t.finishedAt} IS NOT NULL AND ${t.errorCode} IS NOT NULL)
       OR (${t.status} IN ('queued', 'running') AND ${t.finishedAt} IS NULL)`,
    ),
  ],
);

// ---------- plan_documents ----------
export const planDocuments = pgTable(
  'plan_documents',
  {
    id: uuid('id').primaryKey(),
    propertyId: uuid('property_id').notNull().references(() => properties.id, { onDelete: 'cascade' }),
    document: jsonb('document').$type<PlanDocument>().notNull(),
    revision: integer('revision').notNull().default(1),
    reviewFlags: jsonb('review_flags').$type<ReviewFlag[]>().notNull().default(sql`'[]'::jsonb`),
    source: planSourceEnum('source').notNull(),
    readingId: uuid('reading_id').references(() => sketchReadings.id, { onDelete: 'set null' }),
    sourceSketchId: uuid('source_sketch_id').references(() => sketches.id, { onDelete: 'set null' }),
    createdAt: createdAt(),
    updatedAt: updatedAt(),
  },
  (t) => [
    uniqueIndex('plan_documents_property_key').on(t.propertyId),
    index('plan_documents_reading_idx').on(t.readingId),
    index('plan_documents_source_sketch_idx').on(t.sourceSketchId),
    check('plan_documents_revision_positive', sql`${t.revision} >= 1`),
    check(
      'plan_documents_document_object',
      sql`jsonb_typeof(${t.document}) = 'object' AND ${t.document} ? 'schemaVersion'`,
    ),
    check('plan_documents_review_flags_array', sql`jsonb_typeof(${t.reviewFlags}) = 'array'`),
  ],
);

// ---------- exports ----------
export const exportsTable = pgTable(
  'exports',
  {
    id: uuid('id').primaryKey(),
    propertyId: uuid('property_id').notNull().references(() => properties.id, { onDelete: 'cascade' }),
    accountId: uuid('account_id').notNull().references(() => accounts.id, { onDelete: 'cascade' }),
    planRevision: integer('plan_revision').notNull(),
    documentSnapshot: jsonb('document_snapshot').$type<PlanDocument>().notNull(),
    title: text('title').notNull().default(''),
    pageSize: pageSizeEnum('page_size').notNull(),
    pageOrientation: pageOrientationEnum('page_orientation').notNull(),
    slug: text('slug').notNull(),
    status: exportStatusEnum('status').notNull().default('queued'),
    errorCode: text('error_code'),
    errorMessage: text('error_message'),
    renderAttempts: integer('render_attempts').notNull().default(0),
    renderStartedAt: tsz('render_started_at'),
    renderedAt: tsz('rendered_at'),
    emailStatus: emailStatusEnum('email_status').notNull().default('not_sent'),
    emailAttempts: integer('email_attempts').notNull().default(0),
    emailNextAttemptAt: tsz('email_next_attempt_at'),
    emailAttachmentMode: emailAttachmentModeEnum('email_attachment_mode'),
    emailResendCount: integer('email_resend_count').notNull().default(0),
    emailErrorCode: text('email_error_code'),
    emailErrorMessage: text('email_error_message'),
    emailSentAt: tsz('email_sent_at'),
    createdAt: createdAt(),
    updatedAt: updatedAt(),
  },
  (t) => [
    index('exports_property_idx').on(t.propertyId, t.createdAt.desc(), t.id.desc()),
    index('exports_account_idx').on(t.accountId, t.createdAt.desc()),
    uniqueIndex('exports_one_active_idx')
      .on(t.propertyId)
      .where(sql`${t.status} IN ('queued', 'rendering')`),
    check('exports_plan_revision_positive', sql`${t.planRevision} >= 1`),
    check('exports_snapshot_object', sql`jsonb_typeof(${t.documentSnapshot}) = 'object'`),
    check('exports_title_length', sql`char_length(${t.title}) <= 120`),
    check(
      'exports_slug_format',
      sql`${t.slug} ~ '^[a-z0-9]+(-[a-z0-9]+)*$' AND char_length(${t.slug}) <= 60`,
    ),
    check(
      'exports_counters_valid',
      sql`${t.renderAttempts} >= 0 AND ${t.emailAttempts} >= 0 AND ${t.emailResendCount} BETWEEN 0 AND 5`,
    ),
    check('exports_error_code_format', sql`${t.errorCode} IS NULL OR ${t.errorCode} ~ ${ERROR_CODE}`),
    check(
      'exports_email_error_code_format',
      sql`${t.emailErrorCode} IS NULL OR ${t.emailErrorCode} ~ ${ERROR_CODE}`,
    ),
    check(
      'exports_messages_length',
      sql`(${t.errorMessage} IS NULL OR char_length(${t.errorMessage}) <= 2000) AND (${t.emailErrorMessage} IS NULL OR char_length(${t.emailErrorMessage}) <= 2000)`,
    ),
    check('exports_rendered_has_time', sql`${t.status} <> 'rendered' OR ${t.renderedAt} IS NOT NULL`),
    check('exports_failed_has_code', sql`${t.status} <> 'failed' OR ${t.errorCode} IS NOT NULL`),
    check('exports_email_requires_render', sql`${t.emailStatus} = 'not_sent' OR ${t.status} = 'rendered'`),
    check('exports_sent_has_time', sql`${t.emailStatus} <> 'sent' OR ${t.emailSentAt} IS NOT NULL`),
  ],
);

// ---------- export_files ----------
export const exportFiles = pgTable(
  'export_files',
  {
    id: uuid('id').primaryKey(),
    exportId: uuid('export_id').notNull().references(() => exportsTable.id, { onDelete: 'cascade' }),
    format: exportFormatEnum('format').notNull(),
    objectKey: text('object_key').notNull(),
    contentType: text('content_type').notNull(),
    byteSize: bigint('byte_size', { mode: 'number' }).notNull(),
    widthPx: integer('width_px'),
    heightPx: integer('height_px'),
    createdAt: createdAt(),
  },
  (t) => [
    uniqueIndex('export_files_export_format_key').on(t.exportId, t.format),
    uniqueIndex('export_files_object_key_key').on(t.objectKey),
    check(
      'export_files_content_type_matches',
      sql`(${t.format} = 'pdf' AND ${t.contentType} = 'application/pdf')
       OR (${t.format} = 'png' AND ${t.contentType} = 'image/png')
       OR (${t.format} = 'jpg' AND ${t.contentType} = 'image/jpeg')`,
    ),
    check('export_files_byte_size_positive', sql`${t.byteSize} > 0`),
    check(
      'export_files_dims_by_format',
      sql`((${t.format} = 'pdf') = (${t.widthPx} IS NULL)) AND ((${t.format} = 'pdf') = (${t.heightPx} IS NULL))
       AND (${t.widthPx} IS NULL OR ${t.widthPx} > 0) AND (${t.heightPx} IS NULL OR ${t.heightPx} > 0)`,
    ),
  ],
);

// ---------- rate_limits ----------
export const rateLimits = pgTable(
  'rate_limits',
  {
    key: text('key').notNull(),
    windowStart: tsz('window_start').notNull(),
    count: integer('count').notNull().default(0),
  },
  (t) => [
    primaryKey({ columns: [t.key, t.windowStart], name: 'rate_limits_pkey' }),
    index('rate_limits_window_idx').on(t.windowStart),
    check('rate_limits_key_length', sql`char_length(${t.key}) BETWEEN 1 AND 200`),
    check('rate_limits_count_non_negative', sql`${t.count} >= 0`),
  ],
);

// ---------- inferred row types ----------
export type AccountRow = typeof accounts.$inferSelect;
export type MagicLinkTokenRow = typeof magicLinkTokens.$inferSelect;
export type SessionRow = typeof sessions.$inferSelect;
export type PropertyRow = typeof properties.$inferSelect;
export type SketchRow = typeof sketches.$inferSelect;
export type SketchReadingRow = typeof sketchReadings.$inferSelect;
export type PlanDocumentRow = typeof planDocuments.$inferSelect;
export type ExportRow = typeof exportsTable.$inferSelect;
export type ExportFileRow = typeof exportFiles.$inferSelect;