All-in-One Online Form Builder Platform

Formcraft - All-in-One Online Form Builder Platform #

A complete, executable product specification.

Formcraft is an all-in-one online form builder that replaces Tally, Fillout, and Cognito Forms. It pairs a drag-and-drop builder covering every field type with a deep conditional-logic and calculation engine, AI form generation from a plain-text prompt, anonymous partial-submission capture, a full integration and webhook delivery pipeline, in-form Stripe payments, custom domains with automatic TLS, and workspace-scoped team collaboration.

This document specifies that product completely enough to be built without further clarification. Every field type, validation rule, API endpoint, database column, permission, plan limit, error code, and failure mode is defined. Where a decision could reasonably go more than one way, the decision has been made and recorded rather than deferred - there are no open questions and no placeholders. Each concern has exactly one owning section; every other section references it by number.

Read Section 29 first if you are the engineer or agent implementing this. It explains the reading order, how to resolve an apparent conflict between sections, and what to do when you encounter something the document genuinely does not cover.

Table of Contents #

1. Before You Start
2. Project Overview & Vision
3. Technology Stack & Architecture
4. Conventions & Best Practices
5. Data Model & Schema
6. Authentication & Account Management
7. Workspaces, Teams, Roles & Permissions
8. Form Builder & Field Types
9. Form Logic, Calculations & Pre-fill
10. AI Form Generation & Assistance
11. Hosted & Embedded Form Runtime
12. Partial Submissions & Submission Pipeline
13. Response Management & Export
14. File Uploads & Object Storage
15. Spam & Abuse Protection
16. Analytics
17. Integrations & Webhook Delivery
18. Payments
19. Billing, Plans & Usage Enforcement
20. Custom Domains, TLS & White-Label
21. API Design (public + internal)
22. Security, Privacy & GDPR Compliance
23. Accessibility (WCAG 2.2 AA)
24. Observability, Logging & Monitoring
25. Testing Strategy
26. Deployment & Infrastructure
27. Performance Budgets & Optimization
28. Milestones & Execution Plan
29. Executor Instructions
30. Appendices

1. Before You Start #

This section is a customization pass. Read it, answer what you care about, and move on. Every question below has a concrete working default. If you skip a question, take the default — the default is a real, functioning choice, not a placeholder. Nothing in this build is allowed to stop and wait for an answer.

1.1 Customization questions #

1.2 How answers are applied #

Answers land in exactly two places. Nothing else reads them.

1. Environment variables — every operational answer (domains, provider credentials, region, DSNs) is an environment variable parsed and validated at process start by the shared config package described in Section 3.3. The complete table — every variable, its type, whether it is required or optional, its default, which deployable reads it, and what happens when an optional one is missing — is in Section 26. There is no second environment-variable list anywhere in this document, and a CI check asserts that the table in Section 26 and the boot-time schema in packages/config contain exactly the same keys in both directions.
2. packages/config/src/product.ts — a single typed object holding the non-secret product answers (product name, support email, default currency, retention windows, seed toggle). It is imported by both applications and the worker. No component reads these values from anywhere else, and no string from this file is duplicated as a literal elsewhere in the codebase.

// packages/config/src/product.ts
export const product = {
  name: process.env.NEXT_PUBLIC_PRODUCT_NAME ?? 'Formcraft',
  supportEmail: process.env.SUPPORT_EMAIL ?? 'support@formcraft.app',
  defaultCurrency: 'USD',
  analytics: { rawEventRetentionDays: 90, rollupRetentionDays: 400 },
  seedDemoData: process.env.SEED_DEMO_DATA === 'true',
} as const

1.3 Pre-flight checklist #

Before the first pnpm dev, the following exist. Each line states what to do if it does not.

1.4 The no-blocking rule #

If an answer is absent at build time, take the default in the table above and continue. Do not emit a placeholder, do not leave a stub that throws "not configured", and do not ask. Where an optional external service is genuinely unavailable, the correct behaviour is a documented, tested degradation path — the feature disables cleanly, the rest of the product works, and the disabled state is visible in the UI and in /api/v1/health. Every degradation path named in the table above is covered by a test in Section 25.

The rule has one deliberate exception, stated in the last row of 1.3: a missing required secret is a fatal boot error, not a degradation. A product that starts without FORM_STATE_SECRET and then rejects every submission at runtime is worse than one that refuses to start and names the variable.

2. Project Overview & Vision #

2.1 The problem #

Online forms are a solved problem for the trivial case and an unsolved problem for everything else. A marketer who needs a lead-capture form with three fields can build one anywhere in two minutes. The moment that same form needs a branch ("if you selected Enterprise, ask for company size"), a computed total, a file upload with a size limit, a partial-capture safety net for respondents who abandon halfway, a webhook into the CRM, and a colleague who can edit it without being handed the account password — the tool either cannot do it, hides it behind a tier the customer cannot justify, or does it in an editor that becomes unusable past a dozen fields.

The failure compounds in three specific ways:

• The logic ceiling. Most builders support "show field B if field A equals X" and stop. Real intake flows need multi-condition groups, cross-page branching, calculations that feed other calculations, and logic on every field type rather than a privileged subset.
• The dishonest limit. When a form exceeds its plan's response cap, the common behaviour is to close the form or, worse, to accept the submission and discard it. The customer discovers this from a client who says "I filled that in last week." A lost submission is a lost customer, and no pricing page justifies it.
• The accessibility gap. Forms are the single most compliance-exposed surface on most websites, and the generated markup is frequently unusable with a keyboard or a screen reader. Teams that must meet WCAG 2.2 AA end up hand-building forms they should have been able to generate.

Formcraft targets exactly this middle: past the trivial form, below the enterprise workflow platform. A solo marketer is productive in five minutes with zero setup, and a twenty-person team never hits a wall.

2.2 Target user groups #

The workspace is the tenancy boundary from the first migration, for all three groups. A freelancer has one workspace and never thinks about it; an organization has several. This is deliberate: it means the later addition of SSO, SCIM and directory-scoped provisioning is additive work against an existing boundary rather than a rewrite. Section 7 owns the workspace, role and permission model.

2.3 Product principles #

These four principles decide arguments. When a design choice is unclear, the option that better satisfies the higher-listed principle wins.

Principle 1 — Five-minute productivity #

A new user reaches a published, working form inside five minutes without reading documentation, configuring a provider, or making a payment.

Concretely this requires: sign-up with email or an OAuth provider and no mandatory onboarding wizard; a workspace and a first form created automatically on first login; a builder whose default state is a usable form rather than an empty canvas; publish as a single action producing a working public URL; and a share/embed step that does not require touching DNS. AI generation (Section 10) exists to collapse the "blank canvas" minute specifically: describe the form in a sentence, get a real draft with correct field types, then edit.

Verification: an end-to-end test in Section 25 performs sign-up → generate → publish → submit → view response as a single unbroken run and asserts a wall-clock budget.

Principle 2 — Never hit a wall #

Capability grows with need instead of stopping at a tier boundary the product declines to explain. Three commitments follow.

• Logic is available on every field type, not a privileged subset. The distinction between plan tiers is depth (single-condition versus multi-condition groups and calculations), never "this field type cannot participate in logic."
• Every screen that shows a limit shows the actual number, the current usage, and the exact consequence of exceeding it — before it is exceeded, at 80%, and again at 100%.
• Every retained object is exportable in an open format at any tier. There is no data hostage situation: responses export to CSV and JSON, form definitions export to JSON, and files download in bulk, on the free plan as much as on Business. Section 13 owns export.

The word retained is load-bearing and is the one honest qualification on this promise. A response that has passed the retention window its plan or its form defines is deleted, and a deleted response is not exportable — on the Free plan responses are soft-deleted at day 30 and hard-purged at day 37, and between those two dates their answer values are neither readable nor exportable. That is a stated, visible, warned-about deletion the customer can prevent by upgrading before day 37, not a hostage situation. Section 13 owns the timeline, the warnings and the restore path.

Principle 3 — Accessibility is a hard requirement #

WCAG 2.2 AA on the respondent runtime and on the builder is a release gate, not a backlog item. Full keyboard navigation, correct programmatic labels and roles, visible focus, correct error association, and screen-reader-verified flows. Every UI feature section in this specification carries accessibility acceptance criteria of its own, and automated axe checks plus manual keyboard-only passes block merge from the first milestone onward. Section 23 owns the standard and the test matrix.

This is a principle rather than a checklist item because it constrains architecture: it is why the respondent runtime renders semantic HTML on the server before any JavaScript executes (Section 3.6), why every drag interaction in the builder has a stated keyboard equivalent (Section 8), why the builder is composed from accessible primitives rather than styled divs while the respondent page ships native semantic controls and no client framework at all (Sections 3.7 and 11), and why custom theming cannot express a colour pair that fails contrast (Section 11).

Accessibility is also where the product refuses to overclaim. The anti-abuse layer uses an invisible challenge by default, and that challenge can escalate to an interactive one when the risk signal demands it; Section 23 states this plainly in the public accessibility statement rather than asserting that no interactive challenge exists. An honest known exception is worth more than a false blanket claim.

Principle 4 — Never drop a submission #

A respondent who presses Submit and sees a success state has had their data durably stored. This principle overrides revenue protection, spam heuristics, and integration health.

Three separate mechanisms touch a submission, they behave differently, and this document never conflates them. Reading them as one control is the single most common way to misimplement this product:

Mechanism 3 rejecting a flood does not violate this principle and does not contradict mechanisms 1 and 2: when a rate limit fires, no response was ever created and nothing was lost — the respondent's answers stay on screen, the runtime retries once automatically, and the countdown UI in Section 15.8 tells them when to try again. What the principle forbids is accepting data and then losing it.

• Over the plan cap, the form keeps accepting responses. The workspace is flagged over_limit, the owner sees an in-app banner and receives email at 80% and 100% of the cap, and the response is stored normally. Submissions are never silently dropped, and forms are never auto-closed for exceeding a cap. Enforcement is server-side; any client-side limit display is advisory only. Section 19 owns the mechanics.
• Suspected spam goes to a review queue, never to /dev/null. Honeypot, timing checks and the captcha classify; they never delete, and they never reject. The workspace owner can review, approve and restore, and the respondent is never told they were flagged. Section 15 owns detection and the queue.
• A failing downstream never fails the submission. Webhooks, integrations, notification email and virus scanning all run as queued jobs after the response row is committed, dispatched from an outbox written in the same transaction. An integration outage produces retries and a visible delivery-failure state, never a rejected submission. Section 12 owns the pipeline; Section 17 owns delivery.
• A payment failure never destroys the answers. On a form with a payment field the answers are captured before money is taken: the response row is created in pending_payment state and completed by an idempotent finalize step once the payment succeeds. A declined card leaves a recoverable response and a retry path, not an empty database and a frustrated respondent. Section 18 owns payments; Section 12 owns the branch into them.
• Partial capture is real. On plans that include it, answers are persisted as the respondent progresses so an abandoned multi-page form is not a total loss. Section 12 owns partials.

2.4 Competitive framing #

Tally wins on speed and generosity — a document-style editor and a famously permissive free tier — but its logic is shallow, its layout model resists anything that is not a linear document, and its accessibility is incidental rather than engineered. Fillout goes considerably deeper on logic and integrations and is the closest functional comparison, but its builder complexity is the price of that depth, and its pricing pushes teams toward per-seat spend early. Cognito Forms is the strongest of the three on calculations and payments and is trusted in regulated-adjacent contexts, but its interface is dated, its embeds are heavy, and its collaboration model is thin. Formcraft's position is the intersection none of them occupy: Tally's five-minute start, Fillout's logic depth, Cognito's calculation rigour, with two things none of them offer — AI form generation that produces a genuinely editable draft rather than a template, and an explicit promise that hitting a limit costs you money, never data. Accessibility is the fourth differentiator and the one that is hardest to retrofit: a runtime engineered for WCAG 2.2 AA from the first component is a durable advantage over a runtime that will need to be rebuilt to get there.

2.5 What success looks like #

Success is defined by observable outcomes on the deployed product, not by feature counts. Where a row below concerns performance, the number itself is owned by Section 27 and is stated there once, with its units and its measurement method; this table names the outcome and defers.

2.6 Scope #

Out-of-scope items are excluded from build work, not from design consideration. The architecture must not foreclose them: the workspace boundary keeps SSO additive; retaining personally identifying data in identifiable tables with an access log keeps HIPAA reachable; region-parameterized storage and database configuration keeps data residency a deployment concern rather than a schema change; and implementing SOC 2-aligned controls (access logging, change management, encryption at rest, least privilege) now means a future audit is evidence collection rather than remediation. Section 22 records which controls exist and which are deferred.

3. Technology Stack & Architecture #

This section is the single source of truth for dependency versions. No other section states a version number. Where another section needs to name a dependency, it names the dependency and defers here for the line.

3.1 Stack #

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

Two rules follow from that paragraph and are not optional. First, do not downgrade a line to match recollection — these were verified against live package registries and are newer than any model's training data. Second, if the current stable release of a dependency has moved to a higher major line than the table states, take the newer line, record the deviation in the project README, and fix any resulting type errors; do not pin backwards to reproduce this table.

A third rule follows from the package manager: there is no npm in this project. The lockfile is pnpm-lock.yaml, dependency specifiers use the workspace:* protocol, and npm ci cannot resolve them. Every install, script, audit and container build in Sections 22, 25, 26, 28 and 29 uses pnpm or pnpm turbo.

3.2 Deployables #

The system is three deployable processes and four stateful dependencies. Nothing else runs.

3.3 Monorepo layout #

A single pnpm workspace. Applications compose packages; packages never import applications.

formcraft/
├── apps/
│   ├── web/                 # builder + dashboard + authenticated & public REST API
│   ├── forms/               # respondent runtime: SSR hosted forms, embed, submission ingress
│   └── worker/              # BullMQ workers and scheduled jobs
├── packages/
│   ├── config/              # env parsing (Zod), product config, feature flags
│   ├── db/                  # Drizzle schema, generated migrations, connection factory
│   ├── schemas/             # Zod schemas, field-type discriminated union, shared DTO types
│   ├── core/                # domain logic: logic engine, calculation engine, plan rules
│   ├── spam/                # honeypot, timing, reputation and submission scoring
│   ├── runtime/             # respondent form renderer components (no builder dependencies)
│   ├── ui/                  # builder design system (Radix + Tailwind); builder-only
│   ├── jobs/                # queue names, job payload schemas, enqueue helpers
│   ├── integrations/        # webhook, Zapier, Sheets, Slack adapters
│   └── observability/       # pino logger factory, Sentry init, request-id propagation
└── tooling/
    ├── eslint-config/
    ├── tsconfig/
    └── tailwind-config/

The dependency graph is acyclic and enforced by lint (Section 4.10):

