Testimonial & Social Proof Platform

Vouch — Testimonial & Social Proof Platform #

Version: 1.0 — Final Document type: Product & engineering specification, written to be executed cold by an AI coding agent or a small engineering team.

Overview #

Vouch is a testimonial and social-proof platform. It collects written and video testimonials through branded, shareable request pages and one-click email and SMS invites; records video directly in the browser with no app install; auto-transcribes and captions that video, with automatic detection across five launch languages; moderates and tags every submission in an accountable inbox; and publishes the results anywhere through embeddable walls of love, carousels, single-quote widgets, and a public showcase page. It also imports existing reviews from Google, G2, Capterra, and X, turns approved quotes into shareable social image cards, and measures widget impressions and click-through without setting a single cookie.

The product is organised around one loop — Collect → Moderate → Publish → Measure — and every section of this document belongs to one of those four stages or to the platform foundations beneath them.

Four commitments shape almost every technical decision that follows, and they are worth stating before the detail begins:

1. The embed is the front door, and it is the hardest constraint in the system. Widgets are pasted into other people's websites. They ship as a tiny asynchronous script that never blocks render, carries no framework runtime, isolates itself in a shadow root so host CSS cannot break it and it cannot break the host, lazy-loads video, and adds effectively nothing to the host page's Core Web Vitals. Section 13.3 states that budget as measurable numbers with a hard CI gate behind each one.

2. Nothing already live ever breaks. Reaching a plan limit, downgrading, falling into dunning, or cancelling outright never degrades a widget that is already serving on a customer's homepage. Limits block new collection; they never touch published output. Section 19 states this as a numbered invariant.

3. Published customer quotes are reputational, so every action on them is attributable. Approvals, edits, publishes, and unpublishes all write to an append-only audit trail that answers "who put that live, and when?" in two clicks. Section 11.6 owns it.

4. The AI selects; it never rewrites. The highlight assistant proposes which of the respondent's own words to feature and which seconds of their video to clip. It never edits, paraphrases, corrects, or smooths what a customer actually said — and the platform enforces that in code, not by policy alone. Section 12.1 and Section 12.4 own the boundary and its enforcement.

Version 1 is single-workspace: each customer manages one brand. Multi-workspace and agency/white-label operation are deliberately deferred, but the tenancy seam is built from day one — every row is scoped by workspace, with no implicit "current organisation" anywhere in the codebase — so serving agencies later is additive rather than a rewrite. Section 6.3 describes exactly what is already in place and what a later version adds.

Each concern in this document has exactly one canonical section. Every other section references it by number rather than restating it. Where the specification was silent, a decision has been made and recorded rather than deferred; no open questions and no unresolved placeholders remain. An executing agent should be able to read this cold and begin work without needing to ask anything about the document itself.

Table of Contents #

1. Before You Start — Customization Decisions
2. Product Overview, Vision & Success Criteria
3. Technology Stack & System Architecture
4. Conventions, Code Standards & Project Structure
5. Data Model & Database Schema
6. Multi-Tenancy, Authentication, Authorization & Team Management
7. API Design — Internal Contract & Public REST API
8. Collection — Request Pages, Custom Fields & Invitations
9. Video Capture, Chunked Upload & Media Pipeline
10. Transcription, Captions & the Transcript Editor
11. Moderation Inbox, Tagging, Lifecycle & Audit Trail
12. AI Highlight Assistant
13. Widgets & the Embed SDK
14. Public Showcase Pages & Custom Domains
15. Social Image Card Generator
16. Review Import — Google, G2, Capterra, X & CSV
17. Analytics — Cookie-Free Impression & Click Measurement
18. Integrations — Webhooks, Zapier, Slack, HubSpot
19. Plans, Billing & Limit Enforcement
20. Notifications & Transactional Messaging
21. Accessibility — WCAG 2.2 Level AA
22. Security, Privacy, Consent & Compliance
23. Performance Budgets & Non-Functional Requirements
24. Observability, Operations & Runbooks
25. Testing Strategy & Quality Gates
26. Deployment, Environments & Configuration
27. Milestones & Execution Plan
28. Executor Instructions
29. Appendices

1. Before You Start — Customization Decisions #

This document is written to be executed cold, by an agent or a developer with no access to a product manager. Every question that could block execution has already been answered. This section exists so that the small number of answers you may legitimately want to change before writing code are collected in one place, each with a working default that is already wired through the rest of the document.

The rule that governs this entire section: never block. If you have no opinion on a decision below, take the default and move on. Every default is internally consistent with every other default and with the whole specification. If you do change one, this section tells you exactly what else moves.

Record whatever you change — and your reason — in docs/DECISIONS.md in your repository, one Architecture Decision Record per changed item, before you write the first line of code. That file is yours to maintain; this document will not track your deviations for you.

1.1 Decision Register #

1.2 The Decisions in Detail #

1.2.1 D1 — Product Name #