config  ──►  db  ──►  core  ──►  jobs  ──►  integrations
   │          │        │  │
   │          │        │  └──►  spam
   └──────►  schemas ──┘
                │
       ┌────────┴─────────┐
       ▼                  ▼
    runtime              ui
       │                  │
       ▼                  ▼
  apps/forms          apps/web           apps/worker ──► core, spam, jobs, integrations, db

packages/ui and packages/runtime never import each other. packages/runtime may import packages/schemas and packages/core, but not packages/db, packages/spam, packages/jobs or packages/integrations — the respondent renderer must be importable in a browser bundle with no server-only dependency reachable from it. packages/spam is server-only: the decoy markup a honeypot needs is rendered by packages/runtime, but every scoring decision is made on the server where the respondent cannot see the thresholds. Section 4.1 gives the full directory tree inside each of these packages.

3.4 Runtime topology #

                          ┌──────────────────────────────┐
                          │          Respondents         │
                          │  browsers, embedded iframes  │
                          └───────────────┬──────────────┘
                                          │ HTTPS
                                          ▼
                          ┌──────────────────────────────┐
   customer custom  ─────►│             CDN              │◄──── static assets (both apps)
   domains (CNAME)        │  HTML cache + asset cache    │
                          └───────────────┬──────────────┘
                                          │ miss / POST
                                          ▼
   ┌───────────────────┐         ┌────────────────────┐
   │   Builder users   │         │     apps/forms     │
   │     browsers      │         │  SSR hosted forms  │
   └─────────┬─────────┘         │  embed bootstrap   │
             │ HTTPS             │  /api/v1/forms/... │
             ▼                   └─────┬────────┬─────┘
   ┌───────────────────┐                │        │
   │     apps/web      │                │        │  presigned PUT
   │ builder, inbox,   │                │        └──────────────────┐
   │ analytics, admin  │                │                           │
   │ /api/v1/*         │                │                           ▼
   │ /api/internal/*   │                │                 ┌───────────────────┐
   └────────┬──────────┘                │                 │  Object storage   │
            │                           │                 │  (S3-compatible)  │
            │        ┌──────────────────┘                 └─────────┬─────────┘
            │        │                                              │
            ▼        ▼                                              │
      ┌─────────────────────┐        ┌────────────────────┐         │
      │     PostgreSQL      │◄───────┤   Redis / Valkey   │         │
      │  system of record   │        │  queues, limits,   │         │
      └──────────┬──────────┘        │  locks, idempotency│         │
                 │                   └─────────┬──────────┘         │
                 │                             │                    │
                 │                             ▼                    │
                 │                   ┌────────────────────┐         │
                 └──────────────────►│    apps/worker     │◄────────┘
                                     │ webhooks, email,   │
                                     │ AV scan, exports,  │──► Stripe · Resend · Anthropic
                                     │ rollups, retention │──► Zapier · Sheets · Slack
                                     └────────────────────┘

Notes on the diagram. The CDN fronts both applications; only apps/forms serves cacheable respondent HTML, and only for forms whose definition permits it (Section 11 states the cache key and the invalidation rule). Custom domains terminate at the same apps/forms ingress and are resolved to a form by hostname lookup (Section 20) — which is why every respondent-facing route is addressed by form slug rather than by form id (Section 4.5). File bytes never transit either application on the ordinary path: the browser uploads directly to object storage with a presigned URL and the application only records metadata (Section 14). The worker is the only process that talks to third-party APIs on a schedule, and the only process permitted to hold long-running connections. The operator surface /api/internal/* is served by apps/web only, is never exposed on a customer domain, requires the X-Internal-Token bearer credential, is rate-limited, and every action taken through it is written to the audit log (Section 21).

3.5 Request lifecycle — a hosted form submission #

This is the canonical path. Every step names the owning section for its rules.

Render

1. The respondent requests https://forms.<domain>/f/<slug> or a customer custom domain. DNS resolves to the CDN.
2. On a cache hit for a publicly cacheable form, the CDN returns the stored HTML and the flow jumps to step 7. On a miss, the request reaches apps/forms.
3. apps/forms resolves the hostname: the forms subdomain uses the path slug; a custom domain is looked up in the domains table to find its workspace, then the slug within it (Section 20). An unknown host returns the 404 form-not-found page with no workspace information leaked.
4. The published form definition is loaded from PostgreSQL — the published version row, never the draft — together with its theme and its settings. A closed, scheduled-out-of-window, password-protected or response-limited form short-circuits to the corresponding state page (Section 11); a submit attempt against one of those states is 409 FORM_CLOSED.
5. The form is rendered on the server to semantic HTML: a real <form>, real <label> associations, real <input> elements, fields grouped by page in <fieldset> elements with <legend>. The first page is fully present in the initial HTML. Theme values become CSS custom properties in a single inline style block, and any workspace custom CSS is served as a separate first-party stylesheet rather than inlined (Section 22).
6. The response is returned with the cache headers from Section 11 and a signed form-state envelope bound to the form version. The envelope is signed with FORM_STATE_SECRET, carries the server-issued submission key that later serves as the idempotency key (Section 12), and is what makes a replayed or cross-form submission detectable. It is not a CSRF token: cross-origin protection for authenticated surfaces is Origin/Referer validation, owned by Section 22.
7. The respondent runtime binds to the already-rendered DOM. It attaches validation, logic evaluation, calculation, page navigation and upload handling by delegation from the form root. There is no hydration payload and no client framework (Section 3.6). Nothing about the first paint depends on this step completing.
8. A view analytics event is recorded cookie-free by a deferred beacon to POST /api/v1/e (Section 16).

Fill

1. As the respondent types and selects, the logic engine from packages/core re-evaluates visibility, requirement and jump rules, and the calculation engine recomputes dependent values using decimal arithmetic (Section 9). All of this is local; no network round-trip occurs for logic.
2. A file field uploads directly: the runtime requests a presigned URL from POST /api/v1/forms/:slug/uploads, which validates the declared size and MIME type against the form's field configuration and the workspace's plan limits, records an upload row in the initiated state, and returns the URL. The browser PUTs the bytes to object storage and reports completion. The upload is not yet downloadable — it is scanned first, and the state machine that governs it is owned by Section 14. If the workspace is past its storage cap and outside the grace window, the presign request is refused with 402 STORAGE_LIMIT_REACHED (Section 14).
3. On plans that include partial capture, a debounced PATCH to the partial-submission endpoint (/api/v1/forms/:slug/partials/:partialId, Section 12) persists answers-so-far against a partial submission record.

Submit

1. The runtime validates the complete answer set against the shared Zod schema. Failures are rendered inline, focus moves to the first invalid field, and the failure is announced to assistive technology (Section 23). No request is sent.
2. On success, the runtime sends POST /api/v1/forms/:slug/submissions with the answers, the signed form-state envelope, the honeypot value, the captcha token, and the partial-submission token if one exists. The Idempotency-Key header carries the server-issued submission key from the envelope; a value that does not match the envelope is rejected (Section 4.5).
3. The ingress applies, in order: abuse rate limiting by IP and by form, which is the one mechanism here that rejects, with 429 RATE_LIMITED and Retry-After (Section 15.8); idempotency lookup, returning the original stored response if the key has been seen; envelope signature and form-version verification; and payload size limits.
4. The payload is re-validated on the server against the same Zod schema, plus server-only rules the client cannot be trusted for: field existence in the published version, option membership for choice fields, file ownership for upload references, and recomputation of every calculated value from raw inputs. A client-submitted calculated value is never trusted; it is recomputed and the server's result is stored.
5. Spam classification runs against the visible field set, resolved from the published manifest with the same logic evaluator step 15 uses. Honeypot filled, captcha failed, or content heuristics tripped set the response's status to in_review. The response is still stored and the respondent still sees the ordinary success state; classification never rejects and never deletes (Section 15).
6. Payment branch. A form with a payment field does not complete in one request. The pipeline inserts the response with status = 'pending_payment' and its payment row, creates the Stripe Payment Intent, and returns the client secret; the respondent confirms; an idempotent finalize call then completes the response. Data is captured before money is taken, so a declined card never destroys the answers. The Stripe webhook remains the source of truth for payment state, and an amount that does not match the server's recomputed total is 422 PAYMENT_AMOUNT_MISMATCH with the automatic refund and alert defined in Section 18.
7. For a form with no payment field, a single database transaction inserts the response row and its answer rows, links the referenced uploads to the response, marks the partial submission as converted, increments the workspace's monthly response counter, and writes the outbox rows for every side effect. The counter increment and the outbox insert are inside the transaction so usage cannot drift from reality and no side effect can be lost. For a payment form, those last two happen at finalize instead (Section 18) — a pending_payment response does not consume plan quota and does not fire integrations.
8. Usage evaluation runs post-commit: crossing 80% or 100% of the plan's response cap sets the workspace flag and enqueues the notification. The response is committed regardless of the cap (Section 19).
9. The outbox sweeper dispatches jobs for every side effect: webhook deliveries, integration pushes, notification and autoresponder email, virus scanning of newly attached files, analytics rollup, and the search index update. A queue outage delays delivery; it never fails the request and never loses the side effect (Section 12).
10. The API returns 201 with the success envelope from Section 4.5, containing the response id and the configured post-submit behaviour.
11. The runtime shows the thank-you state or performs the configured redirect, and records a completion analytics event.

Failure modes

3.6 Why the respondent runtime is server-rendered and framework-free #

Server rendering hosted forms is not a preference; four requirements force it.

• Performance. The budget is a sub-second first contentful paint on a mid-tier mobile device over 4G at p75, stated with its units in Section 27. A client-rendered form pays for framework download, parse, execute and data fetch before a single field appears. Server rendering puts the complete first page in the first response, so the form is visible and readable at first paint.
• Accessibility. A form that exists in the initial HTML as a real <form> with real labelled inputs works for a screen reader, a keyboard user, and a browser with JavaScript blocked, before any script runs and independently of it. Client-rendered forms make assistive technology wait on JavaScript and make focus management a bug surface. Section 23's guarantees are far cheaper to keep when the semantic baseline is already correct.
• Cacheability. Server-rendered HTML for a public form is cacheable at the CDN, which turns the common case into an edge response with no application or database involvement. A client-rendered shell cannot cache the thing that matters.
• Correctness of what is shipped. Server rendering means the client only receives the published definition it needs to render, not a general-purpose form engine plus a definition document. This is what keeps the payload inside the byte budget.

There is no client framework on the respondent page. React renders on the server only, and there is no hydration payload. Interactivity comes from @formcraft/respondent-runtime, a dependency-free TypeScript bundle that attaches delegated listeners at the form root and loads field modules only for the field types present on the current page. This is progressive binding, not hydration: the form is usable as plain HTML before any script runs, and script adds logic, calculations, client validation, uploads and page transitions on top of a working document. A CI check asserts the runtime package has zero runtime dependencies; Section 27 owns the byte budget the check defends.

A submission from a page where script never ran performs a native POST to the same ingress and is handled identically — server validation is authoritative regardless, so nothing is lost.

3.7 Why the respondent runtime is a separate, minimal bundle #

apps/forms and packages/runtime exist as separate artifacts from apps/web and packages/ui for reasons that are structural rather than stylistic.

• The byte budget is a hard constraint, and shared bundles leak. The respondent runtime ships under the critical-JavaScript ceiling in Section 27. The builder legitimately depends on dnd-kit, Recharts, TanStack Query, a rich text editor and a large Radix surface. If both surfaces live in one application and one component graph, a single careless import from a shared component pulls builder-only weight into the respondent path, and the regression is invisible until a bundle analysis. A separate application with its own dependency list makes that import a build error rather than a slow leak.
• The trust boundaries are opposite. The builder serves authenticated users of a known workspace. The respondent runtime serves the anonymous public on arbitrary customer domains. Separating them means the respondent surface has no session handling, no admin routes, no workspace-scoped data access and no authenticated API client anywhere in its reachable graph — a whole class of vulnerability is removed by construction rather than by review.
• The traffic profiles are unrelated. A campaign can drive a hundred thousand respondents to one form while builder traffic is flat. Independent deployables scale independently, and a respondent traffic spike cannot degrade the builder or exhaust its connection pool.
• The change cadence differs. The respondent runtime is the most correctness-critical and least frequently changed surface in the product. Isolating it means routine builder work cannot regress it, and its deploys can carry a stricter gate: bundle-size assertion, axe pass, and the full submission end-to-end suite.
• Custom domains need a dedicated ingress. Serving customer domains means hostname-based routing, per-domain certificates and a white-label render path (Section 20). Keeping that on a dedicated application avoids exposing the builder's routes, and the operator surface in Section 21, on customer-controlled hostnames.

The two surfaces share exactly three things, all of them logic rather than presentation: the Zod schemas in packages/schemas, the logic and calculation engines in packages/core, and the field-type enum owned by Section 8 (which lives in packages/schemas). The builder's preview mode renders through packages/runtime, so the preview is the respondent runtime rather than a second implementation of it — this is the only way to guarantee that what the builder shows is what the respondent gets.

3.8 Environments #

Environment is carried in APP_ENV, validated against this fixed set at boot. Section 26 owns provisioning, the deploy procedure, and the single canonical environment-variable table.

4. Conventions & Best Practices #

These conventions are mandatory and mechanically enforced wherever enforcement is possible. The API, identifier, envelope and pagination definitions in 4.5 and the validation rules in 4.6 are canonical: Section 21 builds the public API surface on top of them and does not redefine them. Two things this section deliberately does not own: the error-code catalogue, which is the appendix in Section 30, and the field-type enum, which is Section 8's.

4.1 Repository layout #

formcraft/
├── apps/
│   ├── web/
│   │   ├── src/
│   │   │   ├── app/
│   │   │   │   ├── (marketing)/          # public marketing routes
│   │   │   │   ├── (auth)/               # sign-in, sign-up, reset, verify
│   │   │   │   ├── (app)/                # authenticated shell
│   │   │   │   │   ├── [workspaceSlug]/
│   │   │   │   │   │   ├── forms/
│   │   │   │   │   │   ├── responses/
│   │   │   │   │   │   ├── analytics/
│   │   │   │   │   │   └── settings/
│   │   │   │   │   └── layout.tsx
│   │   │   │   └── api/
│   │   │   │       ├── v1/               # authenticated + public-key REST API
│   │   │   │       ├── internal/         # operator surface, X-Internal-Token (Section 21)
│   │   │   │       ├── auth/             # better-auth handler
│   │   │   │       └── webhooks/         # inbound: stripe, stripe connect, email provider
│   │   │   ├── components/               # app-specific composition of packages/ui
│   │   │   ├── server/                   # route-handler services, guards, mappers
│   │   │   └── lib/
│   │   ├── e2e/                          # Playwright specs for builder flows
│   │   └── next.config.ts
│   ├── forms/
│   │   ├── src/
│   │   │   ├── app/
│   │   │   │   ├── f/[slug]/             # hosted form
│   │   │   │   ├── embed/                # embed bootstrap + iframe host
│   │   │   │   └── api/v1/               # submission, upload, partial, analytics ingress
│   │   │   ├── server/
│   │   │   └── lib/
│   │   ├── e2e/                          # Playwright specs for respondent flows
│   │   └── next.config.ts
│   └── worker/
│       ├── src/
│       │   ├── processors/               # one file per job type
│       │   ├── schedules/                # repeatable job registration
│       │   └── index.ts
│       └── Dockerfile
├── packages/
│   ├── config/src/{env.ts,product.ts,flags.ts}
│   ├── db/
│   │   ├── src/{schema/,client.ts,seed.ts}
│   │   └── drizzle/                      # generated migration SQL
│   ├── schemas/src/{fields/,forms/,api/,common/}
│   ├── core/src/{logic/,calculation/,plans/,slug/}
│   ├── spam/src/{score.ts,honeypot.ts,reputation.ts}
│   ├── runtime/src/{fields/,engine/,styles/}
│   ├── ui/src/{primitives/,patterns/,tokens/}
│   ├── jobs/src/{queues.ts,payloads.ts,enqueue.ts}
│   ├── integrations/src/{webhook/,zapier/,sheets/,slack/}
│   └── observability/src/{logger.ts,sentry.ts,request-context.ts}
├── tooling/{eslint-config,tsconfig,tailwind-config}/
├── docs/                                 # ADRs, runbooks, accessibility audit records
├── .github/workflows/
├── docker-compose.dev.yml
├── turbo.json
├── pnpm-workspace.yaml
├── pnpm-lock.yaml
└── package.json

Rules that this tree encodes and lint enforces:

• Applications import packages; packages never import applications. Packages import other packages only along the acyclic graph in Section 3.3.
• packages/db, packages/spam, packages/jobs and packages/integrations are server-only. Every file in them begins with import 'server-only'. Importing them from packages/runtime or packages/ui is a build error.
• Nothing outside packages/db writes SQL or holds a database client. Route handlers call services; services call repository functions in packages/db.
• Nothing outside packages/schemas declares a validation rule that is used on both sides of the network. One rule, one definition.
• There is no package-lock.json and no node_modules at an application root that shadows the workspace store. The only lockfile is pnpm-lock.yaml, and it is committed.

4.2 Naming #

Abbreviations are avoided except for id, url, api, db, ui, css, html. Acronyms in identifiers are cased as words: formId, apiKey, htmlContent — never formID or HTMLContent.

The last two rows are a deliberate separation. An envelope error code is the value of error.code and is defined once, in the catalogue in Section 30. A field-level validation key appears only inside details[].issue and is defined by Section 8 alongside the field type it belongs to. They are both SCREAMING_SNAKE_CASE and would otherwise be indistinguishable at a call site, which is why validation keys carry the V_ prefix in code. A validation key is never the value of error.code, and an envelope code never appears in details[].issue.

4.3 TypeScript conventions #

Compiler settings. A single base config in tooling/tsconfig is extended by every package. It is non-negotiable:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true,
    "noPropertyAccessFromIndexSignature": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "moduleResolution": "bundler",
    "target": "es2023",
    "skipLibCheck": true
  }
}

any is banned. @typescript-eslint/no-explicit-any is an error. When a value is genuinely unknown — a parsed JSON body, a third-party webhook payload — the type is unknown and it is narrowed by a Zod schema before use. Type assertions (as) are permitted only in three places: narrowing after an explicit runtime check, constructing a branded ID inside its own constructor function, and in test fixtures. Every other as requires an inline comment justifying it, and as any is never permitted.

Discriminated unions for closed sets. Field types are a closed set. They are modelled as a discriminated union on type, so adding a field type produces exhaustiveness errors at every site that handles fields — which is the point.

FIELD_TYPES is declared exactly once, in Section 8, and the database enum in Section 5 is generated from it. This subsection does not restate its members and neither does any other section; a second copy of that list is how a renderer, an exporter and a migration end up disagreeing about what a form can contain.

import { FIELD_TYPES, type FieldType } from '@formcraft/schemas' // members: Section 8

interface FieldBase<T extends FieldType> {
  readonly id: FieldId
  readonly type: T
  readonly label: string
  readonly helpText?: string
  readonly required: boolean
  readonly hidden: boolean
}

export type Field =
  | (FieldBase<'short_text'> & { maxLength?: number; pattern?: string })
  | (FieldBase<'number'>     & { min?: number; max?: number; precision: number })
  | (FieldBase<'dropdown'>   & { options: readonly ChoiceOption[]; allowOther: boolean })
  // ...one member per FieldType, in the order Section 8 declares them

Exhaustive switches end in a never guard, so an unhandled variant fails the build:

export function assertNever(value: never, context: string): never {
  throw new Error(`Unhandled variant in ${context}: ${JSON.stringify(value)}`)
}

The same pattern applies to logic conditions, logic actions, integration providers and job payloads. Any closed set that will grow is a discriminated union, never a string plus a Record<string, unknown> bag.

Branded ID types. Every entity identifier has a distinct nominal type, so passing a form id where a response id is expected is a compile error rather than a production incident.

declare const __brand: unique symbol
type Brand<TValue, TBrand extends string> = TValue & { readonly [__brand]: TBrand }

export type WorkspaceId = Brand<string, 'WorkspaceId'>
export type FormId      = Brand<string, 'FormId'>
export type ResponseId  = Brand<string, 'ResponseId'>
export type FieldId     = Brand<string, 'FieldId'>
export type UserId      = Brand<string, 'UserId'>
export type UploadId    = Brand<string, 'UploadId'>

One branded type exists per entity in the prefix registry in Section 5.2, and the registry is what decides which prefixes exist — this block illustrates the mechanism, not the allocation.

Branded values are produced by exactly two mechanisms and no other: the id generator for that entity, and a Zod schema that validates the prefix and shape while narrowing the type. Both live in packages/schemas.

export const FormIdSchema = z.string()
  .regex(/^frm_[0-9A-HJKMNP-TV-Z]{26}$/, 'Invalid form id')
  .transform((v) => v as FormId)

Other rules. Prefer type over interface except when declaration merging or extends on an object contract is genuinely useful. All shared data structures are readonly at their boundaries; mutation happens on local copies. Functions taking more than two arguments take a single named-options object. null means "explicitly absent and stored as such"; undefined means "not provided" — the two are not interchangeable, and exactOptionalPropertyTypes enforces it. Never use non-null assertion (!); narrow instead. Every exported function in a package has an explicit return type; inference is fine for local functions.

4.4 Database conventions #

A schema-drift test in Section 25 compares the Drizzle schema, the migration sequence and a freshly migrated database in both directions and fails on any difference. That test is what makes the schema-ownership rule enforceable rather than aspirational: a stray ALTER TABLE in a feature section shows up as drift the first time CI runs.

4.4.1 Delete policy #

The distinction is explicit and load-bearing.

• Soft delete applies to workspaces, forms and responses. deleted_at is set; rows remain. Every read path filters deleted_at is null — enforced by mandatory repository helpers in packages/db rather than by remembering to write the predicate. A soft-deleted row is restorable from Trash for a bounded window and is then purged by a scheduled job; the window, the warnings and the purge deadline for responses are owned by Section 13, and for workspaces by Section 7.
• Hard delete applies to two cases with no exception. First, GDPR erasure requests: the subject's rows are physically removed, dependent rows cascade, and only a non-identifying tombstone recording that an erasure occurred and when is retained (Section 22). Second, uploaded files: object storage keys are deleted immediately on file removal, on response deletion and on retention expiry, and the upload row moves to its terminal deleted state with them — a soft-deleted file is still a stored file, and a stored file is still a liability.

Hard deletes are performed by a named, audited service function; there is no ad-hoc DELETE in application code.

4.5 API conventions #

These definitions are canonical for the entire product. Both the internal builder API and the public API in Section 21 conform to them without variation.

Paths. /api/v1/<plural-resource>, kebab-case segments, nested no more than three levels, and only where the third segment is an action or a sub-collection of a workspace-scoped or form-scoped resource: /api/v1/forms/:formId/responses, /api/v1/workspaces/:workspaceSlug/invitations/:invitationId/resend. Beyond that, the resource is addressed at top level with a filter: /api/v1/response-values?responseId=res_....

There are three path families and no others:

Respondent ingress is versioned and addressed by form slug. It is /api/v1 like everything else — it is not a separate unversioned surface — and it identifies the form by its public slug rather than its id, because a custom domain resolves a hostname to a workspace and then a slug to a form, and a form-id route does not exist on a custom domain at all. The canonical spellings, used document-wide with no variation, are:

POST   /api/v1/forms/:slug/submissions                        # submit (Section 12)
POST   /api/v1/forms/:formId/submissions/prepare                # payment forms, step 1 (Section 18)
POST   /api/v1/forms/:formId/submissions/:responseId/finalize   # payment forms, step 2 (Section 18)
POST   /api/v1/forms/:slug/uploads                            # presign an upload (Section 14)
PATCH  /api/v1/forms/:slug/partials/:partialId                # partial autosave (Section 12)
POST   /api/v1/e                                              # analytics ingest (Section 16)

Every payment path is prefixed /api/v1 like every other path. Section 21 catalogues each of these with its full request and response contract; the catalogue is the source the contract tests are generated from, so an endpoint that is not in it is an endpoint CI does not check.

Casing. JSON request and response bodies are camelCase, always. Database columns are snake_case and Drizzle performs the mapping. Query parameters are camelCase. Headers are conventional HTTP casing.

Methods. GET reads, POST creates and performs actions, PATCH partially updates, PUT replaces whole documents (used for form definitions only), DELETE deletes. GET and DELETE never carry a body.

Success envelope. Every 2xx response is exactly this shape. There is no bare-array response and no top-level scalar.

{
  "data": { },
  "meta": { }
}

For collections, data is an array and meta carries pagination. For single resources, data is an object and meta may be {} or carry contextual metadata. 204 No Content is used for deletes with nothing to return and carries no body at all.

Redaction inside the envelope. A field the caller is not permitted to see keeps its key and carries { "value": null, "text": null, "redacted": true }, and the response carries meta.redactedFieldIds: string[]. The key is never omitted — a caller must be able to tell that data was collected without being able to read it. This shape is identical in the application API, the public API and every integration payload, and the projection that produces it happens in SQL, never in the UI. Section 7 owns who may see what; Section 13 owns the response surfaces.

Error envelope. Every 4xx and 5xx response is exactly this shape.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Human readable.",
    "details": [ { "field": "email", "issue": "Invalid email address" } ],
    "requestId": "req_01H..."
  }
}

Error codes. code is a stable SCREAMING_SNAKE_CASE string. The complete, canonical catalogue — every code, its HTTP status and its meaning — is the error-code appendix in Section 30. There is no second list, and this section does not reproduce one: a code table here would be a copy, and a copy drifts. A new code is added to that appendix in the same pull request that introduces it, and the exported ErrorCode union is generated from it; CI compares the two sets in both directions and fails on any difference.

HTTP status carries the class of failure; code carries the specific reason. The two are always consistent, and these rules decide which status a new code takes:

500 responses never leak internals; every one is logged with its requestId, stack and context, and reported to the error tracker.

Rate limiting is three separate things and the API never conflates them: abuse limits on the respondent surface (Section 15.8, 429), per-plan API limits (Section 19, 429), and the monthly plan response cap (Section 19.10), which flags the workspace and never rejects a submission.

Cross-origin protection. State-changing requests from a session principal are validated by Origin/Referer comparison against the allowed application origins. There is no double-submit cookie token anywhere in this product. A failure is 403 CSRF_ORIGIN_REJECTED, and Section 22 owns the mechanism and the allowed-origin list.

Cursor pagination. Cursor-based, everywhere, without exception. Offset pagination does not exist in this product.

Request: ?limit=<1..100>&cursor=<opaque> — limit defaults to 50 and is clamped to 100 (a larger value is clamped, not rejected); cursor is omitted for the first page.

Response:

{
  "data": [ { "id": "res_01H..." } ],
  "meta": { "nextCursor": "eyJrIjoiMjAyNi0wOC0xOVQxMDoxMjozM1oiLCJpIjoicmVzXzAxSC4uLiJ9",
            "hasMore": true }
}

nextCursor is null and hasMore is false on the final page. A cursor is a base64url-encoded JSON object { "k": <sort key value>, "i": <tiebreaker id> }, opaque to clients, and valid only for the sort and filter set that produced it. The default sort is created_at desc, id desc; the id tiebreaker makes the ordering total, so no row is ever skipped or repeated across pages. A cursor that fails to decode, or whose embedded sort does not match the request's, returns 400 INVALID_CURSOR. Total counts are not returned by default — an expensive count is opt-in via ?includeTotal=true, which adds meta.total, and is not permitted on unbounded response queries.

Identifiers. All identifiers are generated by the application, never by the database.

• Public-facing entity ids are prefixed ULIDs stored as text primary keys: a three- or four-character lowercase prefix, an underscore, then a 26-character Crockford base32 ULID — frm_01J9Z8QK7F3M2A0P5N6R8T4V1C. The rationale is threefold: they sort lexicographically by creation time, which makes cursor pagination and time-ordered indexes cheap; they are URL- and copy-paste-safe; and they leak no row counts or growth rate to anyone who sees one.

• Prefixes are globally unique per entity type, so any identifier is self-describing in a log line, a support ticket or a URL, and a mis-routed identifier fails validation immediately. A prefix is never reused for a different entity, even after the original is removed.

• The complete prefix registry is the table in Section 5.2, and it is not restated here. This subsection fixes the format; Section 5.2 fixes the allocations. A section introducing a new entity adds its prefix to that registry in the same change, and to the ID_PREFIXES constant the registry defines. Two copies of a prefix list is exactly how one section ends up validating sub_ as a submission while another stores it as a subscription.

• Form public slugs are separate, and this is their one definition. A slug is not an id: it is a 10-character nanoid over the alphabet 23456789abcdefghijkmnpqrstuvwxyz (digits and lowercase letters with visually ambiguous characters removed), globally unique across the deployment — not per workspace, because a slug resolves on a shared host. Owners may replace a slug with a custom value matching ^[a-z0-9](?:[a-z0-9-]{1,48}[a-z0-9])$ (3–50 characters), subject to a reserved-word list; a collision is 409 FORM_SLUG_TAKEN. Slugs are mutable; ids never are. Section 5 stores the column, Section 8 owns the settings UI, and both cite this paragraph rather than restating the length, the alphabet or the pattern.

• Idempotency keys are carried in the Idempotency-Key header, at most 255 characters, and scoped to the route plus the principal. On authenticated write endpoints the key is client-supplied. On the anonymous submission endpoint it is server-issued: a ULID minted at render time and carried inside the signed form-state envelope (Section 12), because a client-chosen key on an anonymous endpoint is a cross-respondent collision and enumeration vector. When both a header and an envelope value are present they must be equal, or the request is rejected. Keys are stored with the resulting response for 24 hours; a repeat within that window replays the stored result rather than re-executing.

• Request ids are the req_ prefix plus a ULID, generated at ingress if the client did not supply X-Request-Id, propagated through every log line, enqueued job and outbound call, and returned in the error envelope and the X-Request-Id response header.

Money. Money is always an object — an integer count of minor units plus an ISO 4217 code:

{ "amountMinor": 2500, "currency": "USD" }

Never a decimal string, never a bare number, never split across two sibling keys, and never snake_case. This holds in request bodies, response bodies, webhook payloads and integration payloads without exception, including payloads whose consumer prefers flat keys — a flat-key requirement applies only to a fields object keyed by slugified field labels, never to the money value itself.

Other API rules. All list endpoints accept ?filter[...] style scoped filters defined by their owning section, and a ?sort= parameter restricted to an allow-list per resource. Timestamps in JSON are ISO 8601 with an explicit Z offset. Booleans in query strings accept only true and false. Unknown properties in a request body are rejected with 422 VALIDATION_FAILED rather than silently ignored, so a typo in an integration is visible immediately. A signed URL is never placed in a response body, a webhook payload, an email or a log line; a payload that needs to reference a file carries the upload id and a download path the consumer calls with its own credential (Section 14).

4.6 Validation #

One rule has one definition. Every validation rule that applies on both the client and the server is a Zod schema in packages/schemas, imported by the renderer and by the route handler. A rule duplicated in two places is a defect regardless of whether the two copies currently agree.

• Route handlers parse the request body with safeParse and map a Zod failure directly onto the error envelope's details array using a single shared mapper — the field path comes from the Zod issue path, the issue text from the schema's message.
• The client renderer uses the same schema for inline validation. Client validation is a user experience feature; the server's parse is the only authority, and it always runs.
• Every jsonb column has a schema, and every read of that column parses through it. A row that fails to parse is a logged error, not a crash: the read path returns a typed "malformed record" result the caller must handle.
• Environment variables are parsed once at boot by a Zod schema in packages/config. A missing required variable exits the process with a message naming the variable; a missing optional variable disables its feature and logs a structured warning. A CI check asserts that the key set of that schema and the key set of the environment-variable table in Section 26 are identical in both directions, so a variable can never be documented but unread, or read but undocumented.
• Schemas are named <Subject>Schema and their inferred types <Subject>: export type CreateFormInput = z.infer<typeof CreateFormInputSchema>. The type is always inferred from the schema, never declared alongside it.

4.7 Error handling #

One error type crosses layers. Domain and service code throws AppError, which carries the error code, HTTP status, safe message, optional details and an optional non-exposed cause. Its code parameter is typed as the ErrorCode union generated from the catalogue in Section 30, so throwing an unregistered code is a compile error rather than a runtime surprise.

export class AppError extends Error {
  constructor(readonly code: ErrorCode, message: string, readonly options: {
    status: number
    details?: ReadonlyArray<{ field: string; issue: string }>
    cause?: unknown
    expose?: boolean            // default true; false forces a generic client message
  }) { super(message, { cause: options.cause }) }
}

One place converts errors to responses. A single error boundary wraps every route handler. It maps AppError to its status and envelope, maps a Zod failure to 422 VALIDATION_FAILED, maps a known database uniqueness violation to 409 ALREADY_EXISTS and other constraint violations to 409 CONFLICT, and maps everything else to 500 INTERNAL_ERROR with a generic message. It logs at error for 5xx and warn for 4xx, attaches requestId, and reports 5xx to the error tracker. No route handler writes its own catch that formats a response.

Rules.

• Never swallow an error. A caught error is either handled meaningfully, rethrown, or converted to an AppError with context added. An empty catch block fails lint.
• Never throw a bare string or a plain object. Error subclasses only.
• Expected, recoverable outcomes are return values, not exceptions. A repository lookup that finds nothing returns null; a delivery attempt that fails returns a typed result the caller branches on. Exceptions are for the genuinely exceptional.
• Third-party clients are wrapped in an adapter that translates their errors into AppError with UPSTREAM_ERROR or a more specific code from the catalogue. Provider-specific error types never escape their adapter.
• Every outbound network call has an explicit timeout and an explicit retry policy. A call that exceeds its deadline surfaces as TIMEOUT. Retries use exponential backoff with jitter and apply only to idempotent operations or operations carrying an idempotency key.
• Background jobs throw to signal retry. A job that must not retry throws an UnrecoverableError and lands in the dead-letter queue with its full context. Section 12 owns retry counts and backoff schedules.
• User-facing error copy states what happened and what to do next, in one sentence, without jargon and without blame. It never exposes an internal identifier other than requestId.

4.8 Logging #

Structured JSON via pino, one logger factory in packages/observability, no console.* anywhere outside build scripts (enforced by lint).

Levels. fatal — the process cannot continue. error — an operation failed and a human should look. warn — degraded but handled: a retry, a fallback, a disabled optional dependency. info — significant state transitions: form published, response submitted, subscription changed, job completed. debug — development detail, off in production. trace — never enabled in production.

Mandatory fields. Every log line carries requestId (or jobId for worker lines), env, service (web | forms | worker), and release. Every line emitted inside an authenticated request additionally carries workspaceId and userId. Every line emitted while handling a form carries formId. These come from an async-context-bound child logger, not from being passed by hand.

Where a log line records a client IP, that address is the one derived from the trusted-proxy allowlist in Section 15.8 — never a raw X-Forwarded-For value — and it is stored under the retention and truncation rules in Section 22.

Never logged, under any circumstance: response answer values (redacted or not), uploaded file contents or filenames containing personal data, email addresses in message bodies, passwords, session tokens, API keys, Stripe secrets, webhook signing secrets, form-state or resume-token secrets, full request bodies for public submission endpoints, and any header in the redaction list. Signed URLs are never logged — a presigned URL is a bearer credential, and a log store with a 90-day retention is a 90-day credential store. pino's redact option is configured with paths covering authorization, cookie, set-cookie, *.password, *.token, *.secret, *.apiKey, *.signedUrl, *.answers — plus a query-string scrubber that strips any parameter matching X-Amz-* or signature — and redaction is verified by a test.

Message style. Lower-case, present-tense, event-shaped, with the variable parts in structured fields rather than interpolated into the string: logger.info({ formId, versionId }, 'form published'). This keeps messages groupable. HTTP access logging is automatic at the ingress and records method, route pattern (never the interpolated path, which can contain a slug), status, duration in milliseconds, and the mandatory fields.

4.9 Git workflow #

• Trunk-based. main is always deployable and is protected: no direct pushes, no force-pushes, linear history via squash merge.
• Branches: <type>/<short-kebab-description> where type is one of feat, fix, chore, docs, refactor, test, perf. Example: feat/conditional-logic-editor. Branches are short-lived; anything open longer than five days rebases on main.
• Commits: Conventional Commits — <type>(<scope>): <subject>, subject in the imperative mood, lower case, no trailing period, at most 72 characters. Scope is the package or application: feat(builder): add multi-condition logic groups. Breaking changes carry a BREAKING CHANGE: footer. The commit body explains why; the diff already shows what.
• Migrations are committed in the same commit as the code that depends on them, never separately.
• Pull requests are required for every change to main and must include: a description of the change and its rationale, the section number of this specification the change implements, screenshots or a recording for any UI change, and an explicit note when a migration is included. A PR touching respondent-facing UI states its accessibility verification.
• Merge requirements — all must pass, none are waivable: type check clean across the workspace; lint clean with zero warnings; unit and integration tests green; end-to-end suite green; axe accessibility checks green on changed UI routes, with any serious or critical violation blocking; respondent bundle-size assertion within the budget in Section 27; schema drift check clean; at least one approving review; and no unresolved review comment. This gate applies from the foundation milestone onward — the accessibility check is not deferred to a later milestone (Section 28).
• Releases are tagged v<major>.<minor>.<patch> from main, and the tag is the release identifier attached to logs and error reports. Section 26 owns the deployment procedure.

4.10 Formatting and lint #

Formatting is not a matter of opinion or review comment; it is a tool. Prettier owns formatting with a single shared config: two-space indentation, single quotes, no semicolons, trailing commas where valid, 100-character print width, LF line endings. It runs on a pre-commit hook over staged files and again in CI as a check.

ESLint owns correctness with a shared flat config in tooling/eslint-config. Warnings are errors; CI runs with --max-warnings=0. The rules that are not defaults:

A rule is disabled inline only with // eslint-disable-next-line <rule> -- <reason>; a disable without a reason fails lint.

4.11 Comments #

Comments explain why, never what. Code that needs a comment to explain what it does is rewritten instead.

• Every exported function, type and constant in a package has a TSDoc block stating its purpose, its non-obvious parameters, and what it throws. Application-internal helpers do not need one.
• A non-obvious decision gets an inline comment naming the constraint that forced it — a spec requirement, a browser bug, a provider limitation, a performance measurement. Where the reason is a section of this specification, cite the section number. A comment never cites a file or a document other than this one by name.
• TODO, FIXME, XXX and HACK comments are banned and fail lint. Work that is not done is either done or tracked as an issue with a link; it is not a comment.
• Commented-out code is deleted. Version control is the archive.
• Every migration file opens with a comment stating what it changes and whether it is destructive.
• Regular expressions of non-trivial length carry a comment giving an example of a matching and a non-matching input.

4.12 Dependency policy #

New runtime dependencies require justification in the pull request that adds them: what it does, why the standard library or an existing dependency is insufficient, its maintenance status, and its impact on the respondent bundle. A dependency reachable from packages/runtime or apps/forms additionally requires a measured bundle-size delta and must keep the budget in Section 27 intact — and packages/runtime itself must keep zero runtime dependencies, which CI asserts (Section 3.6). Dependencies are added at the current stable release per the known-good floor rule in Section 3.1, installed with pnpm add, and the pnpm-lock.yaml is committed. Automated dependency updates run weekly and land as pull requests that must pass the full merge gate like any other change.

5. Data Model & Schema #

This section is the canonical schema. Every table name, column name, enum value, and identifier prefix used anywhere else in this specification is defined here. Where another section describes behaviour, it references these names; it never introduces new ones.

5.1 Design principles and invariants #

1. Workspace is the tenancy boundary. Every row that can be reached by an authenticated request carries a workspace_id, either directly or through exactly one parent that does. Tables that denormalize workspace_id for query performance (for example responses, response_values, uploads) are documented as such and their value is written once at insert and never updated.
2. Application-generated identifiers. Primary keys are prefixed ULIDs stored as text. The database never generates an identity value for a public-facing row. Rationale: identifiers are known before insert (so multi-table writes need no round trips), they are lexicographically sortable by creation time, URL-safe, and leak no row counts. The documented exceptions are all internal, non-public tables and are listed once, here: analytics_events and file_access_log (high-volume append-only tables with a generated identity), analytics_hourly_form, analytics_hourly_dim, analytics_hourly_workspace, analytics_daily_field, response_tags and form_counters (natural composite keys), and workspace_storage and workspace_entitlement_overrides (keyed by workspace_id). Nothing addressable by a client uses anything but a prefixed ULID.
3. Snake_case in the database, camelCase on the wire. Drizzle performs the mapping. No API payload ever exposes a snake_case key; no SQL identifier is ever camelCase.
4. Timestamps are timestamptz, always stored in UTC. Every table has created_at; every mutable table also has updated_at, maintained by a database trigger, never by the application.
5. Soft delete for workspaces, forms, and responses only — a deleted_at timestamptz column. Every other table is hard-deleted or cascaded. GDPR erasure and uploaded-file removal are always hard deletes: the rows and the object-storage objects are physically removed. This distinction is load-bearing and is restated in Section 22.
6. Money is integer minor units. A *_minor bigint column plus a char(3) ISO 4217 currency column. No float, no real, no double precision anywhere in the schema. Decimal arithmetic in the form engine uses the decimal library from the stack in Section 3; results are persisted to numeric, never to a floating type.
7. Versioned form definitions. A form's structure is an immutable JSON document per version. Responses always reference the exact version they were captured against, so an old response never renders against a newer structure.
8. Forward-only migrations. Generated and applied with the migration tool named in Section 3. No down migrations exist; a mistake is corrected by a new forward migration.
9. No row is ever updated to a different tenant. workspace_id is immutable after insert; a database trigger rejects any statement that changes it.
10. Enumerations that are fixed in code are native PostgreSQL enum types. Anything an operator or customer can configure is a table row.
11. Plan definitions are code, not data. There is no plans table. The plan catalogue — the three plan identifiers, their prices, their numeric limits and their boolean entitlements — is the PLANS constant owned by Section 19. Every entitlement read resolves through that constant; the database stores only which plan a workspace is on (workspaces.plan_code) and the payment-provider state that pays for it (subscriptions). This is stated once here and once in Section 5.16.1, and nowhere else in this section.
12. All DDL lives in this section. No other section contains a CREATE TABLE, an ALTER TABLE, or a CREATE INDEX. Where another section needs a column, an index or a whole table, it is defined here — including the tables other sections own behaviourally, which are Section 5.29. A section that needs new storage adds it here and cites the subsection.

5.2 Identifier scheme and prefix registry #

An identifier is <prefix>_<ULID>, for example ws_01K3QF7M9YQ4X6R8N2VT5HJDBC. The ULID is Crockford base32, 26 characters, uppercase. Total length is therefore len(prefix) + 1 + 26 and is always ≤ 30 characters, so every identifier column is text with a CHECK constraint on the prefix rather than a fixed-width type.

ULIDs are produced by a ULID library (current stable major line) through a single helper; no call site generates an identifier inline.

// packages/core/src/ids.ts
import { ulid } from 'ulidx';

export const ID_PREFIXES = {
  user: 'usr', session: 'ses', account: 'acc', verification: 'ver',
  workspace: 'ws', workspaceMember: 'wsm', invitation: 'inv', formShare: 'shr',
  auditLog: 'aud', form: 'frm', formVersion: 'fvr', formField: 'ffd',
  formPage: 'fpg', logicRule: 'lgc', calculation: 'cal',
  fieldKey: 'fld', pageKey: 'pag', ruleKey: 'rul', calcKey: 'clc',
  optionKey: 'opt', conditionKey: 'cnd',
  response: 'res', responseValue: 'rvl', partialSubmission: 'prt',
  responseNote: 'rnt', savedView: 'svw', tag: 'tag', usageAdjustment: 'uad',
  upload: 'upl', uploadScan: 'scn', spamReview: 'spm',
  integration: 'itg', webhookEndpoint: 'whk', integrationDelivery: 'dlv',
  outboundEvent: 'evt', emailSend: 'eml', emailSuppression: 'sup',
  payment: 'pay', stripeEvent: 'sev', subscription: 'sub', usageCounter: 'usg',
  downgradeGrace: 'grc', entitlementOverride: 'ent',
  customDomain: 'dom', domainVerification: 'dvf', apiKey: 'key',
  aiGeneration: 'gen', consentRecord: 'cns',
  dataExportRequest: 'exp', dataDeletionRequest: 'del',
  exportJob: 'exj', formInvite: 'fiv', draftSnapshot: 'snp',
  outboxEntry: 'obx', request: 'req',
} as const;

export type IdPrefix = (typeof ID_PREFIXES)[keyof typeof ID_PREFIXES];
export type Id<P extends IdPrefix> = `${P}_${string}`;

export function newId<P extends IdPrefix>(prefix: P): Id<P> {
  return `${prefix}_${ulid()}` as Id<P>;
}

export function isId<P extends IdPrefix>(prefix: P, value: unknown): value is Id<P> {
  return typeof value === 'string'
    && value.length === prefix.length + 27
    && value.startsWith(`${prefix}_`)
    && /^[0-9A-HJKMNP-TV-Z]{26}$/.test(value.slice(prefix.length + 1));
}

This table is the whole registry. It is the single place a prefix is allocated. Section 4 fixes the identifier format; this subsection fixes the allocations, and no other section — including any appendix — restates them. A prefix is never reused for a different entity, even after the original entity is removed.

Document keys versus row identifiers. Six prefixes are keys inside the form-definition document rather than table primary keys: fld_ (field), pag_ (page), rul_ (logic rule), clc_ (calculation), opt_ (choice option) and cnd_ (logic condition). They are stable across versions of the same form — editing a field's label keeps its fld_ id — which is what makes response data comparable across versions. The projection tables that mirror them (form_fields, form_pages, logic_rules, calculations) carry their own surrogate row identifiers (ffd_, fpg_, lgc_, cal_) because the same stable key appears once per version.

Six collisions were resolved when this registry was consolidated, and the resolutions are binding: sub_ is a Subscription and never a submission (a submission produces a Response, res_); the internal record of a processed Stripe webhook is sev_ and the identifier on an outbound integration event is evt_; a workspace invitation is inv_ and a per-form distribution invite is fiv_; a form version is fvr_; a partial submission is prt_; an integration delivery attempt is dlv_.

Two identifier families are deliberately not ULIDs, and each is defined here once:

• Form public slug (forms.slug): a 10-character nanoid over the alphabet 23456789abcdefghijkmnpqrstuvwxyz — thirty-two symbols with 0/o, 1/l/i and u removed, so a slug read aloud or copied by hand does not collide. It appears in every public URL (/f/<slug>) and must be short, unguessable, and free of the creation-time ordering a ULID leaks. Globally unique across the deployment, not per workspace. 10 characters over 32 symbols is 50 bits, which at the design volume of Section 5.28 gives a collision probability below 1 in 10⁹ over the product's lifetime; the unique index makes a collision a retry, not a corruption.
• Form custom slug (forms.custom_slug): an optional author-chosen replacement, 3–50 characters matching ^[a-z0-9](?:[a-z0-9-]{1,48}[a-z0-9])$, also globally unique, also resolved at /f/<slug>. There is exactly one custom-slug pattern in this specification and it is this one; Section 8.14 applies it and does not restate it.
• Workspace slug (workspaces.slug): a human-chosen, human-readable string used in app URLs (/w/<slug>), rules in Section 7.1. The auto-generated suffix appended at sign-up is a 6-character nanoid over the same 23456789abcdefghijkmnpqrstuvwxyz alphabet.

5.3 Entity-relationship overview #

                          ┌────────────┐
                          │   users    │───┐
                          └─────┬──────┘   │ 1:N
                    1:N ┌───────┴──────┐   ├──────────► sessions
                        │              │   ├──────────► accounts
                        ▼              ▼   └──────────► verifications
              ┌──────────────────┐   ┌─────────────────┐
              │ workspace_members│   │  form_shares    │
              └────────┬─────────┘   └────────┬────────┘
                       │ N:1                  │ N:1
                       ▼                      │
   ┌────────────────────────────────────┐     │
   │            workspaces              │◄────┼──── invitations
   │  (tenancy root — soft delete)      │◄────┼──── audit_log
   └───┬───────┬────────┬────────┬──────┘     │     api_keys
       │       │        │        │            │     custom_domains ──► domain_verifications
       │       │        │        │            │     integrations   ──► webhook_endpoints
       │       │        │        │            │            │              │
       │       │        │        │            │            └──────────────┴──► integration_deliveries
       │       │        │        │            │     ai_generations   email_sends
       │       │        │        │            │     data_export_requests
       │       │        │        │            │     data_deletion_requests
       │       │        │        │            │     tags   outbox   workspace_storage
       │       │        │        │            │     workspace_entitlement_overrides
       │       │        │        │            │
       │       │        │        └────────────┴──► subscriptions
       │       │        │                          usage_counters ◄── usage_adjustments
       │       │        │                          downgrade_graces
       │       │        │
       │       │        └──────────────────────► uploads ──┬──► upload_scans
       │       │                                           └──► file_access_log
       │       └──► forms ◄───────────────── form_shares
       │              │  (soft delete)
       │              │ 1:N
       │              ├──────────► form_versions ──┬──► form_fields
       │              │            (immutable)     ├──► form_pages
       │              │                            ├──► logic_rules
       │              │                            └──► calculations
       │              │            form_draft_snapshots
       │              │
       │              ├──────────► responses ──────┬──► response_values
       │              │            (soft delete)   ├──► consent_records
       │              │                            ├──► spam_reviews
       │              │                            ├──► payments
       │              │                            ├──► response_tags ──► tags
       │              │                            ├──► response_notes
       │              │                            └──► uploads
       │              │
       │              ├──────────► partial_submissions ──► (promotes to a response)
       │              ├──────────► form_counters (1:1)   form_invites   submission_guards
       │              ├──────────► saved_views           export_jobs
       │              │
       │              └──────────► analytics_events (partitioned)
       │                           analytics_hourly_form / _dim / _workspace
       │                           analytics_daily_field
       │
       └──► stripe_events (webhook idempotency, workspace-nullable)

Legend:  ──►  foreign key (child on the arrow head)      ◄──  reverse view of the same key

Reading the diagram. workspaces is the tenancy root: cascading a workspace hard-delete reaches every row in the tree below it. forms is the second-level aggregate root: forms own versions, responses, partial submissions, and analytics. users sits outside the tenancy tree — a user is a global identity that joins zero or more workspaces through workspace_members. There is no reference table for plans: the plan catalogue is code (Section 5.1 rule 11 and Section 5.16.1).

5.4 Enumerated types #

All of the following are native PostgreSQL CREATE TYPE ... AS ENUM types, declared with Drizzle's pgEnum and therefore generated into migrations automatically. New values are added with ALTER TYPE <name> ADD VALUE <value> in a forward migration; a value is never removed — it is deprecated in TypeScript by narrowing the accepted set at the validation layer while the database still tolerates historical rows.

5.4.1 field_type #

There are exactly eighteen field types. Section 8.4 owns their semantics, settings and rendering; this table fixes the wire values, the storage class, and whether a value is captured. Section 5.10.4 expands the storage mapping. The enum, the TypeScript union in Section 5.9.2, the Zod discriminated union in Section 5.9.3, the pgEnum in Section 5.24.1 and Section 8.4's subsection list are the same eighteen identifiers in the same order, and a test asserts it.

page_break is a field type. It carries no answer and produces no response_values row; the projection table form_pages is derived from the ordered positions of page_break fields within a version, which is why a page is addressable by a stable pag_ key even though the author never creates a page directly.

Structural types (16–18) never produce a response_values row, never appear in an export column set, never appear in responses.data, and never appear in an API or webhook payload. form_fields.is_answerable is false for exactly these three.

Types that do not exist. A single-choice field is dropdown in one of three display modes and a multi-choice field is multi_select; there is no single_select, checkbox_group, checkbox, yes_no or radio. A scale is rating with a style; there is no slider, opinion_scale or nps. Date, time, date-and-time and date-range are the four modes of date; there is no time or datetime type. There is no url, country, address, matrix or ranking type at launch — the last two are drag-ordered constructs with no keyboard-equivalent worth shipping, and Section 23's guarantee that no capability requires dragging is the reason. Consent is consent, not legal_consent. A computed value is not a type: a number or currency field becomes read-only and computed by attaching a calculation (Section 9.7), and the schema records that with calculations.target_field_id. Content and layout are static_content and section_heading; there is no statement, image, divider or section_header.

5.5 Shared column conventions, triggers, and helpers #

5.5.1 Standard columns #

5.5.2 Migration 0000 — extensions and shared functions #

-- drizzle/0000_bootstrap.sql  (hand-written, applied before any generated migration)
CREATE EXTENSION IF NOT EXISTS pgcrypto;   -- gen_random_bytes for server-side token salts
CREATE EXTENSION IF NOT EXISTS pg_trgm;    -- trigram indexes for response text search

-- updated_at maintenance. Applied to every table that declares updated_at.
CREATE OR REPLACE FUNCTION set_updated_at() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
  NEW.updated_at := now();
  RETURN NEW;
END;
$$;

-- Tenancy immutability. Applied to every table that declares workspace_id.
CREATE OR REPLACE FUNCTION assert_workspace_immutable() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
  IF NEW.workspace_id IS DISTINCT FROM OLD.workspace_id THEN
    RAISE EXCEPTION 'workspace_id is immutable (table %, row %)', TG_TABLE_NAME, OLD.id
      USING ERRCODE = '23514';
  END IF;
  RETURN NEW;
END;
$$;

-- Append-only guard. Applied to audit_log and consent_records.
CREATE OR REPLACE FUNCTION assert_append_only() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
  RAISE EXCEPTION '% is append-only', TG_TABLE_NAME USING ERRCODE = '23514';
END;
$$;

Every subsequent migration that creates a table with updated_at appends:

CREATE TRIGGER <table>_set_updated_at BEFORE UPDATE ON <table>
  FOR EACH ROW EXECUTE FUNCTION set_updated_at();

and every table with workspace_id appends:

CREATE TRIGGER <table>_workspace_immutable BEFORE UPDATE ON <table>
  FOR EACH ROW EXECUTE FUNCTION assert_workspace_immutable();

The migration tool does not generate triggers. They are added by hand into the generated SQL file before it is committed, and a test (Section 25) asserts that every table carrying updated_at has its trigger and every table carrying workspace_id has its immutability trigger.

5.5.3 Soft delete and uniqueness #

Soft-deleted rows keep their unique values reserved unless stated otherwise. Where a value must be reusable after deletion, the unique index is partial:

CREATE UNIQUE INDEX workspaces_slug_active_key
  ON workspaces (slug) WHERE deleted_at IS NULL;

Every read path for a soft-deleting table adds AND deleted_at IS NULL unless it is an explicit trash/restore view. This is enforced by the repository layer (Section 5.27), not by a database view, because purge jobs and export jobs legitimately need the deleted rows.

5.6 Identity tables #

These four tables are owned by the authentication library named in Section 3. Its default table names are overridden to the plural, snake_case names below; its default id generation is overridden to the prefixed-ULID helper in Section 5.2. Columns marked (lib) are required by the library and must not be renamed or dropped; columns marked (app) are additions.

5.6.1 users #

users has no deleted_at. Account deletion is a hard delete after the grace period; during the grace period deletion_requested_at is the only marker.

5.6.2 sessions #

5.6.3 accounts #

One row per credential the user can authenticate with. At launch the only provider_id values are credential (email + password) and magic-link; the table shape already accommodates OAuth and OIDC providers without migration, which is one of the extension points named in Section 6.20.

5.6.4 verifications #

Single-use tokens for email verification, magic links, password reset, and email change. Tokens are stored hashed — value holds encodeHex(sha256(rawToken)), never the raw token — so a database disclosure cannot be replayed.

Single-use redemption is one statement, so two concurrent clicks cannot both succeed:

UPDATE verifications SET consumed_at = now()
 WHERE value = $1 AND consumed_at IS NULL AND expires_at > now()
 RETURNING id, identifier, payload;

5.7 Tenancy tables #

5.7.1 workspaces #

Why plan_code is duplicated on workspaces. Entitlement is checked on nearly every request (Section 7.12 step 5) and on every submission. Reading it from subscriptions would add a join to the hottest code path. workspaces.plan_code is therefore the authoritative entitlement value and subscriptions holds the payment-provider state. Exactly one writer keeps them consistent: the billing synchroniser (Section 19) updates both inside a single transaction. A nightly consistency job compares them and raises an alert on divergence.

5.7.2 workspace_members #

The unique index guarantees at most one owner. At least one owner is guaranteed by a deferred constraint trigger so that a transaction may temporarily hold zero or two owners while an ownership transfer swaps rows:

CREATE OR REPLACE FUNCTION assert_workspace_has_one_owner() RETURNS trigger
LANGUAGE plpgsql AS $$
DECLARE ws text; n int;
BEGIN
  ws := COALESCE(NEW.workspace_id, OLD.workspace_id);
  -- The workspace row is gone (cascade delete): nothing to assert.
  IF NOT EXISTS (SELECT 1 FROM workspaces w WHERE w.id = ws) THEN
    RETURN NULL;
  END IF;
  SELECT count(*) INTO n FROM workspace_members m
   WHERE m.workspace_id = ws AND m.role = 'owner';
  IF n <> 1 THEN
    RAISE EXCEPTION 'workspace % must have exactly one owner, found %', ws, n
      USING ERRCODE = '23514';
  END IF;
  RETURN NULL;
END;
$$;

CREATE CONSTRAINT TRIGGER workspace_members_owner_invariant
  AFTER INSERT OR UPDATE OR DELETE ON workspace_members
  DEFERRABLE INITIALLY DEFERRED
  FOR EACH ROW EXECUTE FUNCTION assert_workspace_has_one_owner();

5.7.3 invitations #

5.7.4 form_shares #

Per-form grants. The grantee must already be a member of the same workspace; sharing a form with somebody outside the workspace is not possible at launch (Section 7.5).

A composite foreign key keeps a grant from pointing at a form in a different workspace:

ALTER TABLE form_shares
  ADD CONSTRAINT form_shares_form_workspace_fk
  FOREIGN KEY (form_id, workspace_id) REFERENCES forms (id, workspace_id) ON DELETE CASCADE;

which requires UNIQUE (id, workspace_id) on forms (declared in Section 5.8.1).

5.7.5 audit_log #

Append-only. The application database role holds INSERT and SELECT only; UPDATE and DELETE are revoked and additionally blocked by the assert_append_only() trigger from Section 5.5.2. Scope is fixed in Section 7.11.

Retention: 400 days for Free and Pro, 400 days for Business at launch (a single value, restated in Section 22). Rows older than that are deleted by the retention worker — the only process permitted to delete from this table, and it runs as a separate database role that holds DELETE on audit_log alone.

5.8 Form definition tables #

5.8.0 The projection decision #

A form's structure is stored twice, deliberately:

• form_versions.definition — a single immutable JSONB document that is the source of truth.
• form_fields, form_pages, logic_rules, calculations — a derived relational projection of that document.

The document exists because the respondent runtime must fetch a complete form structure in one row read. Server-side rendering a hosted form has a sub-1-second first-contentful-paint budget (Section 27); one primary-key lookup returning one JSONB value is the cheapest possible shape, it is trivially cacheable by version identifier, and it is atomically consistent by construction.

The projection exists because relational questions are asked constantly and are miserable against a document: "which fields in this version are marked PII" (redaction), "what are the export columns for this version, in order" (CSV headers), "what is the drop-off rate per field" (analytics), and the referential integrity of response_values.field_id. Those queries need indexed rows.

Consistency rule. The projection is rebuilt inside the same transaction that inserts or updates a form_versions row. There is no background sync and no eventual consistency: a transaction that writes a version and fails to write its projection rolls back entirely. A single function, materialiseFormVersion(tx, version), is the only code permitted to write the four projection tables; it deletes and reinserts the rows for that form_version_id. Because published versions are immutable, that path runs at most twice per version (once on draft save, once on publish). A nightly reconciliation job recomputes definition_checksum for every version created in the last 24 hours, compares projected row counts against the document, and raises a Sentry error on any mismatch. Drift is a bug, never a normal state.

5.8.1 forms #

Additional constraints:

ALTER TABLE forms ADD CONSTRAINT forms_id_workspace_key UNIQUE (id, workspace_id);
ALTER TABLE forms ADD CONSTRAINT forms_published_needs_version
  CHECK (status <> 'published' OR current_version_id IS NOT NULL);

forms.current_version_id and form_versions.form_id form a cycle. Both foreign keys are created, but the two on forms are added in a later migration step and declared DEFERRABLE INITIALLY DEFERRED so a single transaction can insert the form, insert version 1, and point the form at it.

5.8.2 form_versions #

Immutable once status = 'published'. A published version's definition is never updated; the builder always edits a draft version and publishing promotes it.

ALTER TABLE form_versions ADD CONSTRAINT form_versions_id_form_key UNIQUE (id, form_id);
ALTER TABLE form_versions ADD CONSTRAINT form_versions_one_draft
  EXCLUDE (form_id WITH =) WHERE (status = 'draft');   -- at most one open draft per form

Immutability is enforced by a trigger that rejects any UPDATE touching definition, definition_checksum, schema_version, or version once status = 'published':

CREATE OR REPLACE FUNCTION assert_published_version_immutable() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
  IF OLD.status = 'published' AND (
       NEW.definition IS DISTINCT FROM OLD.definition
    OR NEW.definition_checksum IS DISTINCT FROM OLD.definition_checksum
    OR NEW.schema_version IS DISTINCT FROM OLD.schema_version
    OR NEW.version IS DISTINCT FROM OLD.version) THEN
    RAISE EXCEPTION 'published form version % is immutable', OLD.id USING ERRCODE = '23514';
  END IF;
  RETURN NEW;
END;
$$;
CREATE TRIGGER form_versions_immutable BEFORE UPDATE ON form_versions
  FOR EACH ROW EXECUTE FUNCTION assert_published_version_immutable();

Version retention: the 50 most recent versions per form are kept indefinitely; older versions are deleted only if no response, partial submission, or analytics row references them, checked by the ON DELETE RESTRICT foreign keys on the referencing tables. In practice this means every version that ever received a response is permanent.

5.8.3 form_fields (projection) #

ALTER TABLE form_fields ADD CONSTRAINT form_fields_version_field_key
  UNIQUE (form_version_id, field_id);
ALTER TABLE form_fields ADD CONSTRAINT form_fields_version_name_key
  UNIQUE (form_version_id, name);
ALTER TABLE form_fields ADD CONSTRAINT form_fields_version_position_key
  UNIQUE (form_version_id, position) DEFERRABLE INITIALLY DEFERRED;

5.8.4 form_pages (projection) #

UNIQUE (form_version_id, page_id), UNIQUE (form_version_id, position) DEFERRABLE INITIALLY DEFERRED. Index (form_version_id, position) for ordered rendering of paginated exports.

Every version has at least one page. A single-page form has exactly one form_pages row; the builder hides the page chrome, but the data shape never varies, so switching a form from single-page to multi-page is not a migration.

5.8.5 logic_rules (projection) #

UNIQUE (form_version_id, rule_id). Indexes: (form_version_id, position) for ordered evaluation; GIN (referenced_field_ids) for the reverse dependency lookup.

5.8.6 calculations (projection) #

UNIQUE (form_version_id, calc_id), UNIQUE (form_version_id, target_field_id) — a calculated field has exactly one calculation. Index (form_version_id, position).

5.9 The form-definition document #

5.9.1 Shape #

FormDefinition
├── schemaVersion : 1
├── formId, title, description, language
├── settings   { submitLabel, showProgress, allowPartial, closeBehaviour, … }
├── theme      { primary, background, font, radius, … }
├── pages[]    { id: pag_…, title, description, showProgress }
├── fields[]   flat, ordered, each carries pageId  (discriminated union on `type`)
├── logic[]    { id: rul_…, scope, condition, actions }
├── calculations[] { id: clc_…, targetFieldId, expression, outputType, … }
└── meta       { createdWith, generatedBy, aiGenerationId }

Fields are a flat ordered array carrying a pageId, not nested inside pages. Reordering a field across pages is then a single property change rather than a move between arrays, the projection is a straight map, and drag-and-drop reorder never has to rewrite two collections atomically.

5.9.2 TypeScript types #

// packages/schemas/src/forms/definition.types.ts
export type FieldId   = `fld_${string}`;
export type PageId    = `pag_${string}`;
export type RuleId    = `rul_${string}`;
export type CalcId    = `clc_${string}`;
Section 8.1 is the authority for `FIELD_TYPES`. The `field_type` Postgres enum in Section 5.4.1 is generated from it and must equal it exactly.

/** The eighteen. Section 5.4.1 is the authority; this union must equal it exactly. */
export type FieldType =
  // 15 answerable
  | 'short_text' | 'long_text' | 'email' | 'phone'
  | 'number' | 'currency'
  | 'dropdown' | 'multi_select'
  | 'date' | 'file_upload' | 'rating' | 'signature' | 'consent'
  | 'hidden' | 'payment'
  // 3 structural
  | 'page_break' | 'section_heading' | 'static_content';