Default: Vouch. Short, pronounceable, semantically exact ("to vouch for someone" is literally what a testimonial is), and available as an npm scope shape (@vouch/*).

Why this default: the name appears in a lot of load-bearing places — an npm scope, a cookie name, a CSS custom-property prefix, a webhook signature header, an API key prefix, a global browser variable — and a short lowercase word with no punctuation keeps all of them legal without escaping.

What changes if you pick differently: nothing architectural. The rename is mechanical but it touches identifiers that are hard to change later, so do it before you write code, not after.

Rename procedure — perform all eleven steps, in order, before first commit:

A repository-wide case-sensitive search for vouch, Vouch, VOUCH, and vch after the rename must return zero results outside docs/DECISIONS.md. Add that search as a one-line CI check if you want the guarantee to hold.

Where it takes effect: Sections 3 (repo layout, Valkey keys), 5 (roles), 6 (cookie, roles), 7 (key prefixes, signature header, docsUrl), 13 (global, CSS prefix), 19 (badge), 20 (email templates), 29.2 (env var names are concern-prefixed, not brand-prefixed, so they do not change).

1.2.2 D2 — Domain Names #

Default:

Why this default: the loader host must be permanent and platform-owned, because the embed snippet a customer pastes into their site must never need to be re-pasted (Section 13). Splitting the public respondent surface (v.) from the cached asset surface (cdn.) lets cdn. run a long-lived, aggressively cached, cookie-free policy while v. can set short-lived caches and serve dynamic HTML.

What changes if you pick differently: substitute your hosts in configuration and DNS. The shape — a permanent CDN host, a short public host, an app host, a stable CNAME target for customer domains — must be preserved. Collapsing cdn. into v. is the one change that is genuinely harmful: it makes it impossible to serve widget assets under a cookie-free, credential-free origin, which the analytics design in Section 17 depends on.

Where it takes effect: Sections 3.4, 13, 14, 17, 26.

1.2.3 D3 — Cloud and Hosting Model #

Default: stateless application containers on a managed container platform with autoscaling and zero-downtime rolling deploys; managed PostgreSQL with point-in-time recovery; managed Valkey/Redis-protocol cache; S3-compatible object storage; a CDN in front of cdn. and edge..

Why this default: every component is commodity. Nothing in this specification requires a specific cloud. The application is a Next.js app plus a Node worker plus three stateful dependencies (Postgres, a Redis-protocol cache, object storage) and a CDN. Any platform that runs containers and offers those is sufficient.

What changes if you pick differently:

• Serverless functions instead of long-lived containers: the worker (apps/worker) needs long-running processes for BullMQ consumers and for chunked-upload session handling. If your platform has no long-lived compute, run the worker on a small always-on instance and keep the web tier serverless.
• Self-managed Postgres: you own backups, failover, and the extension set. Section 26 lists required extensions and settings.
• A single VM running everything: acceptable for a first deploy; Section 26 documents the minimum viable single-host topology and its limits.

Where it takes effect: Sections 3.4, 24, 26.

1.2.4 D4 — Object Storage Provider #

Default: Cloudflare R2, accessed through the S3-compatible API.

Why this default: R2 charges no egress fee. This product stores original video uploads and serves posters, social cards, and caption files from storage through a CDN; egress is the dominant cost driver and eliminating it changes the unit economics of the Free tier.

What changes if you pick differently: AWS S3 is a drop-in — the same SDK client, the same multipart upload API, the same pre-signed URL flow. Set the endpoint, region, and credentials in configuration (Section 29.2). Two behaviours to verify on any non-R2 provider: (a) multipart upload part size minimums, and (b) AbortMultipartUpload actually reclaiming storage, which the re-record flow in Section 9 depends on.

Where it takes effect: Sections 3, 9, 15, 22.

1.2.5 D5 — Video Host, Transcode, and Delivery #

Default: Mux.

Why this default: browser-recorded video arrives in whatever codec the respondent's device produced — H.264 in an MP4 on Safari, VP9 or VP8 in a WebM on Chrome and Firefox. Normalizing that into adaptive HLS that plays everywhere is a solved problem you should not solve. Mux additionally provides signed playback, per-asset thumbnails, and delivery analytics, which removes three subsystems from scope.

What changes if you pick differently: the media pipeline in Section 9 is expressed as five provider operations — create upload, get asset, get playback id, get thumbnail, delete asset — plus three webhooks. Any provider offering those fits. Self-hosted FFmpeg transcoding is explicitly out of scope for v1 (Section 2.7); choosing it means building transcode orchestration, an HLS packager, storage lifecycle, and a player, which is a multi-month project on its own.

Where it takes effect: Sections 3, 9, 13, 22, 24.

1.2.6 D6 — Transcription Provider #

Default: Deepgram, nova-3, of the nova model family. The model string is a configuration value read from the environment (Section 29.2), not a dependency version line, so a model upgrade is a configuration change rather than a deploy.

Why this default: word-level timings with per-word confidence are mandatory. The caption editor highlights low-confidence words (Section 10), and the AI highlight assistant clips video by segment boundaries (Section 12). A provider that returns only sentence-level text cannot support either feature.

Alternative: AssemblyAI, documented as a drop-in. It returns the same shape of data. Both adapters implement one interface: transcribe(mediaUrl, opts) → CanonicalTranscript, where CanonicalTranscript is the single JSONB structure defined in Section 10.3. Nothing downstream of that function knows which provider ran.

What changes if you pick differently: the adapter, one environment variable set, and the per-minute cost model behind the transcription quota in Section 19.

Where it takes effect: Sections 3, 10, 12, 19.

1.2.7 D7 — AI Provider #

Default: Anthropic Claude, via the AiProvider interface.

Why this default: the highlight assistant's outputs are constrained and validated server-side (Section 12.4), so provider choice is a quality-and-cost decision, not an architectural one. The default is a strong instruction-following model with reliable structured output.

Alternative: OpenAI, documented as a second adapter. The interface is three methods — suggestHighlights, suggestTags, draftAltText — and every prompt is versioned in packages/core/ai/prompts with the version recorded on each suggestion row.

What changes if you pick differently: one adapter file, one credential, and the prompt templates (which are provider-tuned and versioned). The verbatim-only boundary in Section 12.1 is enforced by server-side substring validation and is provider-independent — it holds no matter which model you use.

Where it takes effect: Sections 3, 12, 19, 22.

1.2.8 D8 — Transactional Email Provider #

Default: Resend.

Why this default: simple API, good deliverability defaults, native support for the two things this product needs beyond sending — per-message tagging (so bounces and complaints can be attributed to a workspace) and inbound webhooks for delivery events.

What changes if you pick differently: Postmark and SendGrid are equivalent. The adapter sends a template id plus a typed payload and returns a provider message id, which is stored on the notifications row so delivery-status webhooks can be reconciled (Section 20).

Where it takes effect: Sections 3, 20, 22.

1.2.9 D9 — SMS Provider #

Default: Twilio. SMS is used only for testimonial request invitations where the workspace supplies a mobile number and the respondent has opted in.

Why this default: the broadest country coverage and the clearest compliance tooling for opt-out handling (STOP/HELP keywords are handled by the provider and surfaced as webhooks).

What changes if you pick differently: any provider with a send API and a delivery webhook works. Section 20 owns the invitation channel logic; SMS is optional per workspace and disabled by default, so a build that omits SMS entirely is a valid, complete build — the feature degrades to email-only invitations with no other behaviour change.

Where it takes effect: Sections 3, 8, 20.

1.2.10 D10 — Payment Provider #

Default: Stripe — Checkout for the first purchase, Billing Portal for all subsequent changes, webhooks as the authoritative source of subscription state, Stripe Tax for tax calculation.

Why this default: hosted Checkout and Portal remove card handling, SCA, dunning UI, proration UI, and invoice delivery from scope. The application never renders a card field.

What changes if you pick differently: Section 19 defines the subscription state machine in provider-neutral terms — a billing_state of trialing, active, past_due, or canceled, with capacity tracked orthogonally as limit_state — with a provider event table mapping onto it. Substituting a provider means rewriting that mapping and the two hosted-page redirects. Everything about quota enforcement is internal and provider-independent.

Where it takes effect: Sections 3, 19, 24, 29.4.

1.2.11 D11 — Pricing Numbers #

Default: Free $0 · Starter $19/month · Growth $49/month · Scale $149/month. Annual billing is priced at ten times the monthly rate (two months free). Custom-domain add-on $10 per domain per month on Starter and Growth, $8 on Scale.

Why this default: it maps to the entitlement table in Section 19 with clear jumps in the two metered dimensions customers actually feel — collected testimonials and seats — and it places the first paid tier below the threshold at which a marketing team needs approval to buy.

What changes if you pick differently: prices live in exactly two places: the plan configuration in packages/core/plans (display prices, used for UI only) and Stripe price IDs in environment configuration (Section 29.2). Entitlement values are separate from prices; you can reprice without touching limits and vice versa. Never read a price from Stripe at render time on a public page — cache the plan config and reconcile on webhook.

Where it takes effect: Sections 2, 19.

1.2.12 D12 — Free-Tier Collected-Testimonial Cap #

Default: 10 lifetime collected testimonials.

Why this default: ten is enough to build a real wall of love and feel the product work end to end, and small enough that a growing business hits it within its first campaign. The cap is on collection, never on serving: a Free workspace's ten testimonials are served forever, at full quality, with no view limit (Section 19, rule 3).

What changes if you pick differently: one integer in the plan configuration. Raising it increases storage and transcription cost per free workspace roughly linearly; the storage and transcription quotas in Section 19 are the actual cost guards and should move with it.

Where it takes effect: Sections 2, 8, 19.

1.2.13 D13 — Maximum Video Length #

Default: 5 minutes on paid plans, 2 minutes on Free.

Why this default: usable video testimonials are 30–90 seconds. Five minutes is generous headroom; beyond it, chunked-upload session state, transcription cost, and moderator review time all grow without improving the output. The two-minute Free limit keeps the free tier's storage and transcription cost bounded.

What changes if you pick differently: the recorder's hard stop, the 15-second warning, the upload-session part budget, and the transcription minute accounting all read the same plan value. Raising it above roughly 10 minutes requires revisiting the chunked-upload part count and the single-request transcription timeout in Section 10.6.

Where it takes effect: Sections 9, 10, 19, 21.

1.2.14 D14 — Launch Transcription Languages #

Default: English (default), Spanish, French, German, Portuguese, with automatic language detection. Detection confidence below 0.6 falls back to the workspace's default language and flags the transcript for human review.

Why this default: these five cover the large majority of the target market's customer base and are all high-accuracy in the chosen model family. Automatic detection means the respondent is never asked to declare a language.

What changes if you pick differently: the language list is configuration. Adding a language requires: adding it to the allowed set, verifying the provider's model supports it at comparable accuracy, and adding its display name to the caption-editor language selector. Note that this is transcription language only — the product UI is English-only in v1 and that is stated as out of scope in Section 2.7.

Where it takes effect: Sections 10, 12.

1.2.15 D15 — Primary Data Region and EU Option #

Default: primary region us-east. All of Postgres, Valkey, object storage, and the worker run in one region. The CDN is global. An EU-region deployment path is documented in Section 26.11: a second, fully independent stack (its own database, cache, bucket, and worker) with workspace-level routing at sign-up, rather than cross-region replication.

Why this default: a single-region primary is dramatically simpler to operate, and the data that actually needs to be near the user — widget payloads, posters, and video — is already global because it is served from the CDN and from the video provider's edge.

What changes if you pick differently: if you launch EU-primary, change the region for all four stateful components together and confirm your video and transcription providers' regional processing options. If you launch both, the workspace's region is chosen at creation, stored on the workspace row, and is immutable; there is no cross-region workspace migration in v1.

Where it takes effect: Sections 22, 26.

1.2.16 D16 — Ship the Popup / Slide-in Widget in v1 #

Default: yes.

Why this default: it is a preset over the same rendering core as the other widget types, not a separate codebase, so its marginal cost is small. It is also the widget type most likely to be misused, which is why its behaviour is tightly constrained in Section 13: never within the first 5 seconds of page load, dismissible with both a visible control and the Escape key, frequency-capped in memory per page view, never focus-trapping, never covering the host page's primary content area, and fully suppressed under prefers-reduced-motion except for a static, non-animated appearance.

What changes if you pick differently: disable it with the flag_widget_popup feature flag. The widget type stays in the enum and the editor hides it. No schema change.

Where it takes effect: Sections 13, 21.

1.2.17 D17 — Brand Palette and Dashboard Type Scale #

Default: a neutral slate grey scale with a single indigo accent, plus semantic colours for success, warning, danger, and info. Type scale is a 1.200 minor third from a 16 px base: 12.8 / 16 / 19.2 / 23 / 27.6 / 33.2 / 39.8 px, rounded to whole pixels. Base line height 1.5, headings 1.25. System font stack throughout, in both the dashboard and the widget, so zero web fonts are downloaded on a host page (a hard requirement in Section 13).

Why this default: it is legible, neutral enough not to fight a customer's own brand in screenshots, and every foreground/background pair in the token file passes 4.5:1 for body text and 3:1 for large text and UI components, so the dashboard starts compliant rather than being remediated.

What changes if you pick differently: replace the token values in packages/config/tokens. Two constraints are non-negotiable regardless of palette: (a) every token pair used for text must pass the contrast ratios in Section 21, verified by the contrast unit test that ships with the token file; (b) no colour may be the sole carrier of meaning anywhere in the product.

Note that the widget's accent colour is a per-workspace customer setting, not a brand decision, and it is contrast-checked in the widget editor at configuration time (Section 21).

Where it takes effect: Sections 4.8, 13, 21.

1.2.18 D18 — Support Channel Addresses #

Default: support@vouch.app (product support, referenced in dunning and quota emails), security@vouch.app (vulnerability disclosure, referenced in the security policy in Section 22), privacy@vouch.app (data subject requests, referenced in the respondent portal and the consent text), status.vouch.app (public status page, linked from the 503 error page and from dependency-degradation banners).

Why this default: three of the four are referenced by name in user-facing copy and in compliance text, so they must exist before launch rather than being invented during an incident.

What changes if you pick differently: all four are configuration values read by the email templates and by the error pages. Support tiers (community / email / 1 business day / 4 business hours) are entitlements in Section 19 and are independent of the addresses.

Where it takes effect: Sections 19, 20, 22, 24.

1.2.19 D19 — Log, Metrics, and Error Vendor #

Default: structured JSON logs to the platform's native log sink; errors and distributed traces to Sentry; metrics exported over the OpenTelemetry protocol to whatever collector the platform provides.

Why this default: the application emits OpenTelemetry-shaped telemetry and never calls a vendor SDK directly outside a single instrumentation module, so the vendor is an exporter configuration rather than a dependency threaded through the code.

What changes if you pick differently: swap the exporter endpoints in configuration. The non-negotiable parts are vendor-independent and are owned by Section 24: every log line carries the request id, the workspace id, and the actor id; no log line ever contains testimonial body text, a respondent's email or phone number, an API key, a session token, or a webhook secret; and every error surfaced to a user carries the request id so a support conversation can find the corresponding trace.

Where it takes effect: Sections 3, 22, 24, 29.2.

1.2.20 D20 — Stripe Tax #

Default: enabled.

Why this default: the product sells globally to businesses from day one. Calculating VAT, GST, and US sales tax by hand is a compliance liability, and retrofitting tax onto existing subscriptions is materially harder than starting with it on. With it enabled, Checkout collects and validates the customer's address and tax ID, and invoices are tax-correct from the first charge.

What changes if you pick differently: disabling it means every price is treated as tax-inclusive with no jurisdiction handling, you must remove the tax-ID field from the billing settings screen, and you accept the registration obligations yourself. The subscription state machine in Section 19 does not change either way.

Where it takes effect: Section 19.

1.3 How to Use This Document #

Reading order. Read Sections 1–7 in sequence before writing any code; they are the foundation and every later section assumes them. After that, Sections 8–20 are feature sections and can be read in build order rather than document order. Sections 21–26 are cross-cutting requirements that apply to everything you build and must be read before you consider any feature finished. Section 27 is the milestone plan, Section 28 is the execution procedure, and Section 29 is reference material you will return to constantly.

One concern, one owning section. Every fact in this document has exactly one home. The HTTP envelope is defined once in Section 7 and referenced everywhere else. The plan limits are defined once in Section 19. The testimonial state machine is defined once in Section 11. When two sections need the same fact, the non-owning one names the owner by number and does not restate it. If you ever find yourself with two plausible answers to the same question, the owning section wins — and if you change something, change it in the owning section and let the references follow.

Version lines. Every dependency version line appears exactly once, in Section 3.1. No other section states a version number: a section may name the technology and cite Section 3.1, and that is the only permitted form. This is deliberate: it makes a stack upgrade a single-table edit rather than an archaeology exercise. Section 3.1 also tells you what to do when the current stable release has moved past the line stated there.

Execution sequencing. Do not invent your own build order. Section 28 gives the exact sequence — environment first, then schema, then the tenancy and authorization core, then collection, then media, then moderation, then publishing, then the long tail — along with the verification gate that closes each step. Section 27 gives the milestone grouping and the definition of done for each milestone. Follow Section 28 literally; the ordering exists because each step's verification depends on the previous step being real rather than stubbed.

When you disagree with a decision. Change it, write the ADR in docs/DECISIONS.md, and update the owning section of your own copy of the specification so the document and the code never drift. What you must not do is leave the document saying one thing while the code does another.

2. Product Overview, Vision & Success Criteria #

2.1 The Problem #

Social proof is the single highest-leverage asset a growing company has, and almost every company collects it badly.

The typical sequence is: someone on the marketing team remembers that a customer said something nice on a call. They email that customer asking for a quote. Two weeks later, after a reminder, a paragraph arrives in an email reply. Someone pastes it into a spreadsheet. Months later a designer hard-codes it into a landing page as static HTML. Nobody has written permission to use it. Nobody knows whether the person still works there. When the customer churns, the quote stays on the homepage because no one has a list of where it appears.

Video is worse. Video testimonials convert dramatically better than text and are collected far less often, because the ask is heavy: install something, or use a link to a tool that demands an account, or record on a phone and email a 400 MB file that bounces. The friction is not the recording — it is everything around the recording.

And publishing is worse again. The teams that do collect testimonials end up stitching together three or four tools: a form builder, a video host, a transcription service, and an embed widget from a fourth vendor. Each one adds JavaScript to the marketing site. The resulting embed is frequently the heaviest thing on the page — a framework runtime, web fonts, an iframe that reflows and shifts the layout — so the social proof that was supposed to increase conversion measurably degrades the page it sits on.

Four failures, concretely:

1. Collection friction. Anything that asks a customer to install, sign up, or fight with file sizes loses most of the customers who were willing to help.
2. No moderation accountability. Who approved this quote? Was it edited? Did the person consent to being in a paid ad? Most teams cannot answer, and increasingly they are asked to.
3. Heavy, inaccessible embeds. Widgets that ship a framework, shift layout, download fonts, and are unusable by keyboard or screen reader.
4. No measurement. No idea which testimonial actually drives clicks, so curation is guesswork — and the analytics that would answer it usually arrive with a cookie banner attached.

2.2 The Product #

Collect, moderate, and publish written and video testimonials as embeddable social proof, anywhere.

A workspace creates a branded request page and shares its link. A customer opens it on their phone, records a 45-second video directly in the browser with no app and no account, ticks an explicit consent box, and submits. The video uploads while they are still speaking, is transcoded and transcribed automatically, and lands in a moderation inbox. Someone with the right role reviews it, tags it, and publishes it — and every one of those actions is recorded in an append-only audit trail. The moment it is published it appears in every widget that matches its filters, on every site those widgets are embedded in, delivered from a CDN edge in a payload under 60 KB with under 27 KB of JavaScript, no framework, no web fonts, and no cookies. Cookie-free analytics then show which testimonials people actually watch and click.

2.3 Target Users #

Primary: B2B SaaS companies and their marketing teams. They have customers who like them, a landing page that needs proof, and no systematic way to get from one to the other. They care about conversion rate, page speed, and being able to prove they had permission.

Secondary: founders and growth marketers replacing an existing point tool. They are already using Testimonial.to, Senja, or Trustmary and are migrating because of embed weight, missing moderation controls, per-seat pricing, or the custom-domain experience. They arrive with existing testimonials and expect to import them, which is why CSV import is available on every plan including Free.

Tertiary: small marketing teams needing multi-seat moderation. Three to ten people where a contractor or junior marketer collects and drafts, and a manager approves. They need real roles, not a shared password, and they need to see who approved what.

2.4 Personas #

2.4.1 Maya — Head of Marketing, 40-person B2B SaaS #

Context. Owns the website and the demand-generation number. Has two direct reports and a freelance designer. Approves anything that goes on the homepage.

Goal. Put five strong video testimonials on the pricing page before the quarter ends, and be able to swap them without a developer.

Frustrations. The last testimonial project produced four text quotes in a spreadsheet. The video her CEO recorded with a customer is sitting in a shared drive, unedited, without captions. Her developer refuses to add another third-party script to the site because the last one cost 0.4 seconds of Largest Contentful Paint.

Hires the product to: get video testimonials collected without her being the bottleneck, and put them on the site in a way her developer will actually approve.

A day in her life with the product. She opens the dashboard at app. and lands on the Overview screen — collection funnel, pending moderation count, and the top-performing published testimonials by click-through. Three new submissions overnight. She clicks through to the Moderation Inbox, where each card shows the video with captions on by default, the transcript beside it, the consent grants that were captured, and the source. She watches the first at 1.5× while reading the transcript, taps Approve, adds the tags enterprise and onboarding, and hits Publish. She opens the Widgets screen, sees her "Pricing page — wall of love" widget already includes the new testimonial because it filters on the enterprise tag, and previews it in the widget editor against a light and a dark background. She copies nothing — the snippet on the pricing page has not changed and never will. She ends in Analytics, sorts published testimonials by click-through rate, notices that a 30-second clip outperforms a 2-minute one by a factor of three, and reorders the wall to lead with the short ones.

2.4.2 Dev — Solo founder, developer, 300-customer micro-SaaS #

Context. Builds and markets alone. Ships his own landing page. Cares about page weight the way other people care about rent.

Goal. Get proof on the landing page this weekend without slowing it down and without a subscription he cannot justify at 300 customers.

Frustrations. Every widget he has tried loads a framework and web fonts. One shifted his hero section by 60 pixels on mobile. He does not want an iframe. He does not want a cookie banner because he does not currently need one.

Hires the product to: be the lightest possible way to put real customer quotes on a page.

A day in his life with the product. He signs up, lands on the Onboarding screen, and creates a request page in about two minutes by picking a template, writing three prompts, and uploading his logo. He emails the v. link to eight customers from his own inbox. Four respond within a day; two record video. He moderates from his phone. He creates a Wall of Love widget, sets the accent to his brand colour — the editor warns him that his chosen colour fails contrast on the dark theme and offers the nearest passing shade, which he accepts — copies the two-line snippet, and pastes it into his landing page. He runs Lighthouse before and after: the JavaScript delta is under 27 KB gzip and Cumulative Layout Shift is unchanged. He stays on Free for two months, hits the ten-testimonial cap, sees the in-product warning at eight, and upgrades to Starter. Nothing on his live page ever changed during the upgrade, and nothing would have changed if he had stayed on Free forever.

2.4.3 Priya — Customer Marketing Manager, 200-person company, regulated buyers #

Context. Runs the customer advocacy programme. Her legal team reviews anything featuring a named customer. Her buyers are in financial services.

Goal. Run testimonial collection at scale with a defensible record of consent, and route approvals through the right people.

Frustrations. Her current tool has one shared login. She cannot prove who approved a quote or whether the customer agreed to appear in a paid ad. Last quarter a customer asked to be removed and it took eleven days and three people to find every place the quote appeared.

Hires the product to: make consent and moderation auditable, and make withdrawal instant.

A day in her life with the product. She invites her two contractors as Editor and her legal reviewer as Viewer from the Team screen. Editors collect and moderate; only she and the workspace Owner can touch billing, domains, or API keys. She configures her request page's consent block: publication consent is required, paid-advertising consent and case-study-contact consent are separate optional checkboxes, never pre-ticked, and the exact wording rendered to each respondent is stored verbatim with its hash. When legal asks who approved a specific quote, she opens the testimonial's Audit tab and sees every status change, every tag change, and every consent grant with actor, timestamp, and before/after snapshot. When a customer emails asking to be removed, she sends them their respondent portal link; they withdraw themselves, the testimonial unpublishes within 60 seconds across every embed, and she gets a notification. She sets up a custom domain so her showcase page lives at stories.hercompany.com, watches the verification UI move from pending_dns to active through the explicit states Section 14.3 defines, without opening a support ticket, and confirms — as the setup screen states explicitly — that the widget snippets already live on her marketing site did not need to change.

2.5 The Product Loop: Collect → Moderate → Publish → Measure #

Everything in this product is one of four things. This loop is the spine of the information architecture, the dashboard navigation, the milestone plan in Section 27, and the feature inventory below.

graph LR
  C[COLLECT<br/>request pages, invites,<br/>video + text capture, import] --> M[MODERATE<br/>inbox, transcript + captions,<br/>tags, consent, audit trail]
  M --> P[PUBLISH<br/>widgets, showcase pages,<br/>custom domains, social cards, API]
  P --> Me[MEASURE<br/>cookie-free impressions,<br/>interactions, clicks, per-testimonial CTR]
  Me -->|informs which prompts and<br/>which customers to ask next| C

• Collect is optimised for the respondent, who is not your user and owes you nothing. No account, no install, no app, mobile-first, under 90 seconds from link to submitted video.
• Moderate is optimised for accountability. Nothing reaches the public without an explicit human action, and every action is recorded permanently.
• Publish is optimised for the host page. The embed is the hardest engineering constraint in the product and the place where it wins or loses against every competitor.
• Measure is optimised for privacy. No cookies, no local storage, no cross-site identifier, therefore no consent banner and no legal review for the customer's site.

2.6 Feature Inventory #

Fifteen capability areas. Each names its owning section, which is the single authority on its behaviour.

1. Branded request pages, custom fields & invitations (Section 8). A public page at v.vouch.app/r/{slug} — or on the workspace's own custom domain — carrying the workspace's logo, colours, and a short intro. It presents up to five prompts that give the respondent something to answer instead of a blank box, offers a choice between recording video and writing text, collects a configurable set of fields (name, role, company, website, headshot, star rating, plus operator-defined custom fields), and captures consent on the same screen as the submit button. Invitations go out by email or SMS with per-recipient tracking through sent, opened, started, and submitted, with configurable reminders.

2. In-browser video & text capture with chunked upload (Section 9). getUserMedia plus MediaRecorder, with a device picker, a 3-2-1 countdown, a live timer, an optional teleprompter, and a hard stop at the plan's maximum length with a 15-second warning. The recording uploads in 5-second chunks while the respondent is still recording, so a five-minute take is roughly 95% uploaded the moment they stop. Retakes are unlimited and free; a discarded take's upload is aborted immediately and its storage reclaimed. Nothing counts against quota until submit.

3. Automatic transcription & editable captions (Section 10). Every video is transcribed automatically with word-level timings and per-word confidence into one canonical transcript structure. Captions, the searchable text, the pull-quote extraction, the highlight assistant's clip boundaries, and the text shown beside a video all derive from that one structure — there is no second copy to drift. A segment editor lets a moderator fix words, merge and split segments, and nudge timings; low-confidence words are flagged non-visually as well as visually. Captions are on by default in every player, including inside widgets.

4. Moderation inbox, tagging, lifecycle & audit trail (Section 11). A single inbox for everything — collected and imported alike — with a strict status lifecycle, bulk actions, saved filters, keyboard-driven review, tagging from a workspace-controlled vocabulary, and an append-only audit trail. Every status change, content edit, tag change, and consent change writes an immutable row with the actor, the actor type, a before/after snapshot, the IP, the user agent, and the timestamp. The table rejects updates and deletes at the database level.

5. AI highlight assistant (Section 12). Optional, Growth and Scale only, and bounded by a permanent product rule: it may only select, never rewrite. It proposes which of the respondent's own words to feature and which seconds of video to clip. Every proposed pull-quote is validated server-side by exact substring match against the stored transcript or body before a human ever sees it. Manual curation is always available and is the default, and nothing AI-proposed publishes without an explicit human approval click.

6. Embeddable widgets & the embed SDK (Section 13). Six widget types — Wall of Love, Carousel, Single Quote, Video Reel, Badge/Rating Summary, and Popup/Slide-in — from one vanilla-TypeScript rendering core with no framework. The snippet a customer pastes carries only the widget id and never has to change again. Rendering happens in an open shadow root with a single adopted stylesheet, one non-enumerable global, zero web fonts, and video that never loads until the viewer chooses to play it.

7. Public showcase pages & custom domains (Section 14). A server-rendered, crawlable, fast public page of a workspace's testimonials, available at a shared subdomain on every plan and on the customer's own domain from Starter upward. Domain setup shows the exact DNS records, polls live, displays every state in Section 14.3's machine explicitly with plain-English diagnostics, and issues TLS automatically. Adding or changing a domain never requires re-pasting an embed snippet.

8. Social image card generator (Section 15). Renders a shareable image from any published testimonial — quote, attribution, avatar, rating, workspace branding — in several presets and sizes, generated server-side, cached to object storage, served from cdn., and used both for og:image on showcase pages and for direct download.

9. Review import (Section 16). Google Business Profile, G2, Capterra, X, and CSV. Every source is an official API, an official syndication feed, or a customer-supplied export — there is no scraping anywhere in this product. Imported reviews land in pending in the same inbox, keep their attribution and permalink, are never editable, and are deduplicated on the source's own review id plus a fuzzy near-duplicate warning.

10. Cookie-free widget analytics (Section 17). Impressions, interactions, clicks, and video-completion quartiles measured with no cookie, no local storage, no fingerprint, and no cross-site identifier of any kind. Dedupe within a page view uses a random id held in JavaScript memory that ceases to exist on navigation. IP is used to derive country and device class and is then discarded, never stored. Bot traffic is filtered and counted separately rather than silently dropped.

11. Integrations (Section 18). Signed outbound webhooks with a documented event catalogue, replay, and automatic disabling after sustained failure; a Zapier app built on those webhooks plus a small polling API; a Slack app that posts new submissions and lets a moderator approve from Slack; and a HubSpot integration that syncs testimonials to contact and company records.

12. Public REST API (Section 7). Versioned at /api/v1/, authenticated with workspace API keys carrying scopes, cursor-paginated, idempotent on unsafe endpoints, rate-limited per workspace, with one error envelope and a stable, catalogued error code for every failure. Read-only access is available even on Free.

13. Team roles, invitations & workspace management (Section 6). Exactly four roles — Owner, Admin, Editor, Viewer — enforced by a single can(actor, action, resource) function that every route and server action calls. Invitations are emailed, single-use, hashed at rest, and expire in seven days. Exactly one Owner per workspace, with an explicit confirmed transfer.

14. Plans, billing & enforced limits (Section 19). Four plans, all limits enforced server-side, with warnings at 80% and 95% in product and emails at 90% and 100%. The rule that governs all of it: reaching a cap never degrades anything already live. Published widgets, showcase pages, and the widget data API keep serving at full quality and full volume on every plan, forever — including Free, including past-due, including cancelled.

15. Consent capture, privacy controls & data rights (Section 22). Consent is captured on the submit screen, never pre-ticked, split into one required and two optional grants, and stored with the exact text the respondent saw plus its hash. Every published testimonial carries a stable respondent portal link from which the person can see what was published, download their data, withdraw, or request erasure — with no account. Withdrawal unpublishes within 60 seconds across every embed. Erasure is a genuine hard delete that also destroys the video asset, every object-storage key, and every CDN cache entry.

2.7 Explicitly Out of Scope for v1 #

2.8 Competitive Positioning #

Kept factual and short. All three named products are competent and all three have real strengths worth learning from.

The three places this product must be better, and what "better" means concretely:

1. Embed performance. Total JavaScript added to a host page ≤ 27 KB gzip, zero framework bytes, zero web fonts, zero render-blocking resources, CLS contribution ≤ 0.01, one network request before first paint. These are CI-enforced budgets, not aspirations (Sections 13 and 23).
2. Moderation accountability. Four real roles, an append-only audit trail the database itself refuses to modify, consent stored with the exact text the respondent saw, and respondent-initiated withdrawal that takes effect across every embed within 60 seconds (Sections 6, 11, 22).
3. Custom-domain setup experience. Exact records shown, live polling with every state in Section 14.3 shown explicitly, the records actually observed at the authoritative nameservers shown next to the records required with a plain-English diff, automatic TLS — and an unconditional guarantee that a domain change never requires re-pasting an embed snippet (Section 14).

2.9 Success Criteria — Launch-Readiness Gates #

These are gates, not goals. Each is measured by a specific method and each must pass before the product is considered launched. Section 23 owns the full non-functional requirement table and Section 25 owns the test strategy that runs these.

3. Technology Stack & System Architecture #

3.1 The Canonical Stack #

This table is the single authority on technology and version lines for the entire document. No other section states a version number. Where a later section mentions a dependency, it names the technology and refers back here.

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

When the current stable major has moved past the line stated here, resolve it as follows. If the current stable major is higher than the line above, take it and record the deviation as an ADR in docs/DECISIONS.md, noting anything in the migration guide that touches this design. If it is lower, the line above is wrong and should be corrected in this table. Never pin below the line stated. This is the whole procedure; do not stop and ask, and do not record the resolved number anywhere in this document — the lockfile is where exact versions live.

3.2 Why These Choices #

TypeScript, strict. strict: true, noUncheckedIndexedAccess, exactOptionalPropertyTypes, and verbatimModuleSyntax on from the first commit. The alternative — starting loose and tightening later — never happens in practice, and this codebase shares types across four consumers (dashboard, request page, worker, public API) where a type error is the cheapest place to catch a contract break. Rejected: JavaScript with JSDoc types, which cannot express the discriminated unions the job payloads and the widget configuration rely on.

Node.js LTS. Native fetch, stable AbortSignal, a built-in test runner available as a fallback, and a support window that outlives the build. Rejected: Bun and Deno — both are capable, but the ecosystem this product depends on (BullMQ, ioredis, the video and payment SDKs, Drizzle's Postgres driver) is validated against Node, and this is not a project where runtime novelty pays for itself.

pnpm + Turborepo. A monorepo is not optional here: the Zod schemas in packages/validation must be the same objects used by the dashboard form, the API route, the worker job, and the public API handler. pnpm's strict, non-hoisted node_modules prevents phantom dependencies — which matters enormously for apps/embed, where an accidental transitive import of React would blow the size budget silently. Turborepo gives content-addressed task caching so CI rebuilds only what changed. Rejected: npm workspaces (hoisting makes the embed boundary unenforceable) and Nx (more capability than this repo needs).

Next.js App Router + React. One framework serving four surfaces — an authenticated dashboard, public request pages, public showcase pages, and API routes — with Server Components keeping the dashboard's client bundle small and Server Actions removing an entire layer of hand-written mutation endpoints. Its Edge runtime is what lets the widget data API and the analytics beacon run at the CDN edge without a second service. Rejected: a Vite SPA plus a separate API server (two deploy targets, no server rendering for showcase pages, worse SEO), and Remix (equivalent quality, but no edge-runtime story as tightly integrated with the hosting model here).

Tailwind CSS. Utility classes with a shared preset in packages/config keep the dashboard and request pages visually consistent without a growing pile of bespoke CSS, and its build step means unused styles never ship. Design tokens are CSS custom properties so the same values are readable from the request page's runtime theming. Rejected: CSS Modules (more files, weaker consistency) and a CSS-in-JS runtime (ships a runtime, fights Server Components). Note that Tailwind is used in neither apps/embed — see Section 4.8 for why the widget's CSS is hand-authored.

Radix UI primitives plus a local component layer. Accessible behaviour — focus trapping, roving tabindex, dismissal semantics, portal management — is the part of a component library that is genuinely hard, and Radix ships it unstyled. Wrapping it in packages/ui means one place to enforce the design tokens and one place to fix an accessibility defect. Rejected: a fully styled component library (fights the design system, ships unused CSS) and hand-building dialogs and menus (a reliable way to ship WCAG failures).

TanStack Query, deliberately limited. Used only where the client genuinely polls or subscribes: domain verification status (Section 14), the moderation inbox's live updates, and media processing state. Everything else is a Server Component read or a Server Action mutation. Rejected: using it as the default data layer, which would push the dashboard back into client-side fetching and inflate the bundle for no benefit.

React Hook Form + Zod resolvers. Uncontrolled inputs mean typing in a long testimonial form does not re-render the tree, which matters on the mobile request page. The resolver reuses the exact same Zod schema the server validates with, so the client cannot accept something the server will reject. Rejected: controlled state by hand (re-render cost, duplicated validation).

Zod as the single validation authority. One schema per boundary, in packages/validation, consumed by the form, the route, the worker, and the public API. It infers TypeScript types, so the type and the runtime check cannot diverge. Rejected: class-validator (decorator-based, awkward to share with the browser) and hand-written guards (drift).

PostgreSQL. Row-Level Security is the reason. Tenant isolation enforced by the database rather than by remembering a WHERE clause is a categorically stronger guarantee, and it is the foundation of the tenancy model in Section 6. Beyond that: native enums, JSONB for transcripts and audit snapshots, generated columns and trigram indexes for search, timestamptz done correctly, and mature partitioning for the analytics tables. Rejected: MySQL (no comparable RLS) and a document database (the data is deeply relational and the audit requirements demand constraints).

Drizzle ORM. SQL-shaped, fully typed from the schema definition, with a migration generator that produces plain SQL files a human reviews and commits. Critically, it does not hide the query, which matters when every query must be workspace-scoped and must run inside a transaction that has set the RLS session variable. Rejected: Prisma (a separate engine process, historically awkward with RLS session variables and with connection pooling under serverless) and raw SQL everywhere (no type safety across four consumers).

Valkey via ioredis. Backs three things: the BullMQ queues, the token-bucket rate limiters, and short-lived caches. Valkey is the community-governed continuation of the Redis protocol; any Redis-compatible server works. Rejected: an in-process cache (breaks with more than one instance) and a database-backed queue (job throughput and latency).

BullMQ. Mature, typed, Redis-protocol-backed job queue with the four features this product actually needs: delayed jobs (reminder emails, retention sweeps), repeatable jobs (domain verification polling, analytics rollups), per-job retry policies with backoff, and a real dead-letter path. Rejected: a cloud-native queue service (couples the design to one cloud; harder local development) and cron-plus-database-polling (no backoff, no concurrency control).

better-auth. Session management, email verification, magic links, password reset, and TOTP in one library that stores its data in your Postgres rather than a third-party identity service — which matters because the session, the user, and the workspace membership need to be joinable in a single query. Rejected: a hosted identity provider (an external dependency on the login path, and user data outside the database that must satisfy erasure requests) and hand-rolled auth (the fastest way to ship a security defect).

Stripe. See Section 1.2.10. Hosted Checkout and Portal remove card handling, SCA, dunning UI, and invoicing from scope entirely.

Mux. See Section 1.2.5. Browser-recorded video arrives in inconsistent codecs and containers; normalizing it to adaptive streaming that plays on every device is a solved commodity.

S3-compatible object storage. Three requirements decide it: multipart upload (the chunked resumable upload in Section 9 depends on it), AbortMultipartUpload (free retakes depend on reclaiming storage immediately), and pre-signed URLs (the browser uploads directly, never through the application server). Rejected: uploading through the application (bandwidth cost, request timeouts, no resumability).

Deepgram. See Section 1.2.6. Word-level timings with per-word confidence are mandatory for the caption editor and the clip suggester.

Resend and Twilio. See Sections 1.2.8 and 1.2.9. Both sit behind thin adapters.

satori + resvg + sharp. Social cards are rendered from a JSX-like tree to SVG and then to PNG, entirely in-process, with no headless browser. A headless browser for image generation costs hundreds of megabytes of memory per worker and is the single most common source of memory exhaustion in Node services. Rejected: Puppeteer screenshots for exactly that reason.

esbuild for the widget. The widget is a single vanilla-TypeScript entry point compiled to an ES2022 IIFE with a hard size budget. esbuild is fast, produces small output, and — most importantly — its metafile makes the size-limit and no-framework CI assertions trivial to write. Rejected: the framework's own bundler (wrong output shape, no IIFE target, no independent size gate) and Rollup (comparable output, materially slower in watch mode).

pino. Structured JSON logging with negligible overhead and first-class redaction paths, so "never log a token or a testimonial body" is a configuration rather than a discipline. Rejected: console logging (unstructured, unqueryable) and winston (slower, heavier).

Sentry with OpenTelemetry. Errors, performance traces, and release health, emitted in a vendor-neutral protocol so the vendor is an exporter setting (Section 1.2.19). Rejected: building an in-house error pipeline.

Vitest and Playwright. Vitest shares the Vite transform pipeline, runs TypeScript natively, and is fast enough that the unit suite runs on save. Playwright drives real browsers, which is non-negotiable for a product whose two hardest surfaces are a MediaRecorder flow and a shadow -DOM widget — and its --use-fake-device-for-media-stream support makes the recorder testable in CI. Rejected: Jest (slower, more configuration for ESM and TypeScript) and Cypress (weaker multi-origin and multi-browser support, which the embed tests need).

axe-core. Automated accessibility checks catch roughly a third of WCAG failures; that third is worth catching on every pull request. The remaining two thirds are covered by the manual test matrix in Section 21.

DOMPurify. Rich-text testimonial bodies are sanitized at write time and again at serve time, against a deliberately tiny allowlist. Sanitizing twice is not redundant: write-time sanitization protects the database, serve-time sanitization protects against a rule change or a direct database write.

3.3 Repository Layout #

vouch/
  apps/
    web/            Next.js App Router application. Dashboard (app.), public request pages,
                    public showcase pages, the widget JSON API, the embed loader route, and
                    all HTTP API routes. Mixed Node and Edge runtimes — see Section 3.6.
    worker/         Long-lived Node service. BullMQ consumers: media/transcode callbacks,
                    transcription, AI jobs, social-card rendering, review imports, outbound
                    webhook dispatch, email and SMS delivery, analytics rollups, retention
                    sweeps, and domain-verification polling.
    embed/          The widget. Vanilla TypeScript, compiled by esbuild to an ES2022 IIFE.
                    No framework, no React, no Tailwind. Renders into an open shadow root.
  packages/
    db/             Drizzle schema, generated SQL migrations, seed data, RLS policies, the
                    connection factory, and typed query helpers. The only package that
                    contains SQL.
    core/           Domain services, framework-free: moderation, quotas and entitlements,
                    publishing, consent, analytics aggregation, import normalization, and AI
                    orchestration. No HTTP, no React, no direct SQL.
    validation/     Zod schemas shared by the client forms, the server routes and actions,
                    the worker job payloads, and the public API.
    ui/             React component layer for the dashboard: Radix primitives wrapped with
                    design tokens, plus composite components.
    config/         Shared configuration: tsconfig bases, ESLint config, Prettier config,
                    the Tailwind preset, and the design-token source.
  infra/            Infrastructure as code, Dockerfiles, the migration runner, and CI
                    workflow definitions.
  docs/             Developer-facing documentation you write and maintain. Create the tree
                    below; every file in it is required by a later section of this document,
                    and the section named beside each one tells you what goes in it.
    README.md                        What this repository is, how to run it, how to deploy it
    DECISIONS.md                     One ADR per irreversible decision (Sections 1, 4.10)
    RUNBOOKS.md                      One runbook per operational procedure (Section 24.8)
    COMMS-TEMPLATES.md               Incident and customer communication copy (Section 24.9.5)
    BUILD-REPORT.md                  The completion report for the build (Section 28.8)
    oncall.md                        Rota and the named incident roles (Section 22.10.3)
    abuse.md                         Platform-abuse categories, SLAs, transparency note
                                     (Section 22.20.4)
    exports.md                       The data-export format, column for column (Section 22.6.1)
    subprocessors.md                 The sub-processor list published to customers (Section 22.9)
    accessibility.md                 Our own accessibility conformance statement (Section 21.15.2)
    quarantine.md                    Quarantined tests, each with an owner and a deadline
                                     (Section 25.10)
    privacy/ropa.md                  Records of processing activities, Art. 30 (Section 22.10.1)
    security/threat-model.md         The threat model (Section 25.8; copy Section 22.12 into it)
    fixtures/README.md               What each recorded provider fixture is and when it was
                                     last refreshed (Section 25.3.2)
    a11y/at-matrix-{version}.md      Assistive-technology results per release (Section 21.13.2)
    a11y/manual-runs/{date}.md       One file per manual accessibility run (Section 25.6)
    ai-eval/{version}.md             AI suggestion evaluation results per prompt version
                                     (Section 12.9.3)
    incidents/{YYYY-MM-DD}-{slug}.md One blameless post-incident review per incident
                                     (Section 24.9.6)

None of these files exists yet — they are outputs of the build, not inputs to it. Create each one the first time the section that owns it asks you to, and treat a missing file as an incomplete milestone rather than as an optional extra.

Every package has a README.md describing its purpose, its public exports, and its constraints. Every package's package.json declares its dependencies explicitly; nothing relies on hoisting.

3.4 System Architecture #

graph TD
  subgraph Browsers
    DASH[Dashboard<br/>app.vouch.app<br/>React Server + Client Components]
    REQ[Request page + recorder<br/>v.vouch.app/r/-slug-<br/>mobile-first]
    HOST[Third-party marketing site<br/>with the pasted embed snippet]
  end

  subgraph Edge
    CDN[CDN edge<br/>cdn.vouch.app<br/>e.js, runtime chunk, widget JSON,<br/>posters, social cards, VTT]
    EDGERT[Next.js Edge runtime routes<br/>widget data API, embed loader,<br/>analytics beacon ingest]
  end

  subgraph Application
    WEB[apps/web - Node runtime<br/>dashboard, request pages, showcase,<br/>REST API, server actions, webhooks in]
    WORKER[apps/worker<br/>BullMQ consumers]
    DISPATCH[Outbound webhook dispatcher<br/>reads the transactional outbox]
  end

  subgraph Data
    PG[(PostgreSQL<br/>RLS-enforced, outbox table)]
    VK[(Valkey<br/>queues, rate limits, cache)]
    OS[(S3-compatible object storage<br/>originals, posters, cards, VTT)]
  end

  subgraph Third-party
    MUX[Mux<br/>transcode + delivery]
    DG[Deepgram<br/>transcription]
    STRIPE[Stripe<br/>billing]
    AI[AI provider<br/>highlight assistant]
    MAIL[Resend / Twilio<br/>email + SMS]
  end

  DASH -->|HTTPS, session cookie| WEB
  REQ -->|HTTPS| WEB
  REQ -->|pre-signed multipart PUT| OS
  HOST -->|async script tag| CDN
  HOST -->|widget JSON, CORS *| CDN
  HOST -->|sendBeacon analytics| CDN
  CDN -->|cache miss| EDGERT
  EDGERT --> PG
  EDGERT --> VK
  WEB --> PG
  WEB --> VK
  WEB --> OS
  WEB --> STRIPE
  WORKER --> PG
  WORKER --> VK
  WORKER --> OS
  WORKER --> MUX
  WORKER --> DG
  WORKER --> AI
  WORKER --> MAIL
  WORKER --> CDN
  MUX -->|signed webhooks| WEB
  STRIPE -->|signed webhooks| WEB
  PG -->|outbox rows| DISPATCH
  DISPATCH -->|signed HTTP POST| CUST[Customer webhook endpoints,<br/>Zapier, Slack, HubSpot]

Three properties of this diagram matter more than the rest:

1. The host page never talks to the application tier. It talks to the CDN. On a cache hit — the overwhelming majority of requests — no application code runs at all.
2. The browser uploads directly to object storage. Video bytes never pass through the application server, which is what makes chunked resumable upload of a five-minute recording viable on a serverless-ish web tier.
3. Everything that must happen exactly once alongside a database write goes through the outbox (Section 3.7), not through a direct call from a request handler.

3.5 Request Lifecycle Walkthroughs #

3.5.1 A respondent records and submits a video #

sequenceDiagram
  autonumber
  participant R as Respondent browser
  participant W as apps/web (Node)
  participant OS as Object storage
  participant Q as Valkey / BullMQ
  participant WK as apps/worker
  participant MX as Mux
  participant DG as Deepgram

  R->>W: GET /r/{slug}
  W->>W: Load request page, check collection quota (Section 19)
  W-->>R: 200 page (or collectionClosed payload if capped)
  R->>R: getUserMedia, device picker, codec negotiation
  R->>W: POST /api/v1/upload-sessions {mimeType, requestPageId}
  W->>OS: CreateMultipartUpload
  W->>W: Insert upload_sessions row
  W-->>R: 201 {uploadSessionId, uploadId, partUrlTemplate}
  loop every 5s timeslice while recording
    R->>W: POST /api/v1/upload-sessions/{id}/parts {partNumber}
    W-->>R: 200 {presignedUrl}
    R->>OS: PUT part bytes
    OS-->>R: 200 ETag
    R->>W: PATCH /api/v1/upload-sessions/{id} {partNumber, etag}
  end
  Note over R,OS: Retake -> AbortMultipartUpload, storage reclaimed, nothing charged
  R->>W: POST /api/v1/testimonials {uploadSessionId, fields, consents}
  W->>OS: CompleteMultipartUpload
  W->>W: TX: insert testimonial(pending) + media_asset(uploaded)<br/>+ consents + audit_event + outbox rows
  W->>Q: enqueue media.ingest
  W-->>R: 201 {testimonialId} -> thank-you screen
  WK->>MX: create asset from object-storage URL
  MX-->>W: webhook video.asset.ready {assetId, playbackId}
  W->>W: media_assets.state = ready, store playback id
  W->>Q: enqueue transcription.run, media.poster
  WK->>DG: transcribe(mediaUrl, detectLanguage)
  DG-->>WK: word-level transcript
  WK->>WK: store canonical transcript JSONB, generate VTT to object storage
  WK->>Q: enqueue notification.new_submission

Failure behaviour at each step. A dropped connection mid-upload resumes from the last acknowledged part with no re-sending. A failed part retries five times with exponential backoff and jitter, capped at 30 seconds. If asset processing errors, the testimonial stays in pending with media_state = errored, the moderator sees an explicit error state with a retry action, and the respondent is not asked to record again. If transcription fails after its retries, the testimonial still publishes with no caption track, the moderator is notified, and a "Retry transcription" action is offered — video is never blocked on transcription.

3.5.2 A moderator publishes, and a live widget reflects it #

sequenceDiagram
  autonumber
  participant M as Moderator (dashboard)
  participant W as apps/web (Node)
  participant PG as PostgreSQL
  participant Q as Valkey / BullMQ
  participant WK as apps/worker
  participant CDN as CDN edge
  participant H as Host page widget

  M->>W: Server Action: publishTestimonial(id)
  W->>W: can(actor, 'testimonial:publish', resource) (Section 6)
  W->>PG: BEGIN; SET LOCAL app.current_workspace_id
  W->>PG: UPDATE testimonials SET status='published', published_at=now()
  W->>PG: INSERT audit_events (before/after snapshot, actor, ip, ua)
  W->>PG: INSERT outbox_events (widget.cache.purge, testimonial.published)
  W->>PG: COMMIT
  W-->>M: optimistic UI update, then revalidated Server Component
  WK->>PG: claim outbox rows (FOR UPDATE SKIP LOCKED)
  WK->>PG: recompute affected widget payloads
  WK->>CDN: purge by tag widget:{id} and workspace:{id}
  WK->>WK: dispatch testimonial.published webhook (signed, Section 7)
  H->>CDN: next data refresh (max-age 60, SWR 300)
  CDN-->>H: fresh payload including the new testimonial

Steady-state propagation to a host page is bounded by the 60-second max-age on the widget payload plus the CDN purge, so a newly published testimonial appears in embeds within seconds of the purge completing and no later than 60 seconds in any case.

3.5.3 A widget loads on a third-party page #

sequenceDiagram
  autonumber
  participant B as Visitor browser on a customer's site
  participant CDN as CDN edge
  participant E as Edge runtime route
  participant PG as PostgreSQL

  B->>CDN: GET /e.js (async, no SRI, immutable behaviour)
  CDN-->>B: 5 KB loader, long-lived cache
  B->>B: loader finds every [data-vouch-widget], batches the ids
  B->>CDN: GET /api/v1/widgets/data?ids=wgt_a,wgt_b
  alt cache hit (typical)
    CDN-->>B: pre-rendered JSON, <=60 KB, CORS *
  else cache miss
    CDN->>E: forward
    E->>PG: read pre-rendered payloads (read replica acceptable)
    E-->>CDN: JSON, Cache-Control public, max-age=60, SWR=300
    CDN-->>B: JSON
  end
  B->>CDN: GET runtime chunk (content-hash pinned by the loader)
  CDN-->>B: <=22 KB runtime
  B->>B: attach open shadow root, adopt one stylesheet, render via textContent
  B->>B: IntersectionObserver -> impression event queued in memory
  B->>CDN: sendBeacon /api/v1/e (batched, max 1 per 5s, no cookies)
  Note over B: Video chunk and player are imported only on first play

Exactly one network request happens before the widget's first paint: the JSON payload. The loader is already cached from e.js, the runtime chunk loads in parallel with the data, no fonts are requested, and the poster images are lazy with explicit dimensions so nothing shifts.

3.5.4 A custom domain goes from added to active #

sequenceDiagram
  autonumber
  participant U as Owner/Admin (dashboard)
  participant W as apps/web
  participant Q as BullMQ repeatable job
  participant DNS as Authoritative nameservers
  participant ACME as ACME CA
  participant EDGE as edge.vouch.app

  U->>W: POST /api/v1/custom-domains {hostname}
  W->>W: validate hostname, check plan entitlement (Section 19),<br/>check global uniqueness
  W->>W: insert custom_domains (state=pending_dns), generate challenge token
  W-->>U: exact records to create: CNAME + _vouch-challenge TXT
  loop client polling: 5s for 2 min, 15s to 10 min, 60s to 24 h
    U->>W: GET /api/v1/custom-domains/{id}
    W-->>U: state, last checked at, records observed, plain-English diff
  end
  loop server polling: every 5 min for 72 h
    Q->>DNS: resolve CNAME and TXT at authoritative nameservers
    DNS-->>Q: observed records
    alt records match
      Q->>W: state = dns_detected -> verifying -> issuing_tls
      Q->>ACME: request certificate (HTTP-01, DNS-01 fallback for apex)
      ACME-->>Q: certificate issued
      Q->>EDGE: install certificate, bind hostname
      Q->>W: state = active, notify Owner
    else records absent or wrong after 72 h
      Q->>W: state = failed, notify with the specific mismatch
    end
  end

The embed snippet on the customer's marketing site is untouched by all of this — the loader origin is permanent and the widget id resolves everything at runtime (Section 13).

3.6 Runtime Split: Edge versus Node #

The rule that makes the split decidable: a route runs on the Edge runtime if and only if it is publicly cacheable or cache-adjacent, needs no session, needs no privileged credential, and touches the database either not at all or through a single pre-rendered, read-only lookup. Everything else runs on Node. If you find yourself wanting an exception, the answer is Node.

Two hard constraints follow from this rule and must not be violated: no Edge route ever opens a write transaction, and no Edge route ever reads a session cookie or an API key secret. Anything Edge-served is safe to cache publicly, which is only true if it is identical for every viewer.

3.7 The Transactional Outbox #

Any effect that must happen exactly once and only if a database write committed goes through the outbox. This covers outbound webhooks, integration fan-out to Zapier, Slack, and HubSpot, CDN cache purges, media purge jobs, and notification sends.

The failure this prevents is the classic dual-write: enqueue a job, then the transaction rolls back, and now a webhook has announced something that never happened. Or: commit the transaction, then the process dies before the enqueue, and the webhook never fires.

The contract, at the architecture level. Section 5 owns the table's exact columns, types, and indexes.

1. Inside the same transaction as the domain write, insert one row per effect, containing: the workspace id, an event type from the catalogue in Section 29.4, an aggregate type and aggregate id, a JSONB payload, and a status of pending.
2. A relay in apps/worker polls with SELECT ... FOR UPDATE SKIP LOCKED LIMIT n, so many worker instances can relay concurrently without processing a row twice.
3. The relay performs the effect — enqueue a BullMQ job, dispatch a signed webhook, issue a CDN purge — and then marks the row dispatched with a timestamp.
4. Failures increment an attempt counter and set a next_attempt_at with exponential backoff. After the maximum attempts the row moves to failed and raises an operator alert.
5. Consumers are idempotent. Every job payload carries the outbox row's id, and every consumer is safe to run twice with the same id — because at-least-once delivery is what this pattern guarantees, and exactly-once processing is the consumer's job.
6. Dispatched rows are retained 30 days for debugging and then swept.

// packages/core/outbox/emit.ts — conceptual shape; Section 5 owns the schema.
export async function emit(
  tx: Transaction,
  events: ReadonlyArray<{
    workspaceId: string;
    eventType: OutboxEventType;   // e.g. 'testimonial.published'
    aggregateType: 'testimonial' | 'widget' | 'workspace' | 'custom_domain';
    aggregateId: string;
    payload: Record<string, unknown>;
  }>,
): Promise<void> {
  // Runs on the SAME transaction handle as the domain write. Never opens its own.
  await tx.insert(outboxEvents).values(
    events.map((e) => ({ id: newId(), status: 'pending' as const, attempts: 0, ...e })),
  );
}

The rule for reviewers: if a code path calls an external system after a database write and is not inside emit(), it is a bug — unless the effect is genuinely safe to lose, in which case a comment must say so.

3.8 Caching Layers and Invalidation Ownership #

Four layers. Each has exactly one owner responsible for invalidating it, because caches with ambiguous ownership go stale.

Valkey key naming — mandatory scheme: vch:{env}:{concern}:{id}, where env is one of dev, test, staging, prod. Never construct a key by string concatenation at a call site; build it with a helper in packages/core/cache/keys.ts so every key is greppable.

The invariant that governs all caching: a cache may make something faster; it may never be the reason something is wrong. Any quota decision that blocks a user re-reads Postgres before blocking. Any permission decision reads Postgres, never a cache.

3.9 Failure-Domain Analysis #

State this invariant loudly, and design every dependency call to preserve it:

Published widgets keep serving in every failure scenario below. Widget payloads are pre-rendered and CDN-cached with stale-while-revalidate, so a host page continues to display published testimonials even when the origin, the database, or any third-party provider is entirely unavailable.

Every one of these is exercised by the chaos test in gate SC-9 (Section 2.9).

3.10 Scale Targets and the First Bottleneck #

Design targets for launch scale:

Where it breaks first, in order:

1. Analytics ingestion. At 500 million impressions a month, raw event volume dominates everything else. Mitigations, all designed in from the start: events are batched in the browser (one beacon per 5 seconds per page maximum), ingested at the Edge, written in bulk, partitioned by day, kept raw for only 7 days, and rolled up hourly and daily. The rollup tables are what the dashboard reads; nothing user-facing ever scans raw events.
2. Widget data API origin load. Solved by construction: the payload is pre-rendered, the CDN hit rate target is ≥ 90%, stale-while-revalidate means even a miss serves instantly from stale, and the batched ?ids= form collapses multiple widgets on one page into one request. A page with six widgets makes one data request, not six.
3. Postgres write throughput on audit_events and outbox_events. Both are append-heavy. Both use UUIDv7 primary keys, which are time-ordered and therefore preserve index locality on insert — this is precisely why identifiers are UUIDv7 and generated application-side (Section 5). audit_events is partitioned by month; outbox_events is swept after 30 days.
4. Object storage cost, not throughput. Original uploads are deleted 30 days after the asset reaches ready unless the workspace has explicitly enabled "keep originals"; abandoned upload sessions are swept after 24 hours. Without those two sweeps, storage grows without bound.
5. Transcription cost. Bounded per plan by the transcription-minutes entitlement in Section 19, enforced server-side before a job is enqueued rather than after the provider has been billed.

The shape to keep in mind: the read path is almost entirely at the edge, and the write path is almost entirely asynchronous. Synchronous origin work happens only for dashboard interactions, submissions, and API writes — which are, by orders of magnitude, the smallest share of total traffic.

4. Conventions, Code Standards & Project Structure #

These conventions are not stylistic preferences. Each one exists because a specific class of defect becomes impossible when it is followed. Reviewers enforce them; the linter enforces what it can.

4.1 Naming Conventions #

4.1.1 Database #

snake_case throughout. Tables are plural nouns. Join tables are the two entity names in alphabetical order joined by an underscore. Booleans are prefixed is_ or has_. Timestamps end in _at. Foreign keys are {singular_referenced_table}_id. Money columns end in _cents and always have a sibling currency column of type char(3).

4.1.2 TypeScript #

camelCase for values and functions, PascalCase for types, interfaces, classes, and React components, SCREAMING_SNAKE_CASE for module-level constants. No Hungarian notation, no I prefix on interfaces, no T prefix on types.

4.1.3 Files and Directories #

Files are kebab-case. React component files are kebab-case.tsx and export a PascalCase component. Test files sit beside their subject as *.test.ts; end-to-end specs live in e2e/*.spec.ts. Directory names are kebab-case and singular when they name a concept, plural when they hold a collection.

There is no utils.ts, no helpers.ts, and no misc.ts anywhere in this repository. A file whose name does not describe its contents is a file nobody can find twice.

4.1.4 API Paths #

/api/v1/{plural-kebab-resource}. Nesting is one level maximum. No verbs in paths, with the single exception of explicit action sub-resources on a specific entity.

The workspace never appears in the path. It is derived from the authenticated API key or session, because a workspace id in a URL is an authorization mistake waiting to happen.

4.1.5 Query Parameters and JSON Bodies #

camelCase for both. Drizzle maps camelCase TypeScript fields to snake_case columns, so the transformation happens exactly once, in the schema definition, and never in a handler.

There is no page or offset parameter anywhere in this product. Cursor pagination is the only pagination model, and Section 7 owns its shape.

4.1.6 Environment Variables #

SCREAMING_SNAKE_CASE, prefixed by the concern they belong to. Every variable is catalogued exactly once, in Section 29.2, with its type, whether it is required, its default, and whether it is a secret.

Environment variables are read in exactly one place — packages/config/env.ts — where they are parsed and validated by a Zod schema at process start. The process refuses to boot if a required variable is missing or malformed. No other file calls process.env, and an ESLint rule enforces it.

4.1.7 Feature Flags #

Prefixed flag_, stored in the feature_flags table, evaluated server-side only. A flag resolves against a workspace and returns a boolean; the client receives the resolved value, never the flag list.

4.1.8 Git #

Trunk-based development. main is protected and always deployable. Branch names are type/short-slug where type is one of feat, fix, chore, docs, refactor, test, or perf. Commit messages follow Conventional Commits.

4.1.9 Public Identifiers #

Primary keys are UUIDv7, generated application-side. That raw form is never emitted. Every identifier that crosses a public boundary — a REST response, a widget payload, a webhook envelope, a dashboard URL, an error message, a log line — is prefix + the Crockford base32 encoding of the row's UUIDv7, 26 characters after the prefix, and carries its prefix every time. No identifier is ever emitted unprefixed.

Section 5.1.1 owns the prefix table and is the only place a prefix is assigned. A prefix that is not in that table does not exist: if you need one for a new entity, add it there rather than inventing it at a call site.

Two consequences worth stating because they are easy to miss: a support conversation and a trace both quote the prefixed form, so the prefix is what makes an id greppable across a log sink; and the prefix is part of the public contract, so changing one is a breaking API change under the versioning rule in Section 7.

4.2 Module Boundaries #

The dependency graph is a strict hierarchy. Violating it is the fastest way to make the widget's size budget unenforceable and the domain logic untestable.

apps/web ──┐
apps/worker┼──> packages/core ──> packages/validation
           │         │
           │         └──────────> packages/db
apps/web ──┴──> packages/ui ────> packages/config
apps/embed ──> (nothing from packages/ui, nothing from React)

The rules:

1. apps/* may import from packages/*. packages/* may never import from apps/*.
2. packages/db is the only place that contains SQL or Drizzle query construction. If a handler builds a query, that is a boundary violation.
3. packages/core holds domain logic and is framework-free: no React, no Next.js imports, no HTTP objects, no direct SQL. It receives a transaction handle and typed inputs, and returns typed results or throws an AppError. This is what makes it testable without a server.
4. packages/validation depends on nothing but Zod. It is imported by everything.
5. packages/ui may import React, Radix, and packages/config. It must not import packages/db or packages/core — components receive data as props.
6. apps/embed may import nothing from packages/ui and nothing from React. It may import types (type-only imports, erased at compile time) from packages/validation to keep the widget payload contract in sync. Any value import from a package that pulls in a framework fails the build.
7. apps/web and apps/worker never import from each other. Shared logic moves to packages/core.

Enforced by ESLint. This configuration lives in packages/config/eslint:

// packages/config/eslint/boundaries.js
const RESTRICTED = {
  // packages/* must never reach into apps/*
  packages: [
    { group: ['@vouch/../apps/*', '**/apps/*'], message:
      'packages/* must not import from apps/*. Move shared logic into packages/core.' },
  ],
  // packages/core stays framework-free and SQL-free
  core: [
    { group: ['react', 'react-dom', 'next', 'next/*'], message:
      'packages/core is framework-free. Keep React and Next.js out of domain logic.' },
    { group: ['drizzle-orm', 'drizzle-orm/*', 'postgres', 'pg'], message:
      'Only packages/db constructs SQL. Import a typed query helper from @vouch/db instead.' },
  ],
  // packages/ui renders; it does not fetch or query
  ui: [
    { group: ['@vouch/db', '@vouch/db/*', '@vouch/core', '@vouch/core/*'], message:
      'packages/ui receives data as props. Fetch in a Server Component and pass it down.' },
  ],
  // the widget ships zero framework bytes
  embed: [
    { group: ['react', 'react-dom', 'preact', 'vue', 'svelte', '@vouch/ui', '@vouch/ui/*',
              '@vouch/core', '@vouch/core/*', '@vouch/db', '@vouch/db/*', 'tailwindcss'],
      message:
      'apps/embed ships zero framework bytes and hand-authored CSS. Type-only imports from '
      + '@vouch/validation are the sole permitted cross-package reference.' },
  ],
  // env is parsed once, centrally
  env: [
    { group: ['**/process.env*'], message:
      'Read configuration from @vouch/config env, which validates at boot.' },
  ],
};

module.exports = {
  overrides: [
    { files: ['packages/**/*.ts', 'packages/**/*.tsx'],
      rules: { 'no-restricted-imports': ['error', { patterns: RESTRICTED.packages }] } },
    { files: ['packages/core/**/*.ts'],
      rules: { 'no-restricted-imports': ['error',
        { patterns: [...RESTRICTED.packages, ...RESTRICTED.core] }] } },
    { files: ['packages/ui/**/*.ts', 'packages/ui/**/*.tsx'],
      rules: { 'no-restricted-imports': ['error',
        { patterns: [...RESTRICTED.packages, ...RESTRICTED.ui] }] } },
    { files: ['apps/embed/**/*.ts'],
      rules: {
        'no-restricted-imports': ['error', { patterns: RESTRICTED.embed }],
        // the widget targets ES2022 and ships no polyfills
        'no-restricted-syntax': ['error',
          { selector: "CallExpression[callee.name='require']",
            message: 'apps/embed is ESM-only; esbuild bundles it to an IIFE.' }],
      } },
    { files: ['**/*.ts', '**/*.tsx'],
      excludedFiles: ['packages/config/env.ts'],
      rules: { 'no-restricted-properties': ['error',
        { object: 'process', property: 'env',
          message: 'Import validated config from @vouch/config instead of reading process.env.' }] } },
  ],
};