export const ANSWERABLE_TYPES = [
  'short_text', 'long_text', 'email', 'phone', 'number', 'currency',
  'dropdown', 'multi_select', 'date', 'file_upload', 'rating',
  'signature', 'consent', 'hidden', 'payment',
] as const satisfies readonly FieldType[];

export const STRUCTURAL_TYPES = [
  'page_break', 'section_heading', 'static_content',
] as const satisfies readonly FieldType[];

export type PiiClass =
  | 'none' | 'contact' | 'identity' | 'financial'
  | 'health' | 'biometric' | 'location' | 'other';

export interface Choice {
  id: OptionId;           // stable across versions; see Section 5.2
  label: string;          // ≤ 200 chars, unique per field after trim and case-fold
  value: string;          // ≤ 200 chars, ^[\w .@:/+-]+$; defaults to the label
}


> **Normative precedence — the field object is defined in Section 8, not here.** The common field
> properties, the per-type `settings` and `validation` sub-objects, and the Zod schema are declared
> once in Section 8.2.1 and Sections 8.4.1–8.4.18, and that declaration is the one every other
> section consumes. The TypeScript and Zod shapes reproduced below are an illustrative projection of
> it for schema-generation purposes only. Where the two differ in property name, nesting or length
> limit, **Section 8 wins and this projection must be regenerated to match it** — in particular
> `key` (not `name`), `hiddenByDefault` (not `hidden`), `prefill.enabled` (not `prefillKey`), and
> type-specific configuration nested under `settings`/`validation` rather than promoted to the top
> level. `FormDefinition.fields[]` is a discriminated union on `type` over exactly the eighteen
> members of `FIELD_TYPES` declared in Section 8.1, imported from the shared schema package. A
> second independent declaration of the field shape or of the type list is the defect the lint rule
> in Section 8.11 exists to catch.