The apps/embed rule is backed by a second, independent check: a CI assertion over esbuild's metafile that no framework package appears anywhere in the widget's module graph (gate SC-2 in Section 2.9). Lint rules can be disabled with a comment; the metafile assertion cannot.

4.3 Errors and the Result Convention #

One base class. Every error the application raises deliberately is an AppError or a subclass. Everything else is unexpected by definition and is treated as such.

// packages/core/errors/app-error.ts
export interface AppErrorDetail {
  /** Dot-path to the offending field, e.g. "fields.email" or "consents[0].granted". */
  field: string;
  /** Human-readable, safe to show an end user. Never contains internal identifiers. */
  issue: string;
}

export class AppError extends Error {
  /** SCREAMING_SNAKE, stable forever, catalogued once in Section 29.3. */
  readonly code: string;
  readonly httpStatus: number;
  /** Safe to render to an end user in any locale-neutral surface. */
  readonly publicMessage: string;
  /** Always an array when present. Section 7.3 owns which statuses may carry it. */
  readonly details?: AppErrorDetail[];
  /** Never serialized to a client. Logged with the request id. */
  readonly cause?: unknown;

  constructor(args: {
    code: string;
    httpStatus: number;
    publicMessage: string;
    details?: AppErrorDetail[];
    cause?: unknown;
  }) {
    super(args.publicMessage);
    this.name = 'AppError';
    this.code = args.code;
    this.httpStatus = args.httpStatus;
    this.publicMessage = args.publicMessage;
    this.details = args.details;
    this.cause = args.cause;
  }
}

export class NotFoundError extends AppError { /* httpStatus 404 */ }
export class ForbiddenError extends AppError { /* httpStatus 403 */ }
export class ValidationError extends AppError { /* httpStatus 422, details required */ }
export class ConflictError extends AppError { /* httpStatus 409 */ }
export class QuotaExceededError extends AppError { /* httpStatus 409 with a plan hint; Section 19.5.7 */ }
export class DependencyUnavailableError extends AppError { /* httpStatus 503, sets Retry-After */ }

The route-level boundary. Exactly one function converts a thrown value into an HTTP response. Section 7.3 owns the envelope's shape; this boundary is the only code that produces it.

// apps/web/lib/http/error-boundary.ts
export function toErrorResponse(err: unknown, requestId: string): Response {
  if (err instanceof AppError) {
    log.warn({ requestId, code: err.code, status: err.httpStatus }, 'handled error');
    return jsonError({
      code: err.code,
      message: err.publicMessage,
      details: err.details,
      httpStatus: err.httpStatus,
      requestId,
    });
  }
  // Unexpected: log everything, return nothing.
  log.error({ requestId, err }, 'unhandled error');
  captureException(err, { tags: { requestId } });
  return jsonError({
    code: 'INTERNAL_ERROR',
    message: 'Something went wrong on our side. Please try again.',
    httpStatus: 500,
    requestId,
  });
}

The rules:

1. Every non-2xx response in the entire product uses the canonical envelope defined in Section 7.3. There are no exceptions and no bespoke error shapes. Section 7.3 owns that envelope's field list, its status rules, and its error-code semantics; this section deliberately does not restate them, so read 7.3 before adding a field or a status to an error path.
2. Unexpected errors are logged in full with the request id and returned as a generic 500 with no internal detail — no stack, no SQL, no provider message, no identifier the client did not already know.
3. Every error carries the request id — in the response envelope, in the X-Request-Id header, and in every log line for that request. A support conversation starts by asking for that id.
4. details is always an array when present, even with a single entry. Which statuses may carry it is Section 7.3's decision, not this section's.
5. packages/core throws AppError; it never returns an HTTP status and never touches a Response. Transport is the app layer's job.
6. Never catch and silently continue. Either handle the error meaningfully, rethrow it, or convert it to an AppError with a code.
7. Error codes are permanent. Adding one is free; changing or removing one is a breaking API change and follows the versioning rule in Section 7.

4.4 Validation #

One Zod schema per boundary, in packages/validation, used by all four consumers. The client form, the server route or action, the worker job, and the public API validate with the same object. This is the single most important convention in the codebase, because it makes it structurally impossible for the client to accept something the server rejects.

Naming pattern:

// packages/validation/testimonial.ts
import { z } from 'zod';
import { publicId } from './public-id';   // prefix + Crockford base32 (Section 4.1.9)

export const testimonialStatus = z.enum([
  'pending', 'approved', 'published', 'unpublished', 'rejected', 'archived',
]);

export const createTestimonialInput = z.object({
  requestPageId: publicId('rqp_'),               // never a raw uuid on a public boundary
  kind: z.enum(['video', 'text']),
  // Opaque server-issued handle (Section 9.6), not a public resource id.
  // Required when kind === 'video'.
  uploadSessionId: z.string().min(1).max(64).optional(),
  body: z.string().trim().min(20).max(5000).optional(), // required when kind === 'text'
  rating: z.number().int().min(1).max(5).optional(),
  author: z.object({
    name: z.string().trim().min(1).max(120),
    email: z.email().max(254),
    role: z.string().trim().max(120).optional(),
    company: z.string().trim().max(120).optional(),
    websiteUrl: z.url().max(2048).optional(),
  }),
  customFields: z.record(z.string(), z.union([z.string().max(2000), z.number(), z.boolean()]))
    .default({}),
  consents: z.array(z.object({
    kind: z.enum(['publish', 'advertising', 'case_study_contact']),
    granted: z.boolean(),
  })).min(1),
}).superRefine((v, ctx) => {
  if (v.kind === 'video' && !v.uploadSessionId) {
    ctx.addIssue({ code: 'custom', path: ['uploadSessionId'],
      message: 'A completed upload session is required for a video testimonial.' });
  }
  if (v.kind === 'text' && !v.body) {
    ctx.addIssue({ code: 'custom', path: ['body'],
      message: 'Testimonial text is required.' });
  }
  if (!v.consents.some((c) => c.kind === 'publish' && c.granted)) {
    ctx.addIssue({ code: 'custom', path: ['consents'],
      message: 'Permission to publish is required.' });
  }
});

export type CreateTestimonialInput = z.infer<typeof createTestimonialInput>;

// The public shape embedded in widget payloads. Deliberately narrow: no email,
// no IP, no internal identifiers, no consent detail.
export const testimonialPublicOutput = z.object({
  id: publicId('tst_'),                          // prefixed, always (Section 4.1.9)
  kind: z.enum(['video', 'text']),
  bodyHtml: z.string().nullable(),               // sanitized at write and at serve time
  rating: z.number().int().min(1).max(5).nullable(),
  author: z.object({
    name: z.string(),
    role: z.string().nullable(),
    company: z.string().nullable(),
    avatarUrl: z.url().nullable(),
  }),
  video: z.object({
    playbackId: z.string(),
    posterUrl: z.url(),
    durationSeconds: z.number(),
    captionsUrl: z.url().nullable(),
    aspectRatio: z.string(),                     // e.g. "9:16", used to reserve layout space
  }).nullable(),
  source: z.enum(['collected', 'google', 'g2', 'capterra', 'x', 'csv']),
  sourceUrl: z.url().nullable(),
  publishedAt: z.iso.datetime(),
});

The rules:

1. Validate at every boundary, including boundaries you control. A worker job payload is validated on dequeue even though the same process family enqueued it, because a payload can sit in a queue across a deploy that changed its shape.
2. Never trust a type assertion at a boundary. as CreateTestimonialInput on parsed JSON is forbidden; createTestimonialInput.parse(json) is the only accepted form.
3. Validation failures produce a 422 with a details array built from the Zod issue list. The mapping from Zod issues to AppErrorDetail lives in one function.
4. Output schemas are as important as input schemas. testimonialPublicOutput is what guarantees a respondent's email address can never leak into a widget payload — the payload is parsed through the output schema before serialization, so an added field does not silently escape.
5. Maximum lengths are always specified. An unbounded string is a denial-of-service vector and a storage-cost surprise.

4.5 Data Access #

Three rules, all mandatory, all enforceable in review:

1. Every query lives in packages/db/queries as a named, typed function. Handlers call those functions; handlers never build queries.
2. Every query is workspace-scoped, and every read of a soft-deletable entity goes through the notDeleted() helper.
3. Every query runs inside a transaction that has already set the Row-Level Security session variable. Section 6 owns the RLS model, the roles, and the policy definitions.

// packages/db/queries/testimonials.ts
import { and, desc, eq, lt, or } from 'drizzle-orm';
import { notDeleted } from '../helpers/not-deleted';
import { testimonials } from '../schema';
import type { Tx } from '../types';

/**
 * Lists testimonials for a workspace, newest first, cursor-paginated.
 * The caller must already be inside a transaction with app.current_workspace_id set;
 * RLS is a second line of defence, not the first (Section 6).
 */
export async function listTestimonials(
  tx: Tx,
  args: {
    workspaceId: string;
    status?: TestimonialStatus;
    cursor?: { createdAt: Date; id: string };
    limit: number; // caller has already clamped to 1..100 (Section 7)
  },
) {
  return tx
    .select()
    .from(testimonials)
    .where(and(
      eq(testimonials.workspaceId, args.workspaceId),
      notDeleted(testimonials),
      args.status ? eq(testimonials.status, args.status) : undefined,
      args.cursor
        ? or(
            lt(testimonials.createdAt, args.cursor.createdAt),
            and(
              eq(testimonials.createdAt, args.cursor.createdAt),
              lt(testimonials.id, args.cursor.id),
            ),
          )
        : undefined,
    ))
    .orderBy(desc(testimonials.createdAt), desc(testimonials.id))
    .limit(args.limit + 1); // one extra row decides pagination.hasMore
}

// packages/db/with-workspace.ts — the only way application code opens a transaction.
export async function withWorkspace<T>(
  workspaceId: string,
  fn: (tx: Tx) => Promise<T>,
): Promise<T> {
  return db.transaction(async (tx) => {
    // SET LOCAL is scoped to this transaction and reset automatically on commit or rollback,
    // which makes it safe with a connection pool.
    await tx.execute(sql`SET LOCAL app.current_workspace_id = ${workspaceId}`);
    return fn(tx);
  });
}

Additional rules:

• Passing a workspaceId that the actor is not a member of is caught by can() (Section 6) before a query runs, and by RLS if it somehow gets past. Two independent controls, both required.
• Background jobs call withWorkspace() with the workspace id from the job payload. There is no "system" bypass in application code; the only role that bypasses RLS is the migrator, and the application never connects as it.
• No raw SQL outside packages/db, and inside it only with parameter binding. String interpolation into SQL is forbidden.
• Batch inserts use a single statement. Because identifiers are UUIDv7 and generated application-side (Section 5), a batch insert is index-friendly and its ids are known before the write, which is what lets an outbox row reference an entity created in the same transaction.

4.6 Asynchronous Work and Jobs #

Every background job satisfies six requirements without exception. Section 29.5 catalogues every job in the product; this is the shape they all share.

// apps/worker/jobs/transcription-run.ts
export const transcriptionRun = defineJob({
  name: 'transcription.run',
  payload: transcriptionRunPayload,       // Zod schema from packages/validation
  attempts: 5,
  backoff: { type: 'exponential', delay: 30_000, maxDelay: 900_000, jitter: true },
  concurrency: 8,
  deadLetter: async ({ payload, error }) => {
    // Transcription failure never blocks publishing (Section 10).
    await markTranscriptFailed(payload.testimonialId, error.code);
    await notifyModerators(payload.workspaceId, 'transcription_failed', payload.testimonialId);
  },
  async handler({ payload, logger }) {
    return withWorkspace(payload.workspaceId, async (tx) => {
      const existing = await getTranscript(tx, payload.testimonialId);
      if (existing?.providerJobId === payload.providerJobId) {
        logger.info('already transcribed; idempotent no-op');
        return;
      }
      const transcript = await transcription.transcribe(payload.mediaUrl, {
        languages: LAUNCH_LANGUAGES,
        detect: true,
      });
      await saveTranscript(tx, payload.testimonialId, transcript);
      await emit(tx, [{
        workspaceId: payload.workspaceId,
        eventType: 'transcript.ready',
        aggregateType: 'testimonial',
        aggregateId: payload.testimonialId,
        payload: { language: transcript.language, confidence: transcript.confidence },
      }]);
    });
  },
});

Additional rules:

• A job name is domain.snake_case_verb, and a hyphen never appears in one. One dotted domain segment, then a snake_case verb phrase: media.ingest, vtt.generate, cdn.purge, quota.notify_threshold, quota.roll_periods, retention.sweep_originals, retention.purge_soft_deleted. Never retention.purge-soft-deleted, never quota.rollPeriods, never a second dot. Every retention sweep lives in the single retention.* family. Section 29.5 catalogues every job in the product with its trigger, payload, idempotency key, retries, timeout, dead-letter behaviour and alert; a name that is not in that catalogue is not a job, and adding a job means adding the row.
• A job never enqueues another job directly from inside a transaction. It writes an outbox row and lets the relay enqueue (Section 3.7).
• A job never takes an unbounded amount of work. Sweeps and rollups process a bounded batch and re-enqueue themselves if more remains, so a single run cannot monopolise a worker.
• Every repeatable job declares a jitter so a fleet restart does not synchronise every instance onto the same second.
• Job payloads carry identifiers, never entity snapshots. The handler re-reads current state, because a payload written five minutes ago may describe a row that has since changed.

4.7 React and Next.js #

// apps/web/app/(dashboard)/testimonials/actions.ts
'use server';

export async function publishTestimonialAction(input: unknown) {
  const parsed = publishTestimonialInput.parse(input);
  const actor = await requireSession();                       // throws 401 as an AppError
  await can(actor, 'testimonial:publish', {
    type: 'testimonial', id: parsed.testimonialId,
  });                                                          // throws 403 as an AppError
  await withWorkspace(actor.workspaceId, (tx) =>
    publishTestimonial(tx, { actor, testimonialId: parsed.testimonialId }),
  );
  revalidateTag(`workspace:${actor.workspaceId}:testimonials`);
}

4.8 Styling #

Dashboard and request pages: Tailwind with a shared preset. The preset lives in packages/config/tailwind and is the only place that defines spacing, colour, radius, and type scale. Design tokens are emitted as CSS custom properties prefixed --vch-, so the same values are readable at runtime — which is what lets a request page apply a workspace's brand colour without a rebuild.

/* packages/config/tokens/base.css — the source of truth for both Tailwind and runtime theming */
:root {
  --vch-color-bg: #ffffff;
  --vch-color-surface: #f8fafc;
  --vch-color-text: #0f172a;          /* 16.1:1 on --vch-color-bg */
  --vch-color-text-muted: #475569;    /*  7.5:1 on --vch-color-bg */
  --vch-color-accent: #4f46e5;        /*  4.9:1 on --vch-color-bg for text use */
  --vch-color-accent-contrast: #ffffff;
  --vch-color-danger: #b91c1c;
  --vch-color-success: #15803d;
  --vch-radius-sm: 4px;
  --vch-radius-md: 8px;
  --vch-radius-lg: 16px;
  --vch-font-sans: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial,
    "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
  --vch-text-xs: 0.8rem;   --vch-text-sm: 1rem;    --vch-text-md: 1.2rem;
  --vch-text-lg: 1.44rem;  --vch-text-xl: 1.728rem; --vch-text-2xl: 2.074rem;
}

A unit test in packages/config asserts the contrast ratio of every foreground/background token pair against the thresholds in Section 21. Adding a token that fails fails the build.

The widget: hand-authored CSS, no Tailwind, no shared preset. This is deliberate, and the reasons are worth stating because a future contributor will otherwise "fix" it:

1. Size. Tailwind's output is generated per project from scanned class names. In a bundle with a 22 KB total budget, a utility-class stylesheet plus the class-name strings in markup costs more than a hand-authored stylesheet that contains only the rules actually needed.
2. Isolation. The widget renders into a shadow root and injects exactly one adopted stylesheet. It must never write to document.head or register global CSS. Hand-authored CSS scoped to :host makes that guarantee trivially auditable.
3. Theming. The widget's theming surface is a small, fixed set of CSS custom properties set on :host from the widget's configuration — accent, radius, font size scale, and the light/dark/auto mode. That is a simpler and smaller mechanism than a utility framework.
4. Independence. The widget's stylesheet must not change when the dashboard's design system changes. A shared preset would couple a third-party page's rendering to an internal design decision.

The widget stylesheet is a single file, authored with the same --vch- custom-property naming so the two systems read consistently, and it is size-checked as part of the runtime chunk budget in Section 23.

4.9 Accessibility Conventions in Code Review #

Section 21 owns the full accessibility specification, the WCAG 2.2 AA criteria, and the manual test matrix. These are the conventions a reviewer checks on every pull request:

1. Semantics first, ARIA second. Use <button>, <a href>, <nav>, <main>, <dialog>, <label>, <fieldset>. Reach for ARIA only when native semantics genuinely run out. A <div role="button" tabindex="0"> with a keydown handler is a defect when a <button> would do.
2. Never tabindex greater than 0. tabindex="0" to make a custom control focusable and tabindex="-1" for programmatic focus are both fine. A positive value breaks document order and is rejected in review.
3. Focus management is explicit. On client-side route change, move focus to the new page's <h1> and announce the change. On modal open, focus the first interactive element or the dialog itself; on close, restore focus to the trigger. On async content replacement, move focus deliberately or announce with a live region — never leave focus on a removed node.
4. No colour-only meaning. Every status, state, delta, and warning carries text or an icon with an accessible name in addition to colour. This is checked on moderation status pills, domain verification states, transcript confidence highlights, and analytics deltas.
5. Every interactive element has an accessible name. Icon-only buttons carry aria-label. Decorative images carry alt="". Meaningful images carry real alt text.
6. Images and video reserve their space. Explicit width and height or an aspect-ratio, always — this is a layout-shift requirement as much as an accessibility one.
7. Live regions are used sparingly and politely. aria-live="polite" for recording state and processing progress; role="alert" reserved for genuine errors. Never announce every tick of a timer.
8. Motion respects prefers-reduced-motion. No auto-advancing carousel, no autoplay, no parallax, no animated entrance that cannot be disabled.
9. Target sizes. Minimum 24×24 CSS pixels for any control; 44×44 for the primary recorder controls on touch.
10. Every drag has a non-drag equivalent. Carousel swipe always has visible buttons.

Automated axe-core checks run in CI against a fixture page for every request page variant and every widget type, and zero violations at "serious" or "critical" is a merge gate.

4.10 Documentation #

4.11 Linting, Formatting, Type-Checking, and CI Gates #

The exact CI gate sequence. Every one of these must pass before a pull request can merge into main:

pnpm install --frozen-lockfile
pnpm format:check          # Prettier, no writes
pnpm lint                  # ESLint, --max-warnings=0
pnpm typecheck             # tsc --noEmit across every package
pnpm db:check              # schema and committed migrations agree
pnpm test -- --coverage    # Vitest unit + integration, coverage thresholds enforced
pnpm build                 # every app and package builds
pnpm size                  # widget and request-page budgets, hard fail
pnpm test:e2e              # Playwright: functional + axe-core accessibility suites
pnpm test:perf             # Lighthouse CI against the widget fixture host page

No step may be skipped, and no step may be marked "continue on error". A flaky test is fixed or quarantined with an issue link, never ignored.

4.12 Commits, Branches, Pull Requests, and Review #

Branching. Trunk-based. main is protected, requires a passing CI run and one approving review, and is always deployable. Branches are short-lived — under two days — and named type/short-slug. No long-running release branches.

Commits. Conventional Commits: type(scope): subject, imperative mood, no trailing period, subject under 72 characters. type is feat, fix, chore, docs, refactor, test, perf, or build. scope is the package or app (web, worker, embed, db, core, validation, ui). A breaking change is marked with ! after the scope and explained in a BREAKING CHANGE: footer.

Pull requests. One logical change per pull request. A description that states what changed, why, and how it was verified. Screenshots or a short recording for any user-visible change. If the change touches the widget, the size-limit output is pasted into the description.

The PR checklist — reproduced in .github/pull_request_template.md:

- [ ] The change does one thing, and the title says what it is.
- [ ] Every new boundary validates its input with a Zod schema from packages/validation.
- [ ] Every new query is workspace-scoped, uses notDeleted() where applicable, and runs
      inside withWorkspace().
- [ ] Every deliberate failure throws an AppError with a code that exists in the error
      catalogue (Section 29.3); no bespoke error shapes.
- [ ] Any effect that must happen exactly once alongside a database write goes through the
      outbox, not a direct call.
- [ ] Any new background job declares a typed payload, retries, backoff, dead-letter
      behaviour, and is idempotent.
- [ ] Any status change, content edit, tag change, or consent change writes an audit event.
- [ ] Any new metered action is checked against the quota service server-side.
- [ ] New UI: semantic elements, keyboard operable, visible focus, no colour-only meaning,
      accessible names on icon-only controls, explicit media dimensions.