export interface FieldBase {
  id: FieldId;
  pageId: PageId;
  type: FieldType;
  name: string;                 // export key, ^[a-z][a-z0-9_]{0,62}$, unique per definition
  label: string;                // ≤ 500 chars
  description?: string;         // ≤ 2000 chars
  placeholder?: string;         // ≤ 200 chars
  helpText?: string;            // ≤ 500 chars
  required: boolean;
  pii: boolean;
  piiClass: PiiClass;
  hidden: boolean;              // initial visibility; logic may reveal
  readOnly: boolean;
  width: 'full' | 'half' | 'third';
  prefillKey?: string;          // URL query parameter name, ^[A-Za-z0-9_-]{1,40}$
  defaultValue?: unknown;       // must satisfy the field's own value schema
}

export interface TextField extends FieldBase {
  type: 'short_text' | 'long_text' | 'email' | 'phone';
  minLength?: number;           // 0 … 10000
  maxLength?: number;           // 1 … 10000, default 255 short / 5000 long
  format?: 'any' | 'letters_only' | 'alphanumeric' | 'no_digits' | 'custom';
  pattern?: string;             // RE2-safe subset, ≤ 200 chars, format === 'custom'
  patternMessage?: string;
  rows?: number;                // long_text only, 2 … 20
  confirmEntry?: boolean;       // email only — renders a "confirm" companion input
  allowedEmailDomains?: string[]; // email only, ≤ 20 entries
  phoneDefaultCountry?: string; // phone only, ISO 3166-1 alpha-2
  phoneAllowedCountries?: string[];
}

export interface NumericField extends FieldBase {
  type: 'number' | 'currency';
  display?: 'input' | 'stepper' | 'slider';   // number only
  min?: number; max?: number; step?: number;
  decimals?: number;            // 0 … 6
  currency?: string;            // ISO 4217, required for `currency`
  allowRespondentCurrency?: boolean;          // currency only
  allowedCurrencies?: string[];               // currency only, ISO 4217
  symbolPosition?: 'before' | 'after';        // currency only
  unitPrefix?: string; unitSuffix?: string;   // number only
  /** Present when this field is computed. The calculation itself is in `calculations`. */
  calcId?: CalcId;
}

export interface RatingField extends FieldBase {
  type: 'rating';
  style: 'stars' | 'numbers' | 'emoji' | 'nps';
  scale: number;                // 2 … 10, forced to 11 for style 'nps'
  startAtZero: boolean;
  allowHalf: boolean;           // 'stars' only
  emojiSet?: 'faces' | 'hearts' | 'thumbs';
  lowLabel?: string; highLabel?: string;      // ≤ 40 chars each
}

export interface DateField extends FieldBase {
  type: 'date';
  mode: 'date' | 'date_time' | 'time' | 'date_range';
  minDate?: string;             // ISO date, or 'today', or 'today+N' / 'today-N'
  maxDate?: string;
  excludedWeekdays?: number[];  // 0 = Sunday
  excludedDates?: string[];     // ≤ 200 ISO dates
  timeStepMinutes?: 1 | 5 | 10 | 15 | 30 | 60;
  timeZoneMode: 'respondent_local' | 'fixed';
  timeZone?: string;            // IANA, required when timeZoneMode is 'fixed'
  displayFormat: 'locale' | 'DD/MM/YYYY' | 'MM/DD/YYYY' | 'YYYY-MM-DD';
  firstDayOfWeek: 'locale' | 'sunday' | 'monday';
}