- [ ] axe-core passes with zero serious/critical violations on any changed surface.
- [ ] Widget changes: size-limit output pasted below and within budget; no framework import
      introduced; nothing written to document.head; no global added beyond window.Vouch.
- [ ] No secret, token, respondent email or phone number, or testimonial body appears in any
      log line.
- [ ] Tests added or updated; the full CI gate sequence passes locally.
- [ ] Irreversible decision? An ADR was added to docs/DECISIONS.md.
- [ ] Public API change? The route's TSDoc, its scopes, and its error codes are updated.

Review standards. Reviewers check correctness, boundary compliance, and the checklist — in that order. A reviewer who cannot tell whether a change is correct asks for a test rather than approving. Nitpicks are prefixed "nit:" and never block a merge. Any comment marked "blocking:" must be resolved by the author, not dismissed. The author merges after approval; the reviewer does not merge on the author's behalf.

5. Data Model & Database Schema #

This section is the single source of truth for persisted state. Every table name, column name, type, default, constraint, and index used anywhere else in this document is defined here. If another section names a column, it is one of the columns below; nothing else exists. An executing agent should be able to generate the entire Drizzle schema in packages/db from this section alone.

If any other section appears to contradict this one about a table, column, type, default, constraint, or index, this section wins and the other section is the defect.

The database is PostgreSQL accessed through Drizzle ORM with drizzle-kit for migrations (the version line is stated once, in Section 3.1). All DDL in this section is written as plain SQL because that is what the migrations contain; the Drizzle schema files are the TypeScript mirror of exactly these definitions.

5.1 Modelling rules that govern every table #

These rules are absolute. They are stated once here and are assumed by every table definition that follows.

5.1.1 Primary keys and identifiers #

• Every table's primary key is a UUIDv7 stored in a uuid column named id, with exactly three kinds of exception:

  • Join and rollup tables with a composite natural key, where a surrogate id would buy nothing and the natural key is what every query already carries: testimonial_tags (testimonial_id, tag_id), analytics_rollup_hourly, analytics_rollup_daily, and delivery_usage_days (workspace_id, usage_date, source).
  • Partitioned tables, whose primary key must include the partition key: analytics_events_raw and audit_events, both (occurred_at, id).
  • The one strict 1:1 table, workspace_settings, whose primary key is workspace_id, because a second settings row for a workspace must be impossible rather than merely unwritten. A 1:1 table's natural key is the single parent column, never a composite. two_factor_secrets is deliberately not in this category: it keeps a surrogate id and enforces one-per-user with UNIQUE (user_id), because column-level grants are easier to reason about on a table with an ordinary key.

• UUIDv7 values are generated application-side, never by the database. packages/db exports a single newId() helper and it is the only place a new identifier is minted:

  Copy

  // packages/db/src/id.ts
  import { uuidv7 } from 'uuidv7';
  
  /** The only identifier factory in the system. Never call a DB-side default. */
  export function newId(): string {
    return uuidv7();
  }

  There is deliberately no DEFAULT gen_random_uuid() on any id column. Application-side generation means an insert's identifier is known before the round trip, which is what makes batched inserts, the transactional outbox (outbox_events), and audit writes able to reference the row they are about to create inside the same statement group. UUIDv7 is time-ordered, so B-tree index locality is equivalent to a bigserial without exposing a guessable sequence.

• Public-facing identifiers are derived, never raw UUIDs in URLs where length matters. This table is the complete prefix register: no identifier is ever emitted unprefixed on any public surface, and a prefix not listed here does not exist. Unless the Encoding column says otherwise, the value is prefix + Crockford base32 of the row's UUIDv7 (26 characters, uppercase alphabet, lowercased on output).

  Prefix	Used by	Encoding
  wsp_	workspaces	Crockford base32 of the row's UUIDv7 (26 chars)
  usr_	users	Crockford base32 of the row's UUIDv7
  tst_	testimonials	Crockford base32 of the row's UUIDv7
  rqp_	request_pages	Crockford base32 of the row's UUIDv7
  sub_	submissions	Crockford base32 of the row's UUIDv7
  inv_	invites	Crockford base32 of the row's UUIDv7
  tag_	tags	Crockford base32 of the row's UUIDv7
  dom_	custom_domains	Crockford base32 of the row's UUIDv7
  wgt_	widgets.public_id	Crockford base32 of the row's UUIDv7; stored, immutable
  crd_	social_cards	Crockford base32 of the row's UUIDv7; appears in the Open Graph and Twitter card metadata a showcase page emits (Section 15.8.3)
  evt_	outbox_events and the webhook envelope's id (Section 18.3)	Crockford base32 of the row's UUIDv7
  dlv_	webhook_deliveries	Crockford base32 of the row's UUIDv7
  req_	request correlation ids	Crockford base32 UUIDv7 (Section 7 owns the envelope)
  key_	api_keys row identifier — the value that appears in API paths and responses (Section 7.15.4). Distinct from the plaintext key below: the id is safe to log and display, the plaintext is shown exactly once and never again	Crockford base32 of the row's UUIDv7
  vch_live_ / vch_test_	api_keys plaintext value	32 random base62 characters after the prefix
  vch_rp_	respondent portal bearer token (respondent_tokens)	32 random base62 characters after the prefix
  whsec_	webhook_endpoints secret	32 random base62 characters after the prefix

  Third-party identifiers we merely store (price_…, sub_…, in_… and other Stripe ids, Mux asset and playback ids) keep the provider's own form and are never re-encoded. The only Stripe prefix that collides with one of ours is sub_; ours is always produced from a submissions.id and lives in a submissionId field, Stripe's always lives in a stripe_subscription_id column, and no serializer emits both in the same object.

• Slugs are used where a URL must be short, typable, and human-meaningful: workspaces.slug, request_pages.slug, showcase_pages.slug, tags.slug. All slugs match ^[a-z0-9](?:[a-z0-9-]{1,46}[a-z0-9])$ (3–48 characters, lowercase, no leading/trailing or doubled hyphen) and are unique within their scope.

5.1.2 Timestamps #

• Every timestamp column is timestamptz, stored in UTC. There are no timestamp, date-only, or epoch-integer time columns anywhere except analytics_rollup_daily.bucket_date, which is a true calendar date in the workspace's reporting timezone and is documented as such.
• Every table has created_at timestamptz NOT NULL DEFAULT now().
• Every mutable table has updated_at timestamptz NOT NULL DEFAULT now() maintained by the shared trigger set_updated_at() (Section 5.16.1). Application code never sets updated_at.
• Domain timestamps are past-participle-named and nullable: published_at, approved_at, rejected_at, verified_at, purged_at, completed_at.
• Append-only tables (audit_events, transcript_revisions, consents) have created_at and no updated_at, because they are never updated.

5.1.3 Money #

Money is stored as integer minor units in integer columns named *_cents, always paired with a currency char(3) ISO-4217 column on the same row (or inherited from the parent subscription row where noted). There are no numeric or floating-point money columns. Where a row can only ever be USD in v1 (plans), the currency column still exists and is defaulted to 'USD' so that multi-currency pricing is a data change, not a migration.

5.1.4 Deletion policy #

Each entity type is on exactly one side of this line. There are no per-case exceptions.

invitations are not hard-deleted on acceptance. An accepted invitation is the evidence that a membership was offered and by whom, and INVITATION_ALREADY_USED (Section 29.3) requires the row to still exist when a used link is clicked again. Every terminal invitation — accepted, revoked, or expired — is retained 90 days from status_changed_at and then hard-deleted (Section 5.20). Section 6.8 owns the state machine.

testimonial_flags, testimonial_replies, usage_notifications, overage_notices, delivery_usage_days, transcription_jobs and usage_counters are hard-deleted only with their workspace: they are per-workspace history whose value is that it does not vanish.

Rules:

1. A soft-deleted row is invisible to every read path. packages/db exports a notDeleted() helper and every query builder in the application composes it:

   Copy

   // packages/db/src/filters.ts
   import { isNull, and, eq, type SQL } from 'drizzle-orm';
   
   /** Appended to every read of a soft-deletable table. Enforced by lint rule `vouch/no-raw-select`. */
   export const notDeleted = <T extends { deletedAt: any }>(t: T): SQL =>
     isNull(t.deletedAt);
   
   export const inWorkspace = <T extends { workspaceId: any }>(t: T, workspaceId: string): SQL =>
     eq(t.workspaceId, workspaceId);
   
   export const scoped = <T extends { workspaceId: any; deletedAt: any }>(t: T, workspaceId: string) =>
     and(inWorkspace(t, workspaceId), notDeleted(t))!;

2. Soft deletion never orphans external assets. Soft-deleting a testimonials row enqueues media.purge (Section 9.10.2) with a delay equal to the 30-day restore window described in Section 11.2.3 T11, so that a restore inside the window still has its media. The job id is deterministic — media.purge:{testimonialId} — precisely so that restoring the testimonial can cancel the pending job by id (Section 11.2.3 T12). GDPR erasure enqueues the same job with zero delay. When it runs, media.purge destroys the Mux asset, every object-storage key, and the CDN cache entries before setting media_assets.purged_at. A row is never treated as permanently deleted while its assets survive.

3. GDPR erasure is always a hard delete. It removes the row rather than stamping deleted_at, and it is the only path that deletes from consents and audit_events (see Section 22.6 for the narrow, logged exception procedure for append-only tables).

4. Unique constraints on soft-deletable tables are partial: UNIQUE (...) WHERE deleted_at IS NULL. This lets a workspace re-use a slug after deleting the row that held it.

5.1.5 Postgres enum versus lookup table #

• A Postgres native enum type is used when the product owns the value set and it cannot expand at runtime: statuses, kinds, states, roles. Adding a value is a deliberate migration.
• A lookup table is used when an operator or a customer can extend the set: tags, plans, feature_flags, consent_versions.
• Custom request-page field types are an enum, not a lookup table. A customer defines as many fields as they like (request_page_fields is a table of definitions), but the seven types a field may have are fixed, because Section 8.5.2 attaches per-type validation rules and per-type mobile rendering to each one. A type added at runtime would have neither, so runtime extension is impossible by construction and request_field_type is a native enum.
• Third-party value sets that we mirror rather than own (Stripe subscription status, Mux asset state) are stored as the provider's raw string in a *_raw column and mapped into our own enum. We never widen our enum to chase a provider's vocabulary.

5.1.6 The tenancy column, and its three documented exceptions #

Every domain table carries workspace_id uuid NOT NULL REFERENCES workspaces(id), including tables that are only ever reached through a parent. The reasoning and the RLS machinery are owned by Section 6.2; the schema consequence is stated here so no table definition is surprising.

There are exactly three categories of table without workspace_id, and no others may be added:

workspace_members and invitations carry workspace_id and are therefore fully workspace-scoped even though they reference global users.

The tables a reader will ask about, resolved explicitly. Each of the following was considered for the nullable-tenant category and each is workspace_id uuid NOT NULL, so no fourth exception is needed:

Tenant-detached-on-purge. Three tables — invoices, refunds, trial_grants — declare workspace_id nullable but are never written with a null. The column is nulled only by the workspace-purge procedure, because each of these rows must outlive the workspace: financial records for the operator's books, and the trial guard so that a purge is not a way to earn a second free trial (Sections 5.11.12 and 5.12). They share the nullable-tenant RLS policy and, like the other nullable-tenant tables, no tenant-facing endpoint reads a detached row. This is not a fourth category: they are ordinary workspace-scoped tables for the whole time a workspace exists.

One table keeps a NOT NULL tenancy column with no foreign key behind it: erasure_log (Section 5.9.7). It must survive a workspace purge intact rather than detached, because it is the evidence that a person's data was destroyed and it is retained six years. A nullable, detached tenancy column would have lost which workspace the erasure belonged to; a foreign key would have cascaded the row away. So the column is NOT NULL, is still the RLS predicate, and is simply not enforced by a constraint. It is the only table in the schema written this way.

5.1.7 JSONB rules #

JSONB is used only for these four purposes, and every JSONB column in this section falls into one of them:

1. Provider payload capture — imported_reviews.raw_payload, stripe_events.payload, ai_suggestions.raw_response, invoices.provider_payload. Kept verbatim for audit and re-processing. Never queried by a hot path.
2. Genuinely open-shape user configuration — widgets.config, request_pages.theme, request_page_fields.options, inbox_saved_views.filter. Every one of these has a Zod schema in packages/validation that is the real contract, validated on write and on read.
3. Immutable document structures — transcripts.doc (the single transcript structure defined in Section 10.3), audit_events.before / .after, submission_drafts.answers, overage_evaluations.inputs.
4. Sparse per-row metadata — submissions.custom_field_values, testimonials.case_study_fields, analytics_events_raw.extras, testimonial_replies.attachments.

Where custom-field answers live, stated once. The answers a respondent gives to the customer-defined fields of a request page are stored on the submission, in submissions.custom_field_values, and nowhere else. testimonials has no custom_field_values column: a testimonial reaches its answers by joining testimonials.submission_id → submissions.id. Imported and manually created testimonials have no submission and therefore no custom-field answers, which is correct rather than missing — those fields are a property of the collection form, not of the testimonial. The column holds a versioned object keyed by field key, never an array; the shape, its default, and its check constraints are in Section 5.5.7, and Section 8.5.3 owns the capture and the answer format.

JSONB is never used to avoid designing a column. Anything filtered, sorted, joined, or aggregated is a real column. Where a JSONB key must be queried, a GIN index with jsonb_path_ops is declared explicitly in Section 5.13.

5.1.8 Secrets at rest #

Columns named *_encrypted hold envelope-encrypted values, never plaintext. The stored value is base64 of a JSON structure { "v": 1, "k": "<key-version>", "iv": "<12-byte base64>", "ct": "<ciphertext base64>", "tag": "<16-byte base64>" }, produced by AES-256-GCM using a data key wrapped by the platform KMS key referenced in Section 26. packages/db exposes encryptSecret() / decryptSecret() and no other code may construct the structure.

Columns named *_hash hold a SHA-256 digest, hex-encoded, 64 characters, char(64), and the plaintext is shown to a human exactly once at creation. This applies to api_keys.key_hash, invitations.token_hash, invites.token_hash, respondent_tokens.token_hash, sessions.token_hash, verification_tokens.token_hash, submission_drafts.token_hash. The same 64-character digest form is also used for the non-secret fingerprints suppressions.address_hash, trial_grants.billing_email_hash, and abuse_blocks.subject_hash, where the point is to compare without storing the raw value at all. Passwords are the exception: they use argon2id via better-auth (parameters in Section 6.5.3) and live in accounts.password_hash.

5.1.9 Required extensions #

CREATE EXTENSION IF NOT EXISTS citext;      -- case-insensitive email, hostname, slug comparison
CREATE EXTENSION IF NOT EXISTS pg_trgm;     -- fuzzy near-duplicate detection on imported reviews
CREATE EXTENSION IF NOT EXISTS btree_gin;   -- composite GIN indexes mixing tsvector with scalars
CREATE EXTENSION IF NOT EXISTS pgcrypto;    -- digest() for in-database integrity checks in tests

Extensions are created in the first migration, owned by vouch_migrator, and installed into the extensions schema which is on the search path. No other extension may be added without a migration and an entry in the future developer's docs/DECISIONS.md.

5.1.10 Standard column preamble and how DDL is presented here #

Unless a table's definition says otherwise, every table has:

  id          uuid        PRIMARY KEY,                        -- UUIDv7 from newId()
  workspace_id uuid       NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
  created_at  timestamptz NOT NULL DEFAULT now(),
  updated_at  timestamptz NOT NULL DEFAULT now()

Column tables below are the normative definition: every column, its type, nullability, default, and meaning. CREATE TABLE SQL is given wherever the DDL carries information the column table cannot — check constraints, partial unique indexes, generated columns, partitioning, privileges, exclusion constraints. Where a table's DDL is the mechanical translation of its column table plus this preamble, the SQL is not repeated; the migration still contains it.

5.1.11 Object storage key convention #

Every *_object_key column holds a key in the single application bucket, never a URL, never a host. Keys are:

workspaces/{workspaceId}/{kind}/{entityId}/{filename}

kind is one of originals, posters, captions, avatars, company-logos, brand, social-cards, exports, imports, backgrounds. Example:

workspaces/018f8b2c-1a4d-7b31-9c02-2f0a5b1d7e10/originals/018f8b2c-2233-7c00-91aa-9f3b0d2c4e55/take-01.mp4

Storing keys rather than URLs means the CDN host, the bucket, and the signing strategy can all change without a data migration. Public URLs are composed at read time by packages/core/storage/url.ts.

5.2 Enum type catalogue #

Every native Postgres enum in the system, with every allowed value. Adding a value is a forward-only migration (ALTER TYPE ... ADD VALUE, which cannot run inside a transaction block — see the expand/contract rules in Section 5.17.4). Removing a value is never done; a retired value is left in the type and rejected at the validation layer.

On invite_status, and why it is not invitation_status. These are two different enums on two different tables and they are never interchangeable. invitation_status (pending, accepted, expired, revoked) belongs to invitations — an offer of a seat to a teammate, which is accepted or not. invite_status belongs to invites — a request for a testimonial sent to a respondent, which travels a delivery-and-engagement funnel. A seat offer cannot bounce and a testimonial request cannot be accepted; giving them one enum would have produced a type on which half the values are meaningless whichever row you are holding. Section 5.4.4 keeps the table names deliberately apart for the same reason.

invite_status's fourteen values, with the terminal ones marked. Section 20.7 owns the send cadence; this is the vocabulary it moves through:

The pairs that look redundant are the ones carrying the most weight. bounced versus failed separates "their mailbox rejected us" from "we never got off the ground", which are different problems with different owners — one is a list-hygiene issue for the customer, the other is an incident for us. complained is a third thing again, and folding it into bounced would be the costliest mistake of the three: a bounce is a fact about an address and can be transient, whereas a complaint is a decision by a person, is permanent, and carries a deliverability penalty from the provider. It must suppress future sends where a soft bounce must not. revoked versus canceled separates "recall the link we sent" from "never send one", which matter differently to a respondent: one may already have the message in their inbox and the other never will. Collapsing any of these pairs would make the deliverability reporting in Section 20.10 unable to state what actually happened.

On dotted enum labels. usage_metric's labels contain a period (storage.bytes). Postgres enum labels are arbitrary strings, so this is legal, and it is deliberate: the same literal is the metric key in the quota API (Section 19.5), the notification key, and the column value, so there is exactly one spelling of each metric in the whole system and no translation table.

On billing_state and limit_state. These are two orthogonal facts about a workspace and they were deliberately split into two enums rather than combined into one status column. "The card was declined" and "you have more testimonials than your plan allows" can be true independently, in any combination, and each is cleared by a different action. A single column would force the two to be encoded as one value and would make "past due and over limit" unrepresentable. There is no workspace_status type and no workspaces.status column; Section 19.8 owns the transitions of both.