export interface ChoiceField extends FieldBase {
  type: 'dropdown' | 'multi_select';
  choices: Choice[];            // 1 … 200
  /** dropdown: how the single choice renders. multi_select: how the set renders. */
  display: 'dropdown' | 'radio' | 'buttons' | 'checkboxes';
  minSelections?: number;       // multi_select only, 0 … 200
  maxSelections?: number;       // multi_select only, 1 … 200
  exclusiveOptionIds?: OptionId[];            // multi_select only — "None of the above"
  randomise: boolean;
  searchable: boolean;
  separateValues: boolean;      // false = value tracks label
  allowOther: boolean;
  placeholder?: string;         // dropdown display only
}

export interface FileUploadField extends FieldBase {
  type: 'file_upload';
  maxFiles: number;             // 1 … 20
  maxFileSizeBytes: number;     // rejected at publish when above the plan cap (Section 19)
  acceptedGroups: Array<'images'|'documents'|'spreadsheets'|'presentations'
                        |'pdf'|'audio'|'video'|'archives'>;
  acceptedExtensions: string[]; // ≤ 30 entries, each ^\.[a-z0-9]{1,10}$
  showPreview: boolean;
  buttonLabel?: string;
}

export interface SignatureField extends FieldBase {
  type: 'signature';
  penColor: string;             // #rrggbb
  requireTypedName: boolean;
  statement?: string;           // ≤ 1000 chars; its hash is stored with the signature
}

export interface ConsentField extends FieldBase {
  type: 'consent';
  statement: string;            // 1 … 1000 chars, restricted rich text (Section 8.4.13)
  purpose: 'marketing' | 'terms' | 'privacy_policy'
         | 'data_processing' | 'age_confirmation' | 'other';
}

export interface PaymentField extends FieldBase {
  type: 'payment';
  currency: string;                       // ISO 4217

> **Normative precedence — the payment field is configured in Section 18.3.** Section 8.4.15 assigns
> ownership of the payment field's configuration to Section 18, and Section 18.3 is the single
> definition: its `mode` vocabulary (`fixed`, `calculated`, `products`, `open`) and its property names
> are authoritative. Any payment-field shape reproduced elsewhere is an illustrative projection and
> must be regenerated to match Section 18.3; where they differ, Section 18.3 wins.

  mode: 'fixed' | 'variable' | 'calculated' | 'quantity';
  amountMinor?: number;                   // fixed
  minAmountMinor?: number; maxAmountMinor?: number;  // variable
  calcId?: CalcId;                        // calculated
  unitAmountMinor?: number; maxQuantity?: number;    // quantity
  methods: Array<'card' | 'link' | 'apple_pay' | 'google_pay'>;
  collectBillingAddress: boolean;
  descriptorSuffix?: string;              // ≤ 22 chars
}

export interface HiddenField extends FieldBase {
  type: 'hidden';
  source: 'url_parameter' | 'fixed_value' | 'system';
  parameterName?: string;       // ^[A-Za-z0-9_.-]{1,64}$
  fixedValue?: string;          // ≤ 500 chars
  systemValue?: 'referrer' | 'landing_page' | 'user_agent'
              | 'submitted_at' | 'form_version' | 'language';
  maxLength: number;            // 1 … 2000, default 500
  showInTable: boolean;
}