On ai_suggestion_state: expired and stale are different. expired is time-based — the proposal passed expires_at without anyone acting on it. stale is content-based — the testimonial or transcript the proposal was made against has since changed, so the proposal may no longer be verbatim and must never be shown or accepted. Section 12.4's metrics count them separately because they mean different things about the assistant's usefulness.

On analytics_event_type and video progress. There are no video_complete_25/50/75/100 values. Progress markers ride in the event payload: a video_progress event carries its percentage in analytics_events_raw.extras as {"pct":25} — the object the beacon sends as x (Section 17.3 owns the marker set). Encoding the percentage in the type would have made "add a 10 % marker" a migration; encoding it in the payload makes it a client change.

On testimonial_status and deletion. Soft deletion is orthogonal to lifecycle status: a deleted testimonial keeps whatever status it held and gains a non-null deleted_at. There is deliberately no deleted enum value, because a status value would make "what was this row's state when it was removed?" unanswerable. The public API projects a derived status of "deleted" when deleted_at IS NOT NULL; that projection lives in packages/core/testimonial/serialize.ts and is the only place the derived value is produced.

5.3 Entity-relationship diagrams #

Three diagrams, split so each stays legible. Attributes shown are keys and discriminators only; the full column lists are in Sections 5.4–5.11.

5.3.1 Identity, tenancy and billing #