/** Structural fields carry no answer, so they carry none of the answer-bearing properties. */
export interface StructuralFieldBase extends Omit<FieldBase,
  'required' | 'pii' | 'piiClass' | 'name' | 'prefillKey' | 'defaultValue' | 'readOnly'> {
  required?: never; pii?: never; piiClass?: never; name?: never;
}

export interface PageBreakField extends StructuralFieldBase {
  type: 'page_break';
  /** These describe the page that FOLLOWS the break. Page 1 is described in FormSettings. */
  pageTitle?: string;           // ≤ 120 chars
  pageDescription?: string;     // ≤ 500 chars
  nextLabel: string;            // label on the button that leaves the PRECEDING page
  showBack: boolean;
}

export interface SectionHeadingField extends StructuralFieldBase {
  type: 'section_heading';
  text: string;                 // 1 … 200 chars
  description?: string;         // ≤ 1000 chars, plain text
  level: 'h2' | 'h3';
  divider: boolean;
}

export interface StaticContentField extends StructuralFieldBase {
  type: 'static_content';
  contentType: 'rich_text' | 'image' | 'video' | 'divider';
  html?: string;                // sanitised allow-list, ≤ 5000 chars of text
  image?: { url: string; alt: string; decorative: boolean;
            maxWidthPx?: number; align?: 'left' | 'center' | 'right' };
  video?: { url: string; title: string; posterUrl?: string };
  divider?: { thicknessPx: number; spacingPx: number };
}

export type FormField =
  | TextField | NumericField | RatingField | DateField | ChoiceField
  | FileUploadField | SignatureField | ConsentField | PaymentField | HiddenField
  | PageBreakField | SectionHeadingField | StaticContentField;

/**
 * Pages are DERIVED, not authored. `pages` is the materialised page list computed from the
 * ordered positions of `page_break` fields; it is written into the document at save time so the
 * runtime and the projection never have to recompute it, and Section 5.8.4 mirrors it.
 */
export interface FormPageDef {
  id: PageId;
  /** The page_break field that opens this page. Null for page 1, which has no preceding break. */
  openedByFieldId: FieldId | null;
  title?: string;
  description?: string;
  showProgress: boolean;
}

/**
 * Logic. The operator catalogue, evaluation order and forward-reference rule are Section 9;
 * this is the storage shape those rules are persisted in, and the two must not diverge.
 */
export type ConditionOperator =
  | 'equals' | 'not_equals' | 'contains' | 'not_contains'
  | 'starts_with' | 'ends_with'
  | 'greater_than' | 'greater_or_equal' | 'less_than' | 'less_or_equal'
  | 'between' | 'is_empty' | 'is_not_empty'
  | 'is_any_of' | 'is_none_of' | 'before' | 'after' | 'is_true' | 'is_false';

export interface Condition {
  id: `cnd_${string}`;
  fieldId: FieldId;
  operator: ConditionOperator;
  value?: unknown;
  value2?: unknown;             // `between` upper bound
}

export interface ConditionGroup {
  combinator: 'and' | 'or';
  items: Array<Condition | ConditionGroup>;   // 1 … 20 items, nesting depth ≤ 2
}

export type RuleTarget =
  | { type: 'field'; fieldId: FieldId }
  | { type: 'page';  pageId: PageId }
  | { type: 'form' };                          // the only valid target for `submit`

export type RuleAction =
  | { kind: 'show' }
  | { kind: 'hide' }
  | { kind: 'require' }
  | { kind: 'optional' }
  | { kind: 'jump_to'; pageId: PageId }
  | { kind: 'submit' };

export interface LogicRuleDef {
  id: RuleId;
  name?: string;
  /** Ascending, contiguous from 0, per target. The last matching rule wins (Section 9.1). */
  order: number;
  enabled: boolean;
  target: RuleTarget;
  action: RuleAction;
  when: ConditionGroup;
}

export interface CalculationDef {
  id: CalcId;
  /** A `number` or `currency` field, or a `payment` field in `calculated` mode. */
  targetFieldId: FieldId;
  expression: string;           // ≤ 1000 chars of source, grammar in Section 9.7.1
  outputType: 'number' | 'money';
  precision: number;            // 0 … 6; forced to the currency exponent for money
  rounding: 'half_up' | 'half_down' | 'down' | 'up' | 'ceil' | 'floor';
  currency?: string;
  onErrorShow: string;          // ≤ 40 chars, default '—'
  blockSubmitOnError: boolean;
}

/**
 * Precomputed at publish so the runtime never sorts a graph on the respondent's critical path
 * (Section 9.4). Stored in the document and mirrored to `form_versions.definition`.
 */
export interface EvaluationPlan {
  calculationOrder: CalcId[];               // topological
  ruleOrderByTarget: Record<string, RuleId[]>;
}

export interface FormSettings {
  submitLabel: string;
  showProgress: boolean;
  oneQuestionPerPage: boolean;
  allowPartialCapture: boolean;      // Pro+ (Section 19)
  allowResume: boolean;
  saveAndResumeEmail: boolean;
  shuffleQuestions: boolean;
  confirmationMode: 'message' | 'redirect';
  confirmationMessage?: string;
  redirectUrl?: string;
  respondentReceipt: boolean;
  receiptEmailFieldId?: FieldId;
  limitOneResponsePerBrowser: boolean;
  honeypotEnabled: boolean;          // always true in practice (Section 15)
  captchaMode: 'off' | 'invisible' | 'always';
  showBadge: boolean;                // forced true on Free
  autosaveIntervalMs: number;        // 2000 … 30000
}

export interface FormTheme {
  primary: string; background: string; text: string;
  font: 'system' | 'inter' | 'serif' | 'mono';
  radius: 'none' | 'sm' | 'md' | 'lg';
  buttonStyle: 'solid' | 'outline';
  logoUrl?: string; coverImageUrl?: string;
  density: 'compact' | 'comfortable';
}

export interface FormDefinition {
  schemaVersion: 1;
  formId: `frm_${string}`;
  title: string;
  description?: string;
  language: string;
  settings: FormSettings;
  theme: FormTheme;
  pages: FormPageDef[];
  fields: FormField[];
  logic: LogicRuleDef[];
  calculations: CalculationDef[];
  evaluationPlan: EvaluationPlan;
  meta: {
    createdWith: 'builder' | 'ai' | 'import' | 'template';
    generatedBy?: string;
    aiGenerationId?: `gen_${string}`;
  };
}

5.9.3 Zod schema #

The Zod schema lives in the shared validation package and is imported unchanged by the builder, the respondent runtime, and the route handlers — one definition of every rule, per Section 4. It is the runtime authority; the TypeScript types above are the compile-time authority; a type assertion keeps them identical.

// packages/schemas/src/forms/form-definition.ts
import { z } from 'zod';
import type { FormDefinition } from './definition.types';

const prefixed = (p: string) =>
  z.string().regex(new RegExp(`^${p}_[0-9A-HJKMNP-TV-Z]{26}$`), `expected a ${p}_ identifier`);

const fieldId  = prefixed('fld');
const pageId   = prefixed('pag');
const ruleId   = prefixed('rul');
const calcId   = prefixed('clc');
const optionId = prefixed('opt');
const condId   = prefixed('cnd');
const hexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/);
const iso4217  = z.string().regex(/^[A-Z]{3}$/);
const iso3166  = z.string().regex(/^[A-Z]{2}$/);
const exportName = z.string().regex(/^[a-z][a-z0-9_]{0,62}$/);
const optionValue = z.string().min(1).max(200).regex(/^[\w .@:/+-]+$/);

export const choiceSchema = z.object({
  id: optionId,
  label: z.string().min(1).max(200),
  value: optionValue,
});


> **Normative precedence — the field object is defined in Section 8, not here.** The common field
> properties, the per-type `settings` and `validation` sub-objects, and the Zod schema are declared
> once in Section 8.2.1 and Sections 8.4.1–8.4.18, and that declaration is the one every other
> section consumes. The TypeScript and Zod shapes reproduced below are an illustrative projection of
> it for schema-generation purposes only. Where the two differ in property name, nesting or length
> limit, **Section 8 wins and this projection must be regenerated to match it** — in particular
> `key` (not `name`), `hiddenByDefault` (not `hidden`), `prefill.enabled` (not `prefillKey`), and
> type-specific configuration nested under `settings`/`validation` rather than promoted to the top
> level. `FormDefinition.fields[]` is a discriminated union on `type` over exactly the eighteen
> members of `FIELD_TYPES` declared in Section 8.1, imported from the shared schema package. A
> second independent declaration of the field shape or of the type list is the defect the lint rule
> in Section 8.11 exists to catch.

const fieldBase = {
  id: fieldId,
  pageId,
  name: exportName,
  label: z.string().min(1).max(500),
  description: z.string().max(2000).optional(),
  placeholder: z.string().max(200).optional(),
  helpText: z.string().max(500).optional(),
  required: z.boolean().default(false),
  pii: z.boolean().default(false),
  piiClass: z.enum(['none','contact','identity','financial','health','biometric','location','other'])
            .default('none'),
  hidden: z.boolean().default(false),
  readOnly: z.boolean().default(false),
  width: z.enum(['full','half','third']).default('full'),
  prefillKey: z.string().regex(/^[A-Za-z0-9_-]{1,40}$/).optional(),
  defaultValue: z.unknown().optional(),
};

const structuralBase = {
  id: fieldId, pageId,
  label: z.string().max(500).default(''),
  description: z.string().max(2000).optional(),
  hidden: z.boolean().default(false),
  width: z.enum(['full','half','third']).default('full'),
};

/** Exactly eighteen members, in the order of Section 5.4.1. */
export const formFieldSchema = z.discriminatedUnion('type', [
  z.object({ ...fieldBase,
    type: z.enum(['short_text','long_text','email','phone']),
    minLength: z.int().min(0).max(10_000).optional(),
    maxLength: z.int().min(1).max(10_000).optional(),
    format: z.enum(['any','letters_only','alphanumeric','no_digits','custom']).default('any'),
    pattern: z.string().max(200).optional(),
    patternMessage: z.string().max(200).optional(),
    rows: z.int().min(2).max(20).optional(),
    confirmEntry: z.boolean().default(false),
    allowedEmailDomains: z.array(z.string().max(253)).max(20).optional(),
    phoneDefaultCountry: iso3166.optional(),
    phoneAllowedCountries: z.array(iso3166).max(250).optional(),
  }).refine(f => f.minLength === undefined || f.maxLength === undefined || f.minLength <= f.maxLength,
      { message: 'minLength must not exceed maxLength', path: ['minLength'] })
    .refine(f => f.format !== 'custom' || !!f.pattern,
      { message: 'a custom format requires a pattern', path: ['pattern'] })
    .refine(f => f.rows === undefined || f.type === 'long_text',
      { message: 'rows applies to long_text only', path: ['rows'] }),

  z.object({ ...fieldBase,
    type: z.enum(['number','currency']),
    display: z.enum(['input','stepper','slider']).default('input'),
    min: z.number().optional(), max: z.number().optional(), step: z.number().positive().optional(),
    decimals: z.int().min(0).max(6).optional(),
    currency: iso4217.optional(),
    allowRespondentCurrency: z.boolean().default(false),
    allowedCurrencies: z.array(iso4217).max(50).optional(),
    symbolPosition: z.enum(['before','after']).optional(),
    unitPrefix: z.string().max(8).optional(), unitSuffix: z.string().max(8).optional(),
    calcId: calcId.optional(),
  }).refine(f => f.type !== 'currency' || !!f.currency,
      { message: 'currency fields require an ISO 4217 currency', path: ['currency'] })
    .refine(f => f.min === undefined || f.max === undefined || f.min <= f.max,
      { message: 'min must not exceed max', path: ['min'] })
    .refine(f => !f.calcId || f.readOnly !== false,
      { message: 'a computed field is read-only', path: ['readOnly'] }),

  z.object({ ...fieldBase,
    type: z.literal('rating'),
    style: z.enum(['stars','numbers','emoji','nps']).default('stars'),
    scale: z.int().min(2).max(11).default(5),
    startAtZero: z.boolean().default(false),
    allowHalf: z.boolean().default(false),
    emojiSet: z.enum(['faces','hearts','thumbs']).optional(),
    lowLabel: z.string().max(40).optional(), highLabel: z.string().max(40).optional(),
  }).refine(f => f.style !== 'nps' || f.scale === 11,
      { message: 'nps style is fixed at an 11-point scale', path: ['scale'] })
    .refine(f => !f.allowHalf || f.style === 'stars',
      { message: 'half steps apply to the stars style only', path: ['allowHalf'] }),

  z.object({ ...fieldBase,
    type: z.literal('date'),
    mode: z.enum(['date','date_time','time','date_range']).default('date'),
    minDate: z.union([z.iso.date(), z.string().regex(/^today([+-]\d{1,4})?$/)]).optional(),
    maxDate: z.union([z.iso.date(), z.string().regex(/^today([+-]\d{1,4})?$/)]).optional(),
    excludedWeekdays: z.array(z.int().min(0).max(6)).max(7).default([]),
    excludedDates: z.array(z.iso.date()).max(200).default([]),
    timeStepMinutes: z.union([z.literal(1),z.literal(5),z.literal(10),
                              z.literal(15),z.literal(30),z.literal(60)]).default(15),
    timeZoneMode: z.enum(['respondent_local','fixed']).default('respondent_local'),
    timeZone: z.string().max(64).optional(),
    displayFormat: z.enum(['locale','DD/MM/YYYY','MM/DD/YYYY','YYYY-MM-DD']).default('locale'),
    firstDayOfWeek: z.enum(['locale','sunday','monday']).default('locale'),
  }).refine(f => f.timeZoneMode !== 'fixed' || !!f.timeZone,
    { message: 'a fixed time zone requires an IANA identifier', path: ['timeZone'] }),

  z.object({ ...fieldBase,
    type: z.enum(['dropdown','multi_select']),
    choices: z.array(choiceSchema).min(1).max(200)
      .refine(cs => new Set(cs.map(c => c.value)).size === cs.length, 'option values must be unique')
      .refine(cs => new Set(cs.map(c => c.id)).size === cs.length, 'option ids must be unique'),
    display: z.enum(['dropdown','radio','buttons','checkboxes']).default('radio'),
    minSelections: z.int().min(0).max(200).optional(),
    maxSelections: z.int().min(1).max(200).optional(),
    exclusiveOptionIds: z.array(optionId).max(200).default([]),
    randomise: z.boolean().default(false),
    searchable: z.boolean().default(false),
    separateValues: z.boolean().default(false),
    allowOther: z.boolean().default(false),
    placeholder: z.string().max(120).optional(),
  }).refine(f => f.maxSelections === undefined || f.maxSelections <= f.choices.length,
      { message: 'maxSelections exceeds the number of options', path: ['maxSelections'] })
    .refine(f => f.type === 'multi_select'
              || (f.minSelections === undefined && f.maxSelections === undefined
                  && f.exclusiveOptionIds.length === 0),
      { message: 'selection bounds apply to multi_select only', path: ['minSelections'] })
    .refine(f => f.exclusiveOptionIds.every(id => f.choices.some(c => c.id === id)),
      { message: 'exclusive options must be options of this field', path: ['exclusiveOptionIds'] }),

  z.object({ ...fieldBase,
    type: z.literal('file_upload'),
    maxFiles: z.int().min(1).max(20).default(1),
    maxFileSizeBytes: z.int().min(1).max(104_857_600).default(10_485_760),
    acceptedGroups: z.array(z.enum(['images','documents','spreadsheets','presentations',
                                    'pdf','audio','video','archives']))
                     .max(8).default(['images','documents','pdf']),
    acceptedExtensions: z.array(z.string().regex(/^\.[a-z0-9]{1,10}$/)).max(30).default([]),
    showPreview: z.boolean().default(true),
    buttonLabel: z.string().max(60).optional(),
  }),

  z.object({ ...fieldBase,
    type: z.literal('signature'),
    penColor: hexColor.default('#111111'),
    requireTypedName: z.boolean().default(false),
    statement: z.string().max(1000).optional(),
  }),

  z.object({ ...fieldBase,
    type: z.literal('consent'),
    statement: z.string().min(1).max(1000),
    purpose: z.enum(['marketing','terms','privacy_policy',
                     'data_processing','age_confirmation','other']).default('other'),
  }).refine(f => f.required || f.purpose === 'marketing' || f.purpose === 'other',
    { message: 'terms, privacy and age consent are always required', path: ['required'] }),

  z.object({ ...fieldBase,
    type: z.literal('payment'),
    currency: iso4217,
    mode: z.enum(['fixed','variable','calculated','quantity']),
    amountMinor: z.int().min(0).optional(),
    minAmountMinor: z.int().min(0).optional(),
    maxAmountMinor: z.int().min(0).optional(),
    calcId: calcId.optional(),
    unitAmountMinor: z.int().min(0).optional(),
    maxQuantity: z.int().min(1).max(999).optional(),
    methods: z.array(z.enum(['card','link','apple_pay','google_pay'])).min(1),
    collectBillingAddress: z.boolean().default(false),
    descriptorSuffix: z.string().max(22).optional(),
  }).superRefine((f, ctx) => {
    const need = (cond: boolean, path: string, msg: string) => {
      if (!cond) ctx.addIssue({ code: 'custom', path: [path], message: msg });
    };
    if (f.mode === 'fixed')      need(f.amountMinor !== undefined, 'amountMinor', 'required for fixed mode');
    if (f.mode === 'variable')   need(f.minAmountMinor !== undefined && f.maxAmountMinor !== undefined,
                                      'minAmountMinor', 'variable mode requires a min and a max');
    if (f.mode === 'calculated') need(!!f.calcId, 'calcId', 'required for calculated mode');
    if (f.mode === 'quantity')   need(f.unitAmountMinor !== undefined, 'unitAmountMinor', 'required for quantity mode');
  }),

  z.object({ ...fieldBase,
    type: z.literal('hidden'),
    source: z.enum(['url_parameter','fixed_value','system']).default('url_parameter'),
    parameterName: z.string().regex(/^[A-Za-z0-9_.-]{1,64}$/).optional(),
    fixedValue: z.string().max(500).optional(),
    systemValue: z.enum(['referrer','landing_page','user_agent',
                         'submitted_at','form_version','language']).optional(),
    maxLength: z.int().min(1).max(2000).default(500),
    showInTable: z.boolean().default(true),
  }).refine(f => f.required === false,
      { message: 'a hidden field can never be required', path: ['required'] })
    .refine(f => f.source !== 'system' || !!f.systemValue,
      { message: 'a system-sourced hidden field must name its system value', path: ['systemValue'] }),

  z.object({ ...structuralBase,
    type: z.literal('page_break'),
    pageTitle: z.string().max(120).default(''),
    pageDescription: z.string().max(500).default(''),
    nextLabel: z.string().min(1).max(60).default('Next'),
    showBack: z.boolean().default(true),
  }),

  z.object({ ...structuralBase,
    type: z.literal('section_heading'),
    text: z.string().min(1).max(200),
    description: z.string().max(1000).default(''),
    level: z.enum(['h2','h3']).default('h3'),
    divider: z.boolean().default(false),
  }),

  z.object({ ...structuralBase,
    type: z.literal('static_content'),
    contentType: z.enum(['rich_text','image','video','divider']).default('rich_text'),
    html: z.string().max(20_000).optional(),
    image: z.object({
      url: z.url().max(2048),
      alt: z.string().max(250).default(''),
      decorative: z.boolean().default(false),
      maxWidthPx: z.int().min(16).max(2000).optional(),
      align: z.enum(['left','center','right']).default('left'),
    }).optional(),
    video: z.object({
      url: z.url().max(2048), title: z.string().min(1).max(200),
      posterUrl: z.url().max(2048).optional(),
    }).optional(),
    divider: z.object({
      thicknessPx: z.int().min(1).max(8).default(1),
      spacingPx: z.int().min(0).max(96).default(24),
    }).optional(),
  }).refine(f => f.contentType !== 'image' || !!f.image,
      { message: 'image content requires an image', path: ['image'] })
    .refine(f => !f.image || f.image.decorative || f.image.alt.length > 0,
      { message: 'images require alternative text unless marked decorative', path: ['image','alt'] })
    .refine(f => f.contentType !== 'video' || !!f.video,
      { message: 'video content requires a video', path: ['video'] }),
]);

const conditionSchema = z.object({
  id: condId,
  fieldId,
  operator: z.enum(['equals','not_equals','contains','not_contains','starts_with','ends_with',
    'greater_than','greater_or_equal','less_than','less_or_equal','between','is_empty',
    'is_not_empty','is_any_of','is_none_of','before','after','is_true','is_false']),
  value: z.unknown().optional(),
  value2: z.unknown().optional(),
});

export const conditionGroupSchema: z.ZodType<import('./definition.types').ConditionGroup> =
  z.lazy(() => z.object({
    combinator: z.enum(['and','or']),
    items: z.array(z.union([conditionSchema, conditionGroupSchema])).min(1).max(20),
  }));

export const logicRuleSchema = z.object({
  id: ruleId,
  name: z.string().max(120).optional(),
  order: z.int().min(0).max(199),
  enabled: z.boolean().default(true),
  target: z.discriminatedUnion('type', [
    z.object({ type: z.literal('field'), fieldId }),
    z.object({ type: z.literal('page'),  pageId }),
    z.object({ type: z.literal('form') }),
  ]),
  action: z.discriminatedUnion('kind', [
    z.object({ kind: z.literal('show') }),
    z.object({ kind: z.literal('hide') }),
    z.object({ kind: z.literal('require') }),
    z.object({ kind: z.literal('optional') }),
    z.object({ kind: z.literal('jump_to'), pageId }),
    z.object({ kind: z.literal('submit') }),
  ]),
  when: conditionGroupSchema,
}).refine(r => r.action.kind !== 'submit' || r.target.type === 'form',
  { message: 'submit targets the form', path: ['target'] });

export const calculationSchema = z.object({
  id: calcId,
  targetFieldId: fieldId,
  expression: z.string().min(1).max(1000),
  outputType: z.enum(['number','money']).default('number'),
  precision: z.int().min(0).max(6).default(2),
  rounding: z.enum(['half_up','half_down','down','up','ceil','floor']).default('half_up'),
  currency: iso4217.optional(),
  onErrorShow: z.string().max(40).default('—'),
  blockSubmitOnError: z.boolean().default(true),
}).refine(c => c.outputType !== 'money' || !!c.currency,
  { message: 'money calculations require a currency', path: ['currency'] });

export const formDefinitionSchema = z.object({
  schemaVersion: z.literal(1),
  formId: prefixed('frm'),
  title: z.string().min(1).max(200),
  description: z.string().max(2000).optional(),
  language: z.string().min(2).max(15).default('en'),
  settings: z.object({
    submitLabel: z.string().min(1).max(60).default('Submit'),
    showProgress: z.boolean().default(true),
    oneQuestionPerPage: z.boolean().default(false),
    allowPartialCapture: z.boolean().default(false),
    allowResume: z.boolean().default(false),
    saveAndResumeEmail: z.boolean().default(false),
    shuffleQuestions: z.boolean().default(false),
    confirmationMode: z.enum(['message','redirect']).default('message'),
    confirmationMessage: z.string().max(5000).optional(),
    redirectUrl: z.url().max(2048).optional(),
    respondentReceipt: z.boolean().default(false),
    receiptEmailFieldId: fieldId.optional(),
    limitOneResponsePerBrowser: z.boolean().default(false),
    honeypotEnabled: z.boolean().default(true),
    captchaMode: z.enum(['off','invisible','always']).default('invisible'),
    showBadge: z.boolean().default(true),
    autosaveIntervalMs: z.int().min(2000).max(30_000).default(5000),
  }),
  theme: z.object({
    primary: hexColor.default('#2563eb'),
    background: hexColor.default('#ffffff'),
    text: hexColor.default('#111827'),
    font: z.enum(['system','inter','serif','mono']).default('system'),
    radius: z.enum(['none','sm','md','lg']).default('md'),
    buttonStyle: z.enum(['solid','outline']).default('solid'),
    logoUrl: z.url().max(2048).optional(),
    coverImageUrl: z.url().max(2048).optional(),
    density: z.enum(['compact','comfortable']).default('comfortable'),
  }),
  pages: z.array(z.object({
    id: pageId,
    openedByFieldId: fieldId.nullable(),
    title: z.string().max(120).optional(),
    description: z.string().max(500).optional(),
    showProgress: z.boolean().default(true),
  })).min(1).max(51),                     // page 1 plus at most 50 page breaks
  fields: z.array(formFieldSchema).max(300),
  logic: z.array(logicRuleSchema).max(200),
  calculations: z.array(calculationSchema).max(50),
  evaluationPlan: z.object({
    calculationOrder: z.array(calcId).max(50),
    ruleOrderByTarget: z.record(z.string(), z.array(ruleId)),
  }),
  meta: z.object({
    createdWith: z.enum(['builder','ai','import','template']).default('builder'),
    generatedBy: z.string().max(120).optional(),
    aiGenerationId: prefixed('gen').optional(),
  }),
}).superRefine((def, ctx) => {
  const issue = (path: (string|number)[], message: string) =>
    ctx.addIssue({ code: 'custom', path, message });

  const pageIds  = new Set(def.pages.map(p => p.id));
  const fieldIds = new Set<string>();
  const names    = new Set<string>();

  if (pageIds.size !== def.pages.length) issue(['pages'], 'page ids must be unique');

  def.fields.forEach((f, i) => {
    if (fieldIds.has(f.id)) issue(['fields', i, 'id'], 'duplicate field id');
    fieldIds.add(f.id);
    if (!pageIds.has(f.pageId)) issue(['fields', i, 'pageId'], 'unknown page');
    if ('name' in f) {
      if (names.has(f.name)) issue(['fields', i, 'name'], 'duplicate export name');
      names.add(f.name);
    }
  });

  // every referenced field/page must exist
  def.logic.forEach((r, i) => {
    const walk = (g: any, p: (string|number)[]) => g.items.forEach((c: any, j: number) =>
      'combinator' in c ? walk(c, [...p, 'items', j])
        : (!fieldIds.has(c.fieldId) && issue([...p, 'items', j, 'fieldId'], 'unknown field')));
    walk(r.when, ['logic', i, 'when']);
    if (r.target.type === 'field' && !fieldIds.has(r.target.fieldId))
      issue(['logic', i, 'target', 'fieldId'], 'unknown field');
    if (r.target.type === 'page' && !pageIds.has(r.target.pageId))
      issue(['logic', i, 'target', 'pageId'], 'unknown page');
    if (r.action.kind === 'jump_to' && !pageIds.has(r.action.pageId))
      issue(['logic', i, 'action', 'pageId'], 'unknown page');
  });

  // calculations: target exists, is a computable type, no duplicate targets, no cycles
  const calcIds = new Set(def.calculations.map(c => c.id));
  const byId = new Map(def.fields.map(f => [f.id, f]));
  const targets = new Set<string>();
  def.calculations.forEach((c, i) => {
    const t = byId.get(c.targetFieldId);
    if (!t) issue(['calculations', i, 'targetFieldId'], 'unknown field');
    else if (!['number','currency','payment'].includes(t.type))
      issue(['calculations', i, 'targetFieldId'],
            'only number, currency and payment fields can be computed');
    if (targets.has(c.targetFieldId)) issue(['calculations', i, 'targetFieldId'], 'duplicate target');
    targets.add(c.targetFieldId);
  });
  def.fields.forEach((f, i) => {
    if ((f.type === 'number' || f.type === 'currency') && f.calcId && !calcIds.has(f.calcId))
      issue(['fields', i, 'calcId'], 'unknown calculation');
    if (f.type === 'payment' && f.mode === 'calculated' && f.calcId && !calcIds.has(f.calcId))
      issue(['fields', i, 'calcId'], 'unknown calculation');
  });
  if (hasCycle(def.calculations)) issue(['calculations'], 'calculation dependency cycle');

  // page structure: derived pages must agree with the page_break fields
  const breaks = def.fields.filter(f => f.type === 'page_break');
  if (def.pages.length !== breaks.length + 1)
    issue(['pages'], 'the page list must contain exactly one more page than there are page breaks');
  if (def.fields[0]?.type === 'page_break')
    issue(['fields', 0], 'a page break cannot be the first field');
  if (def.fields.at(-1)?.type === 'page_break')
    issue(['fields', def.fields.length - 1], 'a page break cannot be the last field');
  def.fields.forEach((f, i) => {
    if (f.type === 'page_break' && def.fields[i - 1]?.type === 'page_break')
      issue(['fields', i], 'two consecutive page breaks produce an empty page');
  });

  // at most one payment field, and it is last
  const payments = def.fields.filter(f => f.type === 'payment');
  if (payments.length > 1) issue(['fields'], 'a form can have only one payment field');
  if (payments.length === 1 && def.fields.at(-1)?.id !== payments[0].id)
    issue(['fields'], 'the payment field must be the last field of the last page');

  // receipt target must be an email field
  if (def.settings.receiptEmailFieldId) {
    const target = byId.get(def.settings.receiptEmailFieldId);
    if (!target || target.type !== 'email')
      issue(['settings','receiptEmailFieldId'], 'must reference an email field');
  }

  // the evaluation plan must cover every calculation exactly once
  if (new Set(def.evaluationPlan.calculationOrder).size !== def.calculations.length)
    issue(['evaluationPlan','calculationOrder'], 'the plan must cover every calculation once');
});

export type ParsedFormDefinition = z.infer<typeof formDefinitionSchema>;