erDiagram
    users ||--o{ workspace_members : "is member via"
    users ||--o{ sessions : "has"
    users ||--o{ accounts : "has credential"
    users ||--o| two_factor_secrets : "may have"
    workspaces ||--o{ workspace_members : "has"
    workspaces ||--|| workspace_settings : "has one"
    workspaces ||--o{ invitations : "issues"
    workspaces ||--o{ api_keys : "owns"
    workspaces ||--o{ workspace_feature_flags : "overrides"
    workspaces ||--o| subscriptions : "has current"
    workspaces ||--o{ usage_counters : "meters"
    workspaces ||--o{ usage_notifications : "warned by"
    workspaces ||--o{ usage_credits : "credited by"
    workspaces ||--o{ usage_reconciliations : "audited by"
    workspaces ||--o{ overage_evaluations : "evaluated by"
    workspaces ||--o{ overage_notices : "noticed by"
    workspaces ||--o{ delivery_usage_days : "meters delivery"
    workspaces ||--o| trial_grants : "granted once"
    workspaces ||--o{ cancellation_reasons : "explains exit"
    workspaces ||--o{ abuse_blocks : "may scope"
    plans ||--o{ workspaces : "priced by"
    plans ||--o{ subscriptions : "priced by"
    subscriptions ||--o{ subscription_items : "contains"
    subscriptions ||--o{ invoices : "bills through"
    invoices ||--o{ refunds : "refunded by"
    feature_flags ||--o{ workspace_feature_flags : "defined by"

    users {
        uuid id PK
        citext email UK
        timestamptz deleted_at
    }
    workspaces {
        uuid id PK
        citext slug UK
        uuid owner_user_id FK
        billing_state billing_state
        limit_state limit_state
        smallint usage_anchor_day
        uuid plan_id FK
    }
    workspace_members {
        uuid id PK
        uuid workspace_id FK
        uuid user_id FK
        member_role role
        member_seat_state seat_state
    }
    usage_counters {
        uuid id PK
        uuid workspace_id FK
        usage_metric metric
        usage_period period
        timestamptz period_start
        bigint value
    }
    invoices {
        uuid id PK
        uuid workspace_id FK
        text stripe_invoice_id UK
        invoice_status status
        integer total_cents
    }
    invitations {
        uuid id PK
        uuid workspace_id FK
        citext email
        invitation_status status
        char token_hash
    }
    api_keys {
        uuid id PK
        uuid workspace_id FK
        api_key_mode mode
        text scopes
    }

5.3.2 Collection, content and media #

erDiagram
    request_pages ||--o{ request_page_fields : "declares"
    request_pages ||--o{ request_page_prompts : "asks"
    request_pages ||--o{ invites : "targets via"
    request_pages ||--o{ submissions : "receives"
    request_pages ||--o{ submission_drafts : "holds drafts for"
    invite_batches ||--o{ invites : "groups"
    contacts ||--o{ invites : "addressed to"
    invites ||--o| submissions : "converts to"
    submission_drafts ||--o| submissions : "promotes to"
    submissions ||--o| upload_sessions : "uses"
    submissions ||--o{ consents : "records"
    submissions ||--o{ consent_grants : "currently grants"
    consents ||--o| consent_grants : "projects into"
    submissions ||--o| testimonials : "creates"
    imported_reviews ||--o| testimonials : "creates"
    testimonials ||--o| media_assets : "may have"
    media_assets ||--o{ media_derivatives : "renders to"
    media_assets ||--o{ transcription_jobs : "transcribed by"
    testimonials ||--o| transcripts : "may have"
    testimonials ||--o{ testimonial_tags : "labelled by"
    tags ||--o{ testimonial_tags : "labels"
    testimonials ||--o{ highlights : "features"
    testimonials ||--o{ ai_suggestions : "proposed for"
    testimonials ||--o{ social_cards : "renders to"
    testimonials ||--o{ testimonial_flags : "flagged by"
    testimonials ||--o{ testimonial_replies : "threaded with"
    testimonials ||--o| respondent_tokens : "reachable by"
    users ||--o{ inbox_saved_views : "saves"
    transcripts ||--o{ transcript_revisions : "versioned by"
    ai_suggestions ||--o{ highlights : "may originate"
    media_assets ||--o| transcripts : "transcribed as"

    testimonials {
        uuid id PK
        uuid workspace_id FK
        testimonial_status status
        testimonial_status pre_archive_status
        testimonial_status pre_delete_status
        testimonial_source source
        testimonial_kind kind
        smallint rating
        integer version
        boolean is_featured
        timestamptz published_at
        timestamptz deleted_at
    }
    testimonial_flags {
        uuid id PK
        uuid testimonial_id FK
        flag_reason reason
        timestamptz cleared_at
    }
    testimonial_replies {
        uuid id PK
        uuid testimonial_id FK
        uuid thread_id
        reply_direction direction
    }
    submission_drafts {
        uuid id PK
        uuid request_page_id FK
        char token_hash UK
        integer revision
        timestamptz expires_at
    }
    media_assets {
        uuid id PK
        media_state state
        text provider_asset_id
        text playback_id
        timestamptz purged_at
    }
    transcripts {
        uuid id PK
        content_language language
        integer version
        jsonb doc
    }
    submissions {
        uuid id PK
        submission_state state
        testimonial_kind kind
    }

5.3.3 Publishing, import, analytics and platform #

erDiagram
    workspaces ||--o{ widgets : "publishes"
    workspaces ||--o{ showcase_pages : "publishes"
    workspaces ||--o{ custom_domains : "claims"
    workspaces ||--o{ import_connections : "connects"
    workspaces ||--o{ webhook_endpoints : "registers"
    workspaces ||--o{ integration_connections : "connects"
    widgets ||--o{ widget_testimonials : "curates"
    testimonials ||--o{ widget_testimonials : "pinned into"
    custom_domains ||--o| showcase_pages : "serves"
    custom_domains ||--o| subscription_items : "billed by"
    import_connections ||--o{ import_runs : "runs"
    import_runs ||--o{ imported_reviews : "yields"
    widgets ||--o{ analytics_events_raw : "emits"
    showcase_pages ||--o{ analytics_events_raw : "emits"
    request_pages ||--o{ analytics_events_raw : "emits funnel events"
    analytics_events_raw }o--|| analytics_rollup_hourly : "aggregates into"
    analytics_rollup_hourly }o--|| analytics_rollup_daily : "aggregates into"
    outbox_events ||--o{ webhook_deliveries : "fans out to"
    webhook_endpoints ||--o{ webhook_deliveries : "receives"
    workspaces ||--o{ audit_events : "records"
    workspaces ||--o{ data_subject_requests : "processes"
    data_subject_requests ||..o{ erasure_log : "proves (no FK)"
    workspaces ||..o{ erasure_log : "records erasures (no FK)"
    testimonials ||..o| erasure_log : "erased into (no FK)"
    workspaces ||--o{ suppressions : "suppresses"
    workspaces ||--o{ notifications : "notifies"

    suppressions {
        uuid id PK
        uuid workspace_id FK
        char address_hash UK
        suppression_reason reason
    }
    erasure_log {
        uuid id PK
        uuid workspace_id
        uuid testimonial_id
        text storage_prefix
        timestamptz erasure_completed_at
        timestamptz verified_at
    }

    widgets {
        uuid id PK
        text public_id UK
        widget_type type
        jsonb config
        boolean is_active
        integer data_version
    }
    custom_domains {
        uuid id PK
        citext hostname UK
        domain_state state
        text challenge_token
        timestamptz tls_expires_at
    }
    analytics_events_raw {
        timestamptz occurred_at PK
        uuid id PK
        analytics_event_type event_type
        uuid request_page_id FK
        text view_id
    }
    audit_events {
        timestamptz occurred_at PK
        uuid id PK
        actor_type actor_type
        text action
    }

5.4 Identity and tenancy tables #

5.4.1 users #

A global principal. Not workspace-scoped, for the reason given in Section 5.1.6: a user may hold membership in more than one workspace, and v1 pins the active workspace in the UI rather than in the schema (Section 6.4).

Constraints

• UNIQUE (email) WHERE deleted_at IS NULL — partial, so a deleted account frees its address.
• CHECK (char_length(name) <= 120)
• CHECK (email <> pending_email)
• CHECK (last_failed_sign_in_at IS NULL OR failed_sign_in_count > 0)

Indexes

• users_email_active_uq — partial unique above; serves sign-in lookup.
• users_default_workspace_idx on (default_workspace_id) — session bootstrap.
• users_last_seen_idx on (last_seen_at DESC) — operator activity reporting.

CREATE TABLE users (
  id                    uuid        PRIMARY KEY,
  email                 citext      NOT NULL,
  email_verified_at     timestamptz,
  pending_email         citext,
  name                  text        NOT NULL DEFAULT '',
  avatar_object_key     text,
  locale                text        NOT NULL DEFAULT 'en',
  timezone              text        NOT NULL DEFAULT 'UTC',
  default_workspace_id  uuid,
  is_two_factor_enabled boolean     NOT NULL DEFAULT false,
  last_seen_at          timestamptz,
  failed_sign_in_count  smallint    NOT NULL DEFAULT 0,
  last_failed_sign_in_at timestamptz,
  marketing_opt_in      boolean     NOT NULL DEFAULT false,
  anonymized_at         timestamptz,
  created_at            timestamptz NOT NULL DEFAULT now(),
  updated_at            timestamptz NOT NULL DEFAULT now(),
  deleted_at            timestamptz,
  CONSTRAINT users_name_len_ck    CHECK (char_length(name) <= 120),
  CONSTRAINT users_pending_ck     CHECK (pending_email IS NULL OR pending_email <> email),
  CONSTRAINT users_lock_ck        CHECK (last_failed_sign_in_at IS NULL OR failed_sign_in_count > 0)
);

CREATE UNIQUE INDEX users_email_active_uq ON users (email) WHERE deleted_at IS NULL;
CREATE INDEX users_default_workspace_idx ON users (default_workspace_id);
CREATE INDEX users_last_seen_idx ON users (last_seen_at DESC NULLS LAST);

Lifecycle. Created by sign-up or by accepting an invitation. Soft-deleted when the person leaves the product; hard-erased only by a GDPR request, which replaces email with deleted+{id}@invalid, empties name, drops avatar_object_key (and its object), sets anonymized_at, and leaves audit_events rows intact but attributed to the tombstone id (Section 6.7.3).

5.4.2 workspaces #

The tenancy boundary. Every domain row in the system belongs to exactly one.

Constraints

• UNIQUE (slug) WHERE deleted_at IS NULL
• UNIQUE (stripe_customer_id) — a Stripe customer maps to at most one workspace.
• CHECK (char_length(name) BETWEEN 2 AND 80)
• CHECK (slug ~ '^[a-z0-9](?:[a-z0-9-]{1,46}[a-z0-9])$')
• CHECK (data_region IN ('us-east','eu-central'))
• CHECK (limit_state <> 'over_limit' OR over_limit_since IS NOT NULL)
• CHECK (usage_anchor_day BETWEEN 1 AND 28)
• CHECK (billing_state <> 'canceled' OR canceled_at IS NOT NULL)
• CHECK (billing_state <> 'trialing' OR trial_ends_at IS NOT NULL)

Indexes

• workspaces_slug_uq (partial unique) — public request-page and showcase host resolution.
• workspaces_owner_idx on (owner_user_id).
• workspaces_billing_idx on (billing_state, status_changed_at) — the dunning sweep.
• workspaces_limit_idx on (limit_state, over_limit_since) — the over-limit sweep. Two indexes rather than one composite, because the two sweeps run on different schedules and neither ever filters on the other column.
• workspaces_anchor_idx on (usage_anchor_day) — the daily quota.roll_periods job selects the workspaces whose period rolls today with a single index scan.
• workspaces_plan_idx on (plan_id) — plan-population reporting.

CREATE TABLE workspaces (
  id                      uuid             PRIMARY KEY,
  name                    text             NOT NULL,
  slug                    citext           NOT NULL,
  owner_user_id           uuid             NOT NULL REFERENCES users(id) ON DELETE RESTRICT,
  plan_id                 uuid             NOT NULL REFERENCES plans(id) ON DELETE RESTRICT,
  billing_state           billing_state    NOT NULL DEFAULT 'active',
  limit_state             limit_state      NOT NULL DEFAULT 'ok',
  status_changed_at       timestamptz      NOT NULL DEFAULT now(),
  usage_anchor_day        smallint         NOT NULL,
  over_limit_since        timestamptz,
  soft_overage_since      timestamptz,
  stripe_customer_id      text,
  trial_ends_at           timestamptz,
  canceled_at             timestamptz,
  data_region             text             NOT NULL DEFAULT 'us-east',
  is_two_factor_enforced  boolean          NOT NULL DEFAULT false,
  onboarding_completed_at timestamptz,
  created_at              timestamptz      NOT NULL DEFAULT now(),
  updated_at              timestamptz      NOT NULL DEFAULT now(),
  deleted_at              timestamptz,
  CONSTRAINT workspaces_name_len_ck  CHECK (char_length(name) BETWEEN 2 AND 80),
  CONSTRAINT workspaces_slug_fmt_ck  CHECK (slug ~ '^[a-z0-9](?:[a-z0-9-]{1,46}[a-z0-9])$'),
  CONSTRAINT workspaces_region_ck    CHECK (data_region IN ('us-east','eu-central')),
  CONSTRAINT workspaces_overlimit_ck CHECK (limit_state <> 'over_limit' OR over_limit_since IS NOT NULL),
  CONSTRAINT workspaces_anchor_ck    CHECK (usage_anchor_day BETWEEN 1 AND 28),
  CONSTRAINT workspaces_canceled_ck  CHECK (billing_state <> 'canceled' OR canceled_at IS NOT NULL),
  CONSTRAINT workspaces_trial_ck     CHECK (billing_state <> 'trialing' OR trial_ends_at IS NOT NULL),
  CONSTRAINT workspaces_stripe_uq    UNIQUE (stripe_customer_id)
);

CREATE UNIQUE INDEX workspaces_slug_uq    ON workspaces (slug) WHERE deleted_at IS NULL;
CREATE INDEX        workspaces_owner_idx  ON workspaces (owner_user_id);
CREATE INDEX        workspaces_billing_idx ON workspaces (billing_state, status_changed_at);
CREATE INDEX        workspaces_limit_idx  ON workspaces (limit_state, over_limit_since);
CREATE INDEX        workspaces_anchor_idx ON workspaces (usage_anchor_day);
CREATE INDEX        workspaces_plan_idx   ON workspaces (plan_id);

Two state columns, not one. A payment problem and a capacity problem are independent facts and are stored independently. billing_state moves only on the billing path (trial start, successful charge, failed charge, cancellation); limit_state moves only on the quota path (a counter crossing its limit, or falling back under it). A workspace can be past_due + ok, active + over_limit, or both at once, and each clears on its own. There is deliberately no combined status column and no suspended value: "suspended" would have been a third thing that is really a consequence of one of the two, and every place that wanted to ask "why is this workspace restricted?" would have had to guess. Section 19.8 owns the transition rules; Section 19.10 owns what each combination does to serving and to the dashboard.

On usage_anchor_day. Monthly usage periods do not roll at midnight UTC on the first for everyone — that would put every workspace's reconciliation into the same minute. The anchor is the workspace's creation day-of-month clamped to 28, so periods roll evenly across the month and a workspace's usage month always lines up with the day it signed up. Section 19.3 owns the period arithmetic.

Lifecycle. workspaces is the RLS anchor and is therefore not itself protected by a workspace policy — it is protected by an id = current_setting('app.current_workspace_id')::uuid policy, described in Section 6.2.3. Soft deletion schedules retention.purge_workspaces for 30 days later; that job hard-deletes every child row and destroys every external asset. Published widgets belonging to a workspace in billing_state = 'canceled' (but not deleted) keep serving forever — cancellation and deletion are different states and only deletion stops delivery.

5.4.3 workspace_members #

The many-to-many join between users and workspaces. It already models the deferred multi-workspace capability (Section 6.4); v1 simply creates one row per user.

Constraints

• UNIQUE (workspace_id, user_id) WHERE deleted_at IS NULL
• EXCLUDE is not used; the single-Owner rule is enforced by CREATE UNIQUE INDEX workspace_members_one_owner_uq ON workspace_members (workspace_id) WHERE role = 'owner' AND deleted_at IS NULL; This makes "exactly one Owner" a database invariant, not an application convention.
• CHECK (deleted_at IS NULL OR role <> 'owner') — an Owner must be demoted or transferred before removal; the last-Owner protection in Section 6.7.4 relies on this.
• CHECK (seat_state <> 'seat_suspended' OR (seat_suspended_at IS NOT NULL AND role <> 'owner')) — the Owner's seat is never suspended, because a workspace with no reachable Owner cannot be brought back under its limit.

Indexes

• workspace_members_ws_user_uq (partial unique).
• workspace_members_one_owner_uq (partial unique).
• workspace_members_user_idx on (user_id) WHERE deleted_at IS NULL — "which workspaces can this user open?", the query the deferred workspace switcher will use unchanged.
• workspace_members_ws_role_idx on (workspace_id, role) WHERE deleted_at IS NULL — seat counting for quota enforcement.
• workspace_members_suspended_idx on (workspace_id, created_at) WHERE seat_state = 'seat_suspended' AND deleted_at IS NULL — the reactivation queue. When seats free up, Section 19.12.5 reactivates oldest membership first, which is exactly this index read in order.

CREATE TABLE workspace_members (
  id                 uuid        PRIMARY KEY,
  workspace_id       uuid        NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
  user_id            uuid        NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  role               member_role       NOT NULL DEFAULT 'viewer',
  seat_state         member_seat_state NOT NULL DEFAULT 'active',
  seat_suspended_at  timestamptz,
  invited_by_user_id uuid        REFERENCES users(id) ON DELETE SET NULL,
  invitation_id      uuid,
  joined_at          timestamptz NOT NULL DEFAULT now(),
  last_active_at     timestamptz,
  created_at         timestamptz NOT NULL DEFAULT now(),
  updated_at         timestamptz NOT NULL DEFAULT now(),
  deleted_at         timestamptz,
  CONSTRAINT workspace_members_owner_removal_ck CHECK (deleted_at IS NULL OR role <> 'owner'),
  CONSTRAINT workspace_members_seat_ck CHECK (
    seat_state <> 'seat_suspended' OR (seat_suspended_at IS NOT NULL AND role <> 'owner'))
);

CREATE UNIQUE INDEX workspace_members_ws_user_uq
  ON workspace_members (workspace_id, user_id) WHERE deleted_at IS NULL;
CREATE UNIQUE INDEX workspace_members_one_owner_uq
  ON workspace_members (workspace_id) WHERE role = 'owner' AND deleted_at IS NULL;
CREATE INDEX workspace_members_user_idx
  ON workspace_members (user_id) WHERE deleted_at IS NULL;
CREATE INDEX workspace_members_ws_role_idx
  ON workspace_members (workspace_id, role) WHERE deleted_at IS NULL;
CREATE INDEX workspace_members_suspended_idx
  ON workspace_members (workspace_id, created_at)
  WHERE seat_state = 'seat_suspended' AND deleted_at IS NULL;

seat_state is where seat suspension lives. It is a column on the membership, not a role change and not a deletion, because the member's role must survive the suspension unchanged so that reactivation restores exactly what they had. Suspension changes the actor's effective permissions without changing role, so every session belonging to a member entering or leaving seat_suspended is revoked at the moment of the change (Section 7.7.1) — otherwise a suspended member would keep acting for up to the life of their session.

5.4.4 invitations #

A pending offer of membership. Distinct from invites, which are testimonial requests sent to respondents — the two are never conflated and their names are deliberately kept apart.

Constraints

• UNIQUE (workspace_id, email) WHERE status = 'pending' — one open invitation per address.
• UNIQUE (token_hash)
• CHECK (role <> 'owner') — ownership is transferred, never invited.
• CHECK (status <> 'accepted' OR (accepted_at IS NOT NULL AND accepted_user_id IS NOT NULL))
• CHECK (resend_count <= 5)

Indexes

• invitations_token_uq on (token_hash) — acceptance lookup.
• invitations_ws_status_idx on (workspace_id, status, created_at DESC) — members screen.
• invitations_expiry_idx on (expires_at) WHERE status = 'pending' — the expiry sweeper.

Lifecycle. An invitation row is never deleted on acceptance. Every terminal invitation — accepted, revoked, or expired alike — is retained 90 days from status_changed_at and then hard-deleted by invitation.expire, which does both jobs: it moves overdue pending rows to expired and removes terminal rows past their retention. Keeping the accepted row is what makes three things work: the members screen can show who invited whom and when (Section 6.8), clicking a used link returns INVITATION_ALREADY_USED rather than a bare 404, and the accepted enum value is actually observable rather than a state no row is ever seen in. Acceptance writes workspace_members and an audit_events row in the same transaction.

5.4.5 sessions #

better-auth's session store, extended with the active-workspace pin. Not workspace-scoped (Section 5.1.6).

Constraints: UNIQUE (token_hash); CHECK (absolute_expires_at >= expires_at). Indexes: sessions_token_uq; sessions_user_idx (user_id, created_at DESC) for the "active sessions" screen; sessions_expiry_idx (expires_at) WHERE revoked_at IS NULL for the sweeper. Hard-deleted 7 days after absolute_expires_at by session.sweep.

5.4.6 accounts #

better-auth's credential/provider rows. In v1 the only provider is credential; the table shape accommodates OAuth providers without migration.

Constraints: UNIQUE (provider_id, provider_account_id); CHECK (provider_id <> 'credential' OR password_hash IS NOT NULL). Indexes: accounts_user_idx (user_id). Hard-deleted with the user (ON DELETE CASCADE).

5.4.7 verification_tokens #

Single-use tokens for email verification, magic-link sign-in, password reset, email change, and two-factor recovery. One table for all five, discriminated by purpose, because they share identical hashing, expiry, and consumption semantics.

Constraints: UNIQUE (token_hash); UNIQUE (identifier, purpose) WHERE consumed_at IS NULL — requesting a new token invalidates the previous one for the same purpose, which is what makes "click the newest link" always correct. Indexes: verification_tokens_expiry_idx (expires_at) WHERE consumed_at IS NULL. Hard-deleted 24 hours after expires_at by session.sweep, which sweeps both token stores.

5.4.8 two_factor_secrets #

One optional row per user. Separated from users so the secret can be read only by the auth service and so column-level grants can restrict it.

Constraints: UNIQUE (user_id); CHECK (array_length(recovery_code_hashes,1) IS NULL OR array_length(recovery_code_hashes,1) <= 10); CHECK (recovery_codes_remaining BETWEEN 0 AND 10).

5.4.9 api_keys #

Public REST API credentials. Keys belong to a workspace, never to a user, so revoking a person does not silently break an integration.

Constraints

• UNIQUE (key_hash)
• CHECK (scopes <@ ARRAY['testimonials:read','testimonials:write','widgets:read','widgets:write','analytics:read','webhooks:manage']::text[]) — an unknown scope cannot be stored, so scope drift is impossible.
• CHECK (array_length(scopes,1) >= 1)
• CHECK (key_prefix = left(key_prefix, 12))

Indexes: api_keys_hash_uq (key_hash) — the authentication lookup, a single index probe; api_keys_ws_idx (workspace_id, created_at DESC) WHERE revoked_at IS NULL.

CREATE TABLE api_keys (
  id                    uuid         PRIMARY KEY,
  workspace_id          uuid         NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
  name                  text         NOT NULL,
  mode                  api_key_mode NOT NULL DEFAULT 'live',
  key_prefix            char(12)     NOT NULL,
  key_hash              char(64)     NOT NULL,
  scopes                text[]       NOT NULL DEFAULT '{}',
  created_by_user_id    uuid         REFERENCES users(id) ON DELETE SET NULL,
  last_used_at          timestamptz,
  last_used_ip          inet,
  request_count         bigint       NOT NULL DEFAULT 0,
  expires_at            timestamptz,
  revoked_at            timestamptz,
  revoked_by_user_id    uuid         REFERENCES users(id) ON DELETE SET NULL,
  rate_limit_per_minute integer,
  created_at            timestamptz  NOT NULL DEFAULT now(),
  updated_at            timestamptz  NOT NULL DEFAULT now(),
  CONSTRAINT api_keys_hash_uq   UNIQUE (key_hash),
  CONSTRAINT api_keys_name_ck   CHECK (char_length(name) BETWEEN 1 AND 80),
  CONSTRAINT api_keys_scopes_ck CHECK (
    array_length(scopes, 1) >= 1 AND scopes <@ ARRAY[
      'testimonials:read','testimonials:write','widgets:read',
      'widgets:write','analytics:read','webhooks:manage']::text[]),
  CONSTRAINT api_keys_rate_ck   CHECK (rate_limit_per_minute IS NULL OR rate_limit_per_minute > 0)
);

CREATE INDEX api_keys_ws_idx ON api_keys (workspace_id, created_at DESC) WHERE revoked_at IS NULL;

Lifecycle. Never soft-deleted in the deleted_at sense; revocation is revoked_at, and revoked rows are retained forever so historical audit_events referencing the key still resolve to a name.

5.4.10 feature_flags and workspace_feature_flags #

Two tables: a platform-owned definition table and a per-workspace override table. Flags are evaluated server-side only; no flag value is ever sent to the widget bundle.

feature_flags (platform, no workspace_id):

workspace_feature_flags (workspace-scoped override):

Constraints: feature_flags: UNIQUE (key), CHECK (key ~ '^flag_[a-z0-9_]{3,60}$'), CHECK (rollout_percent BETWEEN 0 AND 100). workspace_feature_flags: UNIQUE (workspace_id, feature_flag_id).

Evaluation order, implemented in packages/core/flags/evaluate.ts: non-expired workspace override → rollout bucket (hashint('{key}:{workspaceId}') % 100 < rollout_percent) → is_enabled_default. The result is cached in Valkey for 30 seconds and invalidated on write.

5.4.11 workspace_settings #

Exactly one row per workspace, created in the same transaction as the workspace. The primary key is workspace_id; there is no separate id, because a second row must be impossible.

Constraints: every colour column CHECK (value ~ '^#[0-9a-f]{6}$'); CHECK (font_scale BETWEEN 0.85 AND 1.30); CHECK (border_radius_px BETWEEN 0 AND 32); CHECK (notify_digest_frequency IN ('off','daily','weekly')); CHECK (week_start IN (0,1)).

CREATE TABLE workspace_settings (
  workspace_id                uuid              PRIMARY KEY REFERENCES workspaces(id) ON DELETE CASCADE,
  logo_object_key             text,
  wordmark_object_key         text,
  brand_primary_color         char(7)           NOT NULL DEFAULT '#111827',
  brand_accent_color          char(7)           NOT NULL DEFAULT '#2563eb',
  brand_text_color            char(7)           NOT NULL DEFAULT '#111827',
  brand_background_color      char(7)           NOT NULL DEFAULT '#ffffff',
  font_scale                  numeric(3,2)      NOT NULL DEFAULT 1.00,
  border_radius_px            smallint          NOT NULL DEFAULT 12,
  default_language            content_language  NOT NULL DEFAULT 'en',
  reply_to_email              citext,
  reply_to_verified_at        timestamptz,
  from_name                   text              NOT NULL DEFAULT '',
  default_consent_version_id  uuid              NOT NULL REFERENCES consent_versions(id) ON DELETE RESTRICT,
  is_badge_hidden             boolean           NOT NULL DEFAULT false,
  keep_originals              boolean           NOT NULL DEFAULT false,
  auto_transcribe             boolean           NOT NULL DEFAULT true,
  ai_assistant_enabled        boolean           NOT NULL DEFAULT false,
  notify_on_submission        boolean           NOT NULL DEFAULT true,
  notify_on_import_complete   boolean           NOT NULL DEFAULT true,
  notify_digest_frequency     text              NOT NULL DEFAULT 'weekly',
  reporting_timezone          text              NOT NULL DEFAULT 'UTC',
  week_start                  smallint          NOT NULL DEFAULT 1,
  showcase_default_theme_mode widget_theme_mode NOT NULL DEFAULT 'auto',
  created_at                  timestamptz       NOT NULL DEFAULT now(),
  updated_at                  timestamptz       NOT NULL DEFAULT now(),
  CONSTRAINT ws_settings_primary_ck  CHECK (brand_primary_color    ~ '^#[0-9a-f]{6}$'),
  CONSTRAINT ws_settings_accent_ck   CHECK (brand_accent_color     ~ '^#[0-9a-f]{6}$'),
  CONSTRAINT ws_settings_text_ck     CHECK (brand_text_color       ~ '^#[0-9a-f]{6}$'),
  CONSTRAINT ws_settings_bg_ck       CHECK (brand_background_color ~ '^#[0-9a-f]{6}$'),
  CONSTRAINT ws_settings_scale_ck    CHECK (font_scale BETWEEN 0.85 AND 1.30),
  CONSTRAINT ws_settings_radius_ck   CHECK (border_radius_px BETWEEN 0 AND 32),
  CONSTRAINT ws_settings_digest_ck   CHECK (notify_digest_frequency IN ('off','daily','weekly')),
  CONSTRAINT ws_settings_weekstart_ck CHECK (week_start IN (0,1))
);

5.4.12 plans #

Operator-owned pricing catalogue. A lookup table rather than an enum because prices, limits, and plan names change without a code deploy. Section 19 owns the commercial meaning of every value; this table is where the numbers live.

limits shape, validated by planLimitsSchema in packages/validation:

{
  "testimonialsLifetime": 500,
  "seats": 10,
  "requestPages": 25,
  "maxVideoSeconds": 300,
  "maxVideoHeight": 1080,
  "storageBytes": 107374182400,
  "deliveryMinutesPerMonth": 50000,
  "transcriptionMinutesPerMonth": 1500,
  "includedCustomDomains": 1,
  "extraDomainPriceCents": 1000,
  "apiRequestsPerMinute": 120,
  "analyticsRetentionDays": 730,
  "maxApiKeys": 25,
  "maxWebhookEndpoints": 20,
  "maxContacts": 50000,
  "maxTags": 200
}

null in any numeric limit means unlimited (used for requestPages on Scale). Widgets and widget views have no limit key at all, on any plan, because they are unlimited by product design and an absent key cannot be accidentally enforced.

Two of these keys are not metered counters and the distinction matters. apiRequestsPerMinute configures the Valkey token bucket in Section 7.10; it is a rate, refilled continuously, and it never appears in usage_counters or in the usage_metric enum, because there is no period over which it accumulates and nothing to reconcile. The same is true of maxApiKeys, maxWebhookEndpoints, maxContacts, and maxTags: each is a ceiling checked with a count(*) at creation time, refused with the relevant *_LIMIT_REACHED code from Section 29.3, and never metered. Only the seven usage_metric values are counters. Section 19.2 states the per-plan values of every key here; this table is where they live at runtime.

Constraints: UNIQUE (code); UNIQUE (position); CHECK (price_cents_monthly >= 0 AND price_cents_annual >= 0); CHECK (code = 'free' OR stripe_price_id_monthly IS NOT NULL).

5.5 Collection tables #

5.5.1 request_pages #

A public page at https://v.vouch.app/r/{slug} (or https://{customDomain}/r/{slug}) that asks a respondent for a testimonial. Section 8 owns the behaviour; this is the storage.

Constraints

• UNIQUE (workspace_id, slug) WHERE deleted_at IS NULL
• CHECK (allow_video OR allow_text) — a page that collects nothing cannot exist.
• CHECK (max_text_chars BETWEEN 100 AND 5000 AND min_text_chars BETWEEN 0 AND max_text_chars)
• CHECK (max_video_seconds IS NULL OR max_video_seconds BETWEEN 15 AND 300)
• CHECK (min_video_seconds BETWEEN 1 AND 60)
• CHECK (redirect_url IS NULL OR redirect_url ~ '^https://')
• CHECK (array_length(notify_emails,1) IS NULL OR array_length(notify_emails,1) <= 10)
• CHECK (NOT allow_audio_only OR allow_video)

Indexes

• request_pages_ws_slug_uq (partial unique) — public page resolution, one probe.
• request_pages_ws_active_idx on (workspace_id, is_active, created_at DESC) WHERE deleted_at IS NULL — the list screen.
• request_pages_consent_idx on (consent_version_id) — impact analysis when consent text changes.

CREATE TABLE request_pages (
  id                      uuid             PRIMARY KEY,
  workspace_id            uuid             NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
  slug                    citext           NOT NULL,
  name                    text             NOT NULL,
  headline                text             NOT NULL,
  intro_body              text             NOT NULL DEFAULT '',
  logo_object_key         text,
  background_object_key   text,
  theme                   jsonb            NOT NULL DEFAULT '{}'::jsonb,
  allow_video             boolean          NOT NULL DEFAULT true,
  allow_text              boolean          NOT NULL DEFAULT true,
  allow_audio_only        boolean          NOT NULL DEFAULT false,
  require_rating          boolean          NOT NULL DEFAULT false,
  require_email           boolean          NOT NULL DEFAULT true,
  require_name            boolean          NOT NULL DEFAULT true,
  collect_role            boolean          NOT NULL DEFAULT true,
  collect_company         boolean          NOT NULL DEFAULT true,
  collect_avatar          boolean          NOT NULL DEFAULT true,
  collect_company_logo    boolean          NOT NULL DEFAULT false,
  max_video_seconds       smallint,
  min_video_seconds       smallint         NOT NULL DEFAULT 5,
  max_text_chars          integer          NOT NULL DEFAULT 2000,
  min_text_chars          integer          NOT NULL DEFAULT 40,
  teleprompter_default_on boolean          NOT NULL DEFAULT false,
  consent_version_id      uuid             NOT NULL REFERENCES consent_versions(id) ON DELETE RESTRICT,
  thank_you_headline      text             NOT NULL DEFAULT 'Thank you!',
  thank_you_body          text             NOT NULL DEFAULT '',
  redirect_url            text,
  auto_approve            boolean          NOT NULL DEFAULT false,
  notify_emails           citext[]         NOT NULL DEFAULT '{}',
  is_active               boolean          NOT NULL DEFAULT true,
  locale                  content_language NOT NULL DEFAULT 'en',
  submission_count        integer          NOT NULL DEFAULT 0,
  view_count              integer          NOT NULL DEFAULT 0,
  published_at            timestamptz,
  created_by_user_id      uuid             REFERENCES users(id) ON DELETE SET NULL,
  created_at              timestamptz      NOT NULL DEFAULT now(),
  updated_at              timestamptz      NOT NULL DEFAULT now(),
  deleted_at              timestamptz,
  CONSTRAINT request_pages_kind_ck     CHECK (allow_video OR allow_text),
  CONSTRAINT request_pages_audio_ck    CHECK (NOT allow_audio_only OR allow_video),
  CONSTRAINT request_pages_text_len_ck CHECK (max_text_chars BETWEEN 100 AND 5000
                                          AND min_text_chars BETWEEN 0 AND max_text_chars),
  CONSTRAINT request_pages_vid_max_ck  CHECK (max_video_seconds IS NULL OR max_video_seconds BETWEEN 15 AND 300),
  CONSTRAINT request_pages_vid_min_ck  CHECK (min_video_seconds BETWEEN 1 AND 60),
  CONSTRAINT request_pages_redirect_ck CHECK (redirect_url IS NULL OR redirect_url ~ '^https://'),
  CONSTRAINT request_pages_notify_ck   CHECK (coalesce(array_length(notify_emails,1),0) <= 10),
  CONSTRAINT request_pages_slug_fmt_ck CHECK (slug ~ '^[a-z0-9](?:[a-z0-9-]{1,46}[a-z0-9])$')
);

CREATE UNIQUE INDEX request_pages_ws_slug_uq
  ON request_pages (workspace_id, slug) WHERE deleted_at IS NULL;
CREATE INDEX request_pages_ws_active_idx
  ON request_pages (workspace_id, is_active, created_at DESC) WHERE deleted_at IS NULL;
CREATE INDEX request_pages_consent_idx ON request_pages (consent_version_id);