All-in-One Privacy-First PDF Toolkit

PDFWorks — Product Requirements & Build Specification #

An all-in-one, privacy-first PDF toolkit: browser-native editing, server-side OCR and Office conversion, ESIGN/eIDAS-compliant e-signature, and a first-class public REST API.

Version 1.0 · Status: Final · Audience: the engineering team or AI coding agent that will build this product from an empty repository.

Overview #

PDF work today is scattered across iLovePDF, Smallpdf, and Sejda. Users juggle three sites, hit a paywall halfway through a task, and upload contracts, medical records, and financial statements to servers they have never evaluated. Teams need signing, forms, and redaction sitting next to the basic edits. Developers need an API. No single product combines the full editing surface with genuine privacy and a real developer platform.

PDFWorks does. Its central architectural commitment is that most tools never upload your file. Merging, splitting, compressing, watermarking, Bates numbering, encrypting, editing, annotating, form-filling, and — critically — redaction all run inside the browser on a WebAssembly engine. The bytes stay on the device. Only the four things that genuinely cannot run locally go to a server: OCR, Office and HTML conversion, signature requests sent to other people, and anything invoked through the public API, which has no browser to run in. Those uploads are encrypted with a per-job key, processed in a network-isolated sandbox, and destroyed within 24 hours. Every tool tells the user which mode it is in before they act, and that indicator is enforced by a build-time check rather than by good intentions.

The same WebAssembly artifact runs in the browser and on the server, so an operation performed in a tab and the same operation performed through the REST API produce byte-identical output. There is one engine, not two.

This document specifies that product completely: 23 sections covering the data model, the processing engine, every tool, the e-signature system and its tamper-evident audit trail, accounts and teams, billing and quotas, the public API and webhooks, the frontend and design system, security and privacy, testing, infrastructure, the marketing site, and a milestone-by-milestone build plan. It is written to be executed cold, without clarifying questions. Every concern has exactly one owning section; every other section references it by number.

How to read this: Section 1 lists the decisions you may want to change before you start, each with a working default so you can begin immediately. Section 22 is the build order. Section 23.6 is the direct instruction set for the executing agent. Everything between is the specification.

Table of Contents #

1. Before You Start: Customization Decisions
2. Product Overview, Vision & Success Metrics
3. Technology Stack & System Architecture
4. Conventions & Engineering Standards
5. Data Model & Database Schema
6. The Processing Engine: Client-Side and Server-Side
7. Tool Specifications A: Page Operations, Compression, Image Conversion
8. Tool Specifications B: Editing, Annotation, Forms
9. Tool Specifications C: Redaction, Watermarks & Numbering, Document Security, OCR, Office & HTML Conversion
10. E-Signature System
11. Accounts, Guest Access, Teams & Workspaces
12. Plans, Billing, Quotas & Entitlements
13. Batch Processing & Job Orchestration
14. Public REST API & Webhooks
15. Frontend Application Architecture
16. Design System, Accessibility & Internationalization
17. Security, Privacy & Compliance
18. Observability, Performance & Reliability
19. Testing & Quality Assurance
20. Infrastructure, Deployment & Operations
21. Marketing Site, SEO Strategy & Product Copy
22. Milestones & Execution Plan
23. Appendices

1. Before You Start: Customization Decisions #

This section exists so the executor can start building immediately without asking anyone anything. Every value in this document that a real deployment would need to change is listed below with a working default, the reasoning behind that default, and the exact place to change it. If the executor changes nothing in this section, the product builds, runs, and is fully functional under placeholder identity. Nothing downstream in this document depends on any of these values being correct on day one; they are all overridable through configuration, not hard-coded into logic.

1.1 Customization Decisions Table #

1.2 How to Use This Document #

Reading order. This document is written to be built from, not read front-to-back like a novel, but it has a natural build order for an executor working alone: Sections 1–4 (this section plus product framing, architecture, and conventions) first, because every later section assumes them. Then Section 5 (data model), because every feature section references its tables. Then Sections 6–10 (the processing engine and the tool catalogue) in numeric order, since later tools sometimes build on primitives introduced by earlier ones (for example, watermarking and Bates numbering in Section 9.2 reuse the page-content-stream utilities introduced for page operations in Section 7). Sections 11–14 (accounts, billing, batch orchestration, the public API) can be built in parallel once Section 5 and Section 6 exist, because they depend on the data model and the job state machine but not on each other's internals. Sections 15–19 (frontend architecture, design system, security, observability, testing) are cross-cutting and are best implemented incrementally alongside the feature sections rather than as a discrete final pass. Sections 20–23 (infrastructure, marketing site, milestones, appendices) close out the build.

How cross-references work. Every concern in this document has exactly one owning section, stated the first time the concern appears and never redefined afterward. A reference like "per the error envelope in Section 14.6" or "using the job state machine in Section 4.7" means: the full, binding definition lives at that section number, and every other mention is required to match it exactly. If an example elsewhere in this document appears to conflict with the owning section, the owning section is correct and the example has a defect — there is no case where two sections intentionally disagree.

What is canonical where. The following concerns are defined exactly once, each in the section named, and are only ever referenced by number elsewhere: the error envelope (14.6), the job state machine (4.7), the pagination and cursor model (14.7), the plans/limits/entitlements table (12.2), the dependency version table (3.2), the canonical conventions table (4.3), the redaction algorithm (9.1), the e-signature audit and hash-chain mechanism (10.4), the retention and deletion rules (6), the security baseline (17), the accessibility bar (16), and the performance budgets (18.6). Restating any of these elsewhere in this document, or in code built from it, is a defect: fix the duplicate, do not maintain two copies.

The one-owning-section rule. When building a feature that touches several of these concerns — for example, a batch job that returns errors, transitions through job states, and is paginated in its list endpoint — the implementation pulls from all three owning sections but the documentation for that feature only needs to say which states, which error codes, and which pagination parameters apply; it does not need to re-explain what a cursor is or what the processing_error type means. This keeps the document's size proportional to genuinely new information rather than to repetition, and it is the same discipline the executor should carry into their own code comments and internal documentation once building begins.

2. Product Overview, Vision & Success Metrics #

2.1 Vision Statement #

PDFWorks is the PDF toolkit people reach for because it does not ask them to trust it. Most PDF work is small, repetitive, and involves documents the user has no business uploading to a stranger's server — a signed lease, a scanned passport, a client contract with a redlined clause. PDFWorks performs the large majority of its operations entirely inside the user's browser, using a WebAssembly build of production-grade PDF engines, so the file is read, edited, and re-saved without ever leaving the device. When an operation genuinely requires a server — because it needs a format converter too heavy to ship to a browser, or because it needs to coordinate multiple people signing a document — PDFWorks says so, plainly, before the user commits to it, and treats the uploaded bytes as a liability to be destroyed on a strict clock rather than an asset to retain. The product's competitive wedge is not a longer feature list than iLovePDF or Smallpdf; it is that every screen tells the user, honestly and before they act, whether their file is about to leave their device — and for most of the tool catalogue, the honest answer is no.

2.2 Target User Groups #

2.2.1 Individual Professional — "Dana, the contract-adjacent freelancer" #

• Who: A freelance consultant, paralegal, real-estate agent, or similar professional who touches PDFs daily but has no engineering background and no dedicated document-management budget.
• Jobs-to-be-done: Redact a client's Social Security number before forwarding a document; merge three inspection reports into one PDF to email a buyer; fill and sign a W-9 without printing it; compress a scanned lease under an email attachment limit; convert a signed PDF back to a Word document because a counterparty insists on tracked changes.
• Current workarounds: A rotating set of free tools (iLovePDF, Smallpdf, Sejda) hit one at a time as each one's free-tier cap or feature gate is reached; a desktop print-to-PDF driver for anything Acrobat-shaped; occasionally a screenshot pasted into Word because the "real" tool wanted a subscription for a five-second task.
• What would make Dana switch and stay: No account required for the handful of tools she uses weekly (merge, split, compress, rotate — see Section 2.6's guest tool list); a redaction tool she can trust because it explains, not just claims, that the text is gone (Section 9.1); a free tier generous enough that she never has to think about it for basic tasks, with a Pro upgrade path that is obviously worth $9/month the first time she needs OCR or a batch job.

2.2.2 Small Team — "The five-person closing coordination team at a boutique title company" #

• Who: A team of three to fifteen people who collaborate on documents that need multiple external signatures — closing packages, engagement letters, vendor agreements — and who currently pay for a named e-signature product plus a separate PDF editor.
• Jobs-to-be-done: Send a three-signer envelope (buyer, seller, agent) with a defined signing order and get a legally defensible audit trail; keep a shared template library so new hires don't rebuild the same envelope from scratch; see every teammate's job history and signature envelopes in one shared workspace; enforce MFA on the whole team after a phishing scare.
• Current workarounds: A separate e-signature subscription (DocuSign, Dropbox Sign) alongside a separate PDF editor subscription, with no shared audit log between the two and no cost benefit from bundling; manually re-uploading the same template every time; tracking envelope status in a shared spreadsheet because the e-signature tool's dashboard is not shared across the team's seats without a higher-tier plan.
• What would make the team switch and stay: One $15/user/month plan that replaces both subscriptions (Section 12.2); a shared workspace with shared templates and a shared audit log (Section 11.6); an admin who can enforce MFA workspace-wide (Section 17.3); confidence that the audit trail (Section 10.4) will hold up if a signature is ever challenged.

2.2.3 Developer — "The engineer at a proptech startup automating document intake" #

• Who: A backend or full-stack engineer building a product that needs to generate, convert, OCR, or collect signatures on PDFs as part of a larger workflow — lease generation, invoice OCR, contract intake — and does not want to operate PDFium, LibreOffice, and an OCR pipeline themselves.
• Jobs-to-be-done: Convert a generated HTML invoice to PDF from a backend job; OCR a batch of scanned intake documents and get structured text back; kick off a three-party signature envelope from an application event and get a webhook when it completes; keep API costs predictable and visible per environment.
• Current workarounds: Self-hosting an open-source stack (Stirling PDF plus a hand-rolled OCR pipeline) and absorbing the operational burden; or paying for a developer-unfriendly consumer tool's undocumented internal API by scraping it, which breaks without notice.
• What would make the developer switch and stay: A documented, versioned REST API (Section 14) with a published OpenAPI document and an official TypeScript SDK; predictable metered pricing with a configurable spend cap (Section 12.6); webhooks with a real signature scheme (Section 17.4) instead of "poll until it's done"; idempotency keys so a retried request never double-charges or double-sends an envelope (Section 14.8).

2.3 Competitive Analysis #

2.4 Differentiation Thesis #

The defensible differentiator is not any single tool — merge, split, and compress are commodity operations that every competitor in Section 2.3 already offers adequately. The defensible differentiator is the combination of (a) running the large majority of the catalogue client-side by architectural default rather than as a marketing claim, (b) disclosing execution location before the user acts through the Processing Location Indicator (Section 2.5), and (c) unifying that privacy-first document tooling with a genuinely competitive e-signature product under one audit log and one price. Points (a) and (b) are hard to copy because they are not a feature toggle — they require the underlying architecture described in Section 3 (a WASM-compiled engine that produces byte-identical output to its server counterpart, cross-origin isolation, OPFS-based local staging) and a UI discipline that surfaces execution location on every relevant screen without exception, which is enforced in this document as a CI-blocking contract (Section 2.5). Point (c) is hard to copy because it requires an operator willing to build and maintain both a document-editing engine and an e-signature audit/legal-consent system to the same quality bar, which is why the market has, to date, kept them as separate products. A competitor could copy any one of these three; copying all three without years of runway is unlikely.

2.5 The Processing Location Indicator #

Every tool page, every tool card in the tool grid, every batch job row, and every confirmation dialog shows a Processing Location Indicator before the user commits to an action:

This indicator is not decorative copy — it is a contractual statement about system behavior. The binding version of this contract — the full state table, glyph, token color, and copy shown above, plus the rule for when each state applies — is defined once, canonically, in Section 6.2, and is shown here because it is the product's central proof point (Section 2.4), not because this section owns it. Its visual specification lives in Section 16.4. Every end-to-end test suite that exercises a tool asserts the indicator shown matches the tool's actual execution location from the table in Section 2.6, and a pull request that changes a tool's execution location without updating its indicator fails the required check described in Section 4.11. There is no tool in this product for which the indicator is allowed to be wrong, approximate, or absent.

2.6 Complete Tool Inventory #

The Tool column above gives each tool's display name, not a URL or API identifier — every tool has two deliberately distinct identifier namespaces built from that same name. The API operation slug is a short form (for example merge), used as the tool value in public REST API job creation calls and defined canonically in Section 14.5. The web route slug is a longer, SEO-oriented, suffixed form (for example merge-pdf), used in the tool page's URL and defined canonically in Section 15.1. These two namespaces are not an inconsistency to reconcile — a route slug exists to read well in a browser address bar and a search result, while an operation slug exists to be short and stable in code — and the table in Section 15.1 is the single place both forms are mapped to each other and to the tool names above.

Any operation invoked through the public REST API runs server-side regardless of which row above it corresponds to, because the API has no browser to run WASM in (Section 14.1). Any batch job that contains at least one server-side tool runs entirely server-side (Section 13.2).

2.7 End-to-End User Journeys #

2.7.1 Guest merges two files and hits the daily cap #

1. A visitor with no account lands on the marketing site and clicks "Merge PDF."
2. The tool page loads with the Processing Location Indicator showing "On your device."
3. The visitor drops two PDF files (18 MB total) onto the drop zone; the worker pool (Section 3.7) begins loading the WASM engine in the background while the drop zone remains interactive.
4. The visitor reorders the two files by dragging thumbnails, then clicks "Merge."
5. The merge runs entirely in-browser and completes in under a second; the visitor downloads the result directly from OPFS with no upload having occurred.
6. The visitor repeats this four more times across the session (splitting a file, compressing another, rotating a third, merging again), consuming the guest daily cap of five tasks per device (Section 12.2, footnote 1).
7. On the sixth attempt the tool page shows a non-blocking banner: "You've used today's 5 free tasks on this device. Create a free account for unlimited client-side tools." The merge button is disabled until either the visitor creates an account or the daily cap resets at midnight UTC.
8. The visitor creates a free account in two fields (email, password) and is returned to the same tool page with the task immediately available again — no re-upload, since nothing was ever uploaded.

2.7.2 Freelancer redacts a contract #

1. Dana (Section 2.2.1) signs in to her free account and opens the Redact tool.
2. She uploads a 12-page vendor contract; the Processing Location Indicator confirms "On your device."
3. She marks three regions across two pages: a bank account number, a home address, and a signature block she wants replaced later.
4. She clicks "Apply redaction." The tool runs the nine-step redaction algorithm defined in Section 9.1 entirely client-side and produces a Redaction Verification Report showing three glyph runs removed, zero images affected, and a PASS verdict.
5. She downloads both the redacted PDF and the verification report, and forwards the redacted file to her client with the report attached as proof the removal was verified, not just visually applied.

2.7.3 Small team sends a three-signer envelope #

1. A workspace owner at the title company (Section 2.2.2) opens the Team workspace's shared template library and selects "Residential Closing — 3 Signer" template, previously built by a colleague.
2. She uploads the finalized closing PDF, which the template maps onto: buyer signs first, then seller, then the agent countersigns, per the sequential routing rule in Section 10.5.
3. She reviews the pre-placed fields from the template (signature, date-signed, initials on each page), adjusts one field position, and clicks "Send." This is a server-side operation (Section 2.6): the document uploads, encrypted at rest with a per-job data key (Section 3.9).
4. Each signer receives an email at their turn in the sequence; the buyer opens the link, verifies their email with a 6-digit code, accepts the Electronic Record and Signature Disclosure, completes their fields, and signs by drawing a signature. The audit trail records signer.viewed, signer.consented, field.completed, and signer.signed events with hash-chained document snapshots (Section 10.4).
5. After all three sign, the envelope reaches envelope.completed; a Certificate of Completion page is appended, the document is flattened, and all three signers plus the sender receive the completed, flattened PDF by email.
6. The completed PDF and certificate remain downloadable from the shared workspace's audit log for 30 days (Section 6); the audit trail itself is retained for 7 years.

2.7.4 Developer integrates the API #

1. An engineer at the proptech startup (Section 2.2.3) creates an API-plan workspace and generates a live API key with a documents:write and jobs:read scope (Section 17.4).
2. She reads the published OpenAPI document at https://docs.pdfworks.io/openapi.json and installs the official TypeScript SDK.
3. From a backend job, she calls the SDK's documents.upload() with a generated HTML invoice, followed by jobs.create({ tool: "html-to-pdf", documentId }), passing an Idempotency-Key header so a network retry cannot create a duplicate job (Section 14.8).
4. She registers a webhook endpoint; when the job reaches succeeded, PDFWorks POSTs a job.succeeded event signed with HMAC-SHA256 (Section 17.4), and her endpoint verifies the signature before downloading the resulting PDF via a short-lived signed URL.
5. Over the following weeks, usage crosses the Starter plan's 2,000-operation monthly inclusion; the dashboard's usage graph and a proactive email at 80% utilization warn her before overage billing begins at $0.012/operation (Section 12.6).

2.7.5 Power user batch-Bates-numbers 180 exhibits #

1. A litigation paralegal on a Pro plan opens the Batch tool and selects "Bates Numbering" as the batch operation.
2. She uploads 180 individual PDF exhibits (well under the Pro plan's 100-files-per-job cap being exceeded — she instead runs it in two batches of 90, per the plan limits in Section 12.2), sets the Bates prefix to SMITH- starting at 000001, and confirms placement in the bottom-right corner.
3. Because Bates numbering is a client-side tool (Section 2.6) and the batch contains no server-side tool, the entire batch — Section 13.2's routing rule — runs in the browser, processed by the worker pool with a concurrency of clamp(navigator.hardwareConcurrency - 1, 2, 4) (Section 3.7), showing a per-file progress row using the job state machine's states (Section 4.7).
4. When all 90 files reach succeeded, she downloads the batch as a single zip archive, sequentially numbered SMITH-000001.pdf through SMITH-000090.pdf.
5. She repeats the process for the remaining 90 exhibits, continuing the Bates sequence from 000091, which the batch tool supports via a "starting number" field that defaults to one past the previous batch's last-used number when run in the same session.

2.8 Non-Goals #

• Native iOS/Android/desktop applications. A PWA covers the installable-app use case (Section 15.7) without the maintenance cost of separate native codebases; a future version could revisit native apps if offline-first mobile usage proves to be a significant share of demand.
• In-person identity verification or knowledge-based authentication for signers. The e-signature product targets ESIGN/UETA/eIDAS simple and advanced signatures (Section 10.1), not identity-proofed qualified signatures; a future version aimed at regulated industries (real estate closings requiring notarization, for example) would need to add this as a distinct, higher-assurance signing tier.
• Languages other than English at launch. The internationalization architecture is built in from day one (Section 16.6) so that adding a locale is a translation-file exercise, not a re-architecture, but translating the UI itself is out of scope for the initial launch.
• A white-label or reseller portal. Every customer uses the product under the operator's own brand; reselling under a partner's brand would require multi-tenant theming and billing changes not designed here.
• PDF/A archival compliance certification. The product produces valid, well-formed PDFs but does not claim or verify PDF/A conformance; an archival-compliance customer segment would need a dedicated conformance-checking and remediation tool.
• PKI-based digital certificate signatures. Explicitly out of scope for the e-signature product; see Section 10.1 for the full rationale and the exact mechanism used instead.
• Enterprise SSO/SAML/SCIM. Team workspaces use PDFWorks accounts with optional MFA (Section 17.3); large-enterprise identity federation is a natural addition once a Team-tier customer requests it contractually, but is not built speculatively.
• Built-in Google Drive/Dropbox/OneDrive pickers. Users work with files from their local filesystem or drag-and-drop; a future version could add cloud-picker integrations as a convenience once the client-side privacy story has clearly landed with users, since a picker necessarily involves a third-party authorization flow.
• Document management or version history beyond the retention windows in Section 6. PDFWorks is a processing tool, not a document repository; users needing long-term versioned storage are expected to keep their own copies.

2.9 Success Metrics #

North-star metric: weekly completed tool operations per active user (a completed operation is any tool run that reaches a terminal success state, client-side or server-side) — chosen because it reflects actual utility delivered rather than logins or page views, and it is measurable identically whether the operation ran in the browser or on a server.

3. Technology Stack & System Architecture #

3.1 Layer-by-Layer Stack #

Each layer below states the technology, its justification, and the leading alternative considered and rejected. The version table in Section 3.2 gives the line to cite for every dependency named here.

Language — TypeScript, end to end (web, API, workers-media, contracts, SDK). A single language across the browser, the API server, and the media worker lets packages/contracts' Zod schemas be imported, not re-implemented, everywhere except the Python-based worker-office service (Section 3.1, "Office worker language" below). The alternative considered was a Go API server for lower cold- start latency; rejected because splitting the type system in two would have re-created the exact hand-written-validator duplication the shared-contract discipline in Section 4.4 exists to eliminate.

Web framework — Next.js, App Router. Server components reduce client bundle size for content-heavy marketing and documentation routes, while the same framework's client components and route handlers serve the highly interactive tool pages. The alternative considered was a plain Vite SPA with a separate marketing static site; rejected because it would have meant two build pipelines and two deployment targets for what is, to the user, one product.

UI library — React. The dominant ecosystem for the class of component libraries this product depends on (Radix UI primitives, TanStack Table for job/history grids), and the framework Next.js is built around. No serious alternative was evaluated given the Next.js choice above.

Styling — Tailwind CSS, with the design tokens from Section 16.2 expressed as Tailwind theme extensions rather than a separate CSS-in-JS runtime. Utility classes keep the tool UI's dense, information-heavy layouts (page thumbnail grids, batch job tables) fast to build and avoid runtime style-computation cost, which matters for the performance budgets in Section 18.6. The alternative considered was vanilla-extract for zero-runtime CSS-in-JS; rejected because Tailwind's utility-first approach maps more directly onto the design system's constrained token set and has a larger contributor pool.

Headless component primitives — Radix UI. Provides accessible, unstyled primitives (dialog, dropdown, tabs, tooltip) that satisfy the WCAG 2.2 AA bar in Section 16 without hand-rolling focus management and ARIA wiring for every interactive component.

Icons — lucide-react. A single consistent icon set, tree-shakeable, matching the design system's line-icon visual language (Section 16.2).

Client state — Zustand, for ephemeral UI state (tool wizard step, selected pages, drag state) that does not belong in a server cache. The alternative considered was React Context alone; rejected because Context re-renders do not scale to the frequent, granular updates a page-thumbnail-grid drag interaction produces.

Server-state cache — TanStack Query, for every piece of data that originates from the API (job status polling, document lists, workspace membership). Handles cache invalidation, background refetch, and request deduplication so job-status polling (Section 13.5) does not need hand-rolled polling logic in every component that displays a job.

Data grids — TanStack Table, for the job history table, the batch job row list, and the API usage dashboard — all of which need client-side sorting, filtering, and virtualization at a scale (hundreds to low thousands of rows) that a hand-rolled table would handle poorly.

Forms — react-hook-form, with @hookform/resolvers binding directly to the Zod schemas from packages/contracts (Section 4.4), so a form's validation rules are never restated — they are the same schema the API validates against.

Schema and validation — Zod. The single source of truth for every request body, response body, and form value across the entire system, per Section 4.4.

Internationalization — next-intl. Chosen over a hand-rolled i18n layer because it integrates with the App Router's server components without a client-side waterfall, satisfying the i18n-architecture- without-translations scope stated in Section 2.8.

Local persistence (browser) — Dexie over IndexedDB, for metadata only (Section 3.7); never file bytes.

Worker RPC — Comlink, to give the main thread a promise-based, type-safe proxy to the WASM worker pool instead of hand-rolled postMessage message routing.

HTML sanitization — DOMPurify, applied to any HTML rendered from a converted document (the PDF → HTML tool, Section 9.7) before it touches the DOM, closing the obvious XSS vector a naive HTML render would open.

API framework — Hono. A single lightweight, standards-based (Fetch API) router that runs identically on the Node server and is trivially portable if a future edge deployment is wanted; it hosts both the public /v1 and internal /internal route trees (Section 3.9). The alternative considered was Express; rejected because Hono's smaller surface area and native TypeScript-first routing produce less boilerplate for the OpenAPI-generation pipeline in Section 4.4.

ORM and schema — Drizzle ORM, chosen for SQL-first ergonomics (queries read like SQL, not like a query-builder DSL) and a migration tool (drizzle-kit) that generates plain, reviewable SQL migration files rather than an opaque binary format.

Primary database — PostgreSQL. Relational integrity for billing, entitlements, and the signature-envelope state machine is non-negotiable; Postgres's native jsonb, partial indexes, and row-level constraints cover every modeling need in Section 5 without a second database engine.

Cache and queue backing store — Redis, backing both BullMQ (below) and the rate-limiter token buckets (Section 14.9).

Job queue — BullMQ, providing priority lanes, delayed jobs (for signature reminders, Section 10.5), and retry/backoff (Section 4.8) on top of Redis without operating a separate broker like RabbitMQ or Kafka, which would be disproportionate to this system's throughput.

Object storage client — AWS SDK for JavaScript v3 (S3 client), targeting the S3-compatible store chosen in Section 1.1.

Payments — Stripe, server SDK for subscription and metered-billing management plus Stripe.js only for the hosted Checkout and Billing Portal redirect flows described in Section 3.8 — never Stripe Elements.

Auth — better-auth, a self-hosted session and credential library (rather than a third-party hosted auth SaaS) so that account data never leaves the operator's own database, consistent with the product's privacy posture; supports the password/MFA/session model specified in Section 17.

Transactional email — Resend, with React Email for templates, so every transactional email (signature invites, receipts, security alerts) is built as a reviewable React component rather than a string-concatenated HTML blob.

Logging — Pino, structured JSON logging with redaction paths configured per Section 4.9's secret- handling rule.

Tracing — OpenTelemetry JS API, propagating W3C traceparent from the browser through the API into workers so a single request can be followed across every layer of Section 3.9's server runtime.

Error tracking — Sentry, for both the Next.js app and the Node services, per the per-app DSN setup in Section 1.1.

Unit and integration testing — Vitest. End-to-end testing — Playwright. Package build tooling — Vite (used only for building packages/* library outputs, not for the Next.js app itself, which uses Next's own build pipeline).

Image processing (server side) — sharp, for thumbnail generation and any raster resizing the server-side conversion pipeline needs outside of pdfcore's own image handling.

ID generation — uuidv7, generated application-side (Section 4.3) rather than relying on a database default, so IDs are available before an insert and are naturally time-sortable.

PDF engine — PDFium plus QPDF, compiled once to WebAssembly, detailed fully in Section 3.6.1 below.

OCR — OCRmyPDF orchestrating the Tesseract OCR engine, with pikepdf as OCRmyPDF's underlying PDF manipulation library — a proven, actively maintained combination purpose-built for adding a searchable text layer to a scanned PDF without altering its visual appearance.

Office and HTML conversion — LibreOffice (headless) for Office-format conversions, Poppler utils and Ghostscript for supporting PDF rasterization and PostScript-adjacent operations in the office-conversion pipeline.

Office worker language — Python. LibreOffice's headless automation, pikepdf, and OCRmyPDF all have their most mature, actively maintained integration surface in Python; rather than shelling out to Python from a Node process for every call, worker-office is a dedicated Python service that consumes BullMQ jobs directly via a Redis client, keeping the process boundary explicit instead of implicit.

3.2 Version Table #

This is the single, canonical version table for the entire document. It is the only place a specific dependency version number appears; every other section that names one of these dependencies cites it by number — "Section 3.2" — rather than restating a version line.

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

3.3 Monorepo Layout #

apps/
  web/            Next.js 16 App Router — marketing, app, tool pages, dashboard
  api/            Hono service — public REST API (/v1) + internal API (/internal)
  signer/         Next.js route group inside apps/web, served at sign.pdfworks.io
  worker-media/   Node container — OCR orchestration, rasterization, image work
  worker-office/  Python container — LibreOffice, pdf2docx, Poppler, Ghostscript
packages/
  pdfcore/        C++ sources + Emscripten build + TypeScript bindings  (THE engine)
  contracts/      Zod schemas + generated OpenAPI + shared types
  db/             Drizzle schema, migrations, seed
  ui/             Design system components + tokens
  sdk-js/         Public API client, published to npm
  config/         eslint/tsconfig/tailwind presets
infra/            Dockerfiles, compose, Helm chart, Terraform

Package purposes, one line each:

3.4 System Architecture Diagram #

                              ┌───────────────────────────┐
                              │        Browser            │
                              │  app.pdfworks.io           │
                              │  (COOP: same-origin,       │
                              │   COEP: credentialless)    │
                              │                            │
                              │  ┌──────────┐  ┌─────────┐ │
                              │  │Main thread│─▶│ Worker  │ │
                              │  │ (React,   │  │  pool   │ │
                              │  │  Zustand, │◀─│(pdfcore │ │
                              │  │  TanStack)│  │  WASM)  │ │
                              │  └────┬─────┘  └────┬────┘ │
                              │       │  OPFS staging│      │
                              │       │  Dexie (meta)│      │
                              └───────┼──────────────┼──────┘
                                      │ fetch (JSON)  │ upload (server-side tools only)
                                      ▼               ▼
                    ┌──────────────────────────────────────────────┐
                    │           apps/api  (Hono, Node 24)            │
                    │  /v1  (public REST API)  /internal (web app)   │
                    │  one auth chain — session cookie / API key     │
                    └───────┬───────────────┬────────────────────────┘
                            │               │
                     ┌──────▼─────┐   ┌─────▼──────┐
                     │ PostgreSQL │   │   Redis     │
                     │ (Drizzle)  │   │(BullMQ +    │
                     │            │   │ rate limit) │
                     └────────────┘   └──────┬──────┘
                                              │ enqueue
                       ┌──────────────────────┼──────────────────────┐
                       ▼                      ▼                      ▼
              ┌────────────────┐    ┌──────────────────┐   ┌─────────────────┐
              │ worker-media    │    │ worker-office     │   │  (esign/batch/  │
              │ (Node, gVisor)  │    │ (Python, gVisor)  │   │ webhook/janitor  │
              │ OCR, raster     │    │ LibreOffice, HTML  │   │  share the same  │
              └───────┬─────────┘    └────────┬──────────┘   │  worker pools by │
                      │                       │               │  queue routing)  │
                      └──────────┬────────────┘               └──────────────────┘
                                 ▼
                        ┌─────────────────┐
                        │  S3-compatible   │
                        │  object storage  │
                        │ (per-job envelope│
                        │   encryption)    │
                        └─────────────────┘

  Stripe Checkout / Billing Portal: hosted, redirect — no embedded iframe (Section 3.8)

3.5 Request Lifecycle #

3.5.1 Client-side operation (e.g., merge) #

1. User drops files onto the tool page; files are written directly to OPFS-backed scratch storage, never read fully into main-thread memory as a single buffer.
2. The main thread posts a job to the worker pool via Comlink, referencing the OPFS file handles.
3. A pool worker loads (or reuses, if already resident) the pdfcore WASM module, opens each input via QPDF's object model, and performs the merge as a sequence of object-model operations, writing the result to a new OPFS file.
4. Progress updates (0–100, matching Section 4.7's job state machine vocabulary) are posted back to the main thread over the Comlink channel and reflected in the UI without any network request.
5. On completion, the main thread offers a direct download from the OPFS-resident output file (via a File System Access save flow or a generated Blob download, depending on browser support) and records a lightweight metadata entry (filename, tool, timestamp — never bytes) in Dexie for the "recent files" list.
6. No network request contains file bytes at any point in this lifecycle. The only network activity is the initial page load and the WASM artifact fetch (cached per Section 18.6's performance budgets).

3.5.2 Server-side operation (e.g., OCR) #

1. The client requests a signed upload URL from /internal/documents (or, for API consumers, /v1/documents, Section 14.2).
2. The client uploads the file directly to S3-compatible storage via the signed URL; the API server never proxies file bytes through itself.
3. On upload completion (an S3 event or a client-confirmed callback), the API creates a documents row (Section 5) and, when the user submits the tool form, a jobs row in state queued, enqueuing a BullMQ job onto the appropriate queue (ocr, convert, and so on, Section 3.9) at the priority matching the user's plan (Section 12.2).
4. A worker in worker-media or worker-office picks up the job, downloads the encrypted object from S3-compatible storage into its per-job tmpfs, unwraps the per-job data key via KMS, decrypts, processes, and re-uploads the result under a new envelope-encrypted object.
5. The worker updates the jobs row to succeeded or failed and publishes a completion event; the client, which has been polling /v1/jobs/{jobId} (or holding a long-lived connection, Section 13.5), reflects the terminal state and offers a download link.
6. If a webhook is registered for the workspace, the API publishes a signed job.succeeded (or job.failed) event per Section 17.4.
7. The retention janitor (Section 6, Section 13.6) later deletes the uploaded and result objects per the 2-hour-after-terminal / 24-hour-absolute rule.

3.6 The pdfcore Engine #

3.6.1 Design #

pdfcore is compiled once, from PDFium (rendering, text/layout extraction, image decoding, form field interaction) and QPDF (object model manipulation, encryption, object streams, linearization), plus zlib, libjpeg-turbo, libwebp, and Brotli, into a single Emscripten-built WebAssembly artifact with a TypeScript binding layer over it. The same artifact runs unmodified in the browser worker pool (Section 3.7) and in the worker-media Node container (Section 3.9) — there is no separate "server engine." Given identical input bytes and an identical deterministicTimestamp parameter (which replaces any wall-clock-derived value the underlying libraries would otherwise embed, such as a PDF's /ModDate), an operation run in the browser and the same operation run through the public API produce byte-identical output. This equality is enforced by an automated cross-host test that runs the full golden-file corpus (Section 19.4) through both hosts and diffs the output bytes.

3.6.2 Threading and the single-threaded fallback #

The primary build is compiled with pthreads support and requires SharedArrayBuffer, which in turn requires the cross-origin isolation described in Section 3.8. A second build target, compiled without -pthread, ships alongside it as the single-threaded fallback described in Section 1.1; the loader selects between them at runtime based on self.crossOriginIsolated and the presence of SharedArrayBuffer. The fallback is slower — operations that would otherwise be parallelized across the worker pool's threads run sequentially within a single thread — but it is never wrong: the same object-model code path executes, only the threading strategy differs.

3.6.3 Memory limits and streaming #

pdfcore does not use WASM64; the addressable heap per worker is bounded by the 32-bit WASM memory model. For files above approximately 700 MB, the engine streams page ranges through OPFS-backed scratch storage rather than loading the full document into WASM linear memory at once — an operation like split or page extraction processes a bounded window of pages at a time, flushing completed output to OPFS before advancing. This is transparent to the user; the only observable effect is that very large files show incremental progress rather than an instantaneous jump to 100%.

3.6.4 Build pipeline, versioning, and caching #

The Emscripten build is a dedicated packages/pdfcore/build pipeline invoked in CI: it checks out PDFium at the commit pinned in the build script (Section 3.2 — PDFium is pinned by commit, not semver), checks out QPDF at the version line in Section 3.2, applies a small patch set (documented in packages/pdfcore/patches) that exposes the specific object-model functions the TypeScript bindings need, and produces pdfcore.wasm (threaded) and pdfcore.st.wasm (single-threaded fallback). Both artifacts are named with a content hash (pdfcore.<hash>.wasm) and served with a one-year immutable Cache-Control header, satisfying the performance budget in Section 18.6. The build script writes the resolved PDFium commit and QPDF version into a pdfcore-build-manifest.json file checked into the repository, so every deployed artifact is traceable to an exact source revision.

3.7 Browser Runtime #

• Worker pool. Sized clamp(navigator.hardwareConcurrency - 1, 2, 4) — leaving one logical core free for the main thread's UI work, with a floor of 2 (so even a 2-core device gets some parallelism) and a ceiling of 4 (beyond which coordination overhead outweighs benefit for typical document sizes). Comlink wraps each worker with a typed RPC surface exposing one method per pdfcore operation (merge, split, redact, and so on), each returning a promise that resolves with the OPFS handle of the result and rejects with a typed error (Section 14.6).
• OPFS staging. The Origin Private File System is the staging area for every input file, intermediate artifact, and output file. File bytes are never placed in localStorage, sessionStorage, or a base64 data URL — those mechanisms are unsuitable for multi-megabyte binary content and, for localStorage, are synchronous and would block the main thread.
• Dexie over IndexedDB — metadata only. Recent-file entries (filename, tool, timestamp, an OPFS path reference), tool presets (a user's saved watermark configuration, for example), draft annotations awaiting a user's "Apply" action, and queued batch descriptors. Never file bytes.
• Purge rules. Everything OPFS-resident is purged when the tab closes and whenever the user triggers the explicit "Clear local data" control in account settings. As a backstop against a tab that is never properly closed (e.g., the OS kills the browser process), a janitor sweep runs on next app load and removes any OPFS entry older than 24 hours.

3.8 Cross-Origin Isolation #

The app sets Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: credentialless on every response from app.pdfworks.io. This combination is what unlocks SharedArrayBuffer, which the threaded pdfcore build in Section 3.6.2 requires.

What it breaks. credentialless strips credentials (cookies, client certificates) from cross-origin subresource requests unless the subresource response opts back in via Cross-Origin-Resource-Policy: cross-origin. Any third-party embed that expects ambient credentials — most critically, an embedded payment iframe like Stripe Elements — cannot function inside an isolated document.

The resulting decision. Billing therefore uses Stripe Checkout (hosted, full-page redirect) for new subscriptions and the Stripe Billing Portal (hosted, full-page redirect) for plan changes, payment method updates, and cancellation. Stripe Elements is not used anywhere in this product. Any other third-party embed considered in the future that cannot satisfy credentialless is either dropped or moved to a non-isolated route segment (a route that does not set the isolation headers and therefore cannot load the threaded WASM build); the tool routes themselves always stay isolated.

Fallback when crossOriginIsolated is false. Some environments (certain corporate proxies, older browser versions, or an operator who has not yet propagated the isolation headers through an intermediate CDN correctly) will report self.crossOriginIsolated === false. In that case the loader selects the single-threaded pdfcore.st.wasm build from Section 3.6.2 automatically; every client-side tool remains fully functional, only slower. The UI does not surface this as an error — a small, dismissible notice ("Running in compatibility mode — some operations may be slower") is the only user-visible signal, and it is informational, not blocking.

3.9 Server Runtime #

• apps/api runs Hono on Node 24, terminating both the public /v1 API and the internal /internal API consumed by apps/web. One codebase, two route trees, one auth middleware chain that branches on credential type (session cookie for /internal, API key for /v1, Section 17.4).
• Jobs run on BullMQ on Redis. Named queues: ocr, convert, esign, batch, webhook, janitor. Two priority lanes — priority for Pro/Team/API paid workspaces and standard for Free — implemented as a BullMQ job-priority integer value on a single queue per queue name, not as separate queues, so queue depth and worker concurrency are managed once per job type rather than once per (job type × plan) combination.
• Blob storage is S3-compatible (Section 1.1). Every object is encrypted with a per-job data key using AES-256-GCM envelope encryption: a fresh 256-bit data key is generated per job, used to encrypt the object client-side-of-storage (i.e., inside the API or worker process, before the PUT), then wrapped by a KMS master key and stored, wrapped, on the job's row. Deleting the wrapped key from the row cryptographically shreds the object immediately — the ciphertext bytes become permanently unrecoverable even before the janitor's byte-level deletion sweep runs, which is what makes the "delete now" guarantee in Section 6 instantaneous from the user's perspective.
• Workers run in gVisor-sandboxed containers: no outbound network access (a compromised OCR or Office-conversion dependency cannot exfiltrate data or phone home), a read-only root filesystem, a per-job tmpfs mount that is wiped on job completion, and a hard wall-clock timeout enforced by the container orchestrator independent of the application-level timeout budgets in Section 4.8.

3.10 Data Flow: Upload, Process, Download, Delete #

UPLOAD                         PROCESS                         DOWNLOAD                    DELETE
------                         -------                         --------                     ------
Client requests   ──▶   API creates `documents`  ──▶   API creates `jobs`   ──▶  Worker downloads,
signed PUT URL          row (state: uploaded)          row (state: queued)      unwraps data key,
     │                        │                               │                 decrypts, processes
     ▼                        ▼                               ▼                       │
Client PUTs bytes      Object stored with a           BullMQ job enqueued            ▼
directly to S3         fresh per-job data key         on the matching queue    Worker re-uploads
(never through         (AES-256-GCM), key              at the plan's           result under a NEW
the API process)       wrapped by KMS, wrapped         priority lane           envelope-encrypted
                        key stored on the row                                  object; `jobs` row
                                                                                → succeeded
                                                                                       │
                                                                                       ▼
                                                                        Client downloads via a
                                                                        short-lived signed GET URL
                                                                        (Section 14.2); webhook
                                                                        fires if registered

                                                                        ── 2 hours after terminal state,
                                                                           or 24 hours after upload,
                                                                           or an explicit delete request ──
                                                                                       ▼
                                                                        Wrapped data key destroyed
                                                                        (cryptographic shred,
                                                                        immediate) → object bytes
                                                                        removed by the janitor queue
                                                                        within 60 seconds

Each of the four stages above has its own failure and retry behavior, described individually below.

3.10.1 Upload #

The client requests a signed PUT URL scoped to a single object key and a maximum content length matching the requesting plan's file-size limit (Section 12.2). The signed URL is valid for 5 minutes; if the client does not complete the PUT within that window, it must request a new one. On a successful PUT, S3-compatible storage emits an event (or, where the store does not support event notifications, the client confirms completion via POST /internal/documents/{id}/confirm-upload), which flips the documents row from pending to uploaded and triggers magic-byte and structural validation (Section 17.5) before the document becomes eligible for any job. A PUT that never completes leaves an orphaned pending row, swept by the janitor queue after 1 hour.

3.10.2 Process #

Once a job is enqueued, a worker claims it, downloads the encrypted object into its per-job tmpfs, unwraps the data key via KMS, decrypts into memory (never to unencrypted disk), and performs the operation. Every worker job handler wraps its core logic in the typed-result pattern from Section 4.5: a processing failure (a corrupt input, an OCR engine crash, a LibreOffice timeout) is caught, mapped to a processing_error in the error envelope (Section 14.6), and the job transitions to failed with the mapped error recorded on the row — the raw underlying exception is logged (Section 4.3, logging row) but never surfaced verbatim to the caller, since library-internal error text can leak implementation detail.

3.10.3 Download #

The completed object is fetched only via a short-lived signed GET URL (default 15-minute expiry, regenerated on each GET /v1/documents/{id}/download-url call, Section 14.2) — never a permanently public object URL. Every download-URL issuance is logged with the requesting principal (user or API key) so the audit log (Section 17) can answer "who downloaded this file and when" even though the file itself is not retained past the windows in Section 6.

3.10.4 Delete #

Deletion is either scheduled (the default 2-hour-after-terminal / 24-hour-absolute rule) or immediate (an explicit "Delete now" click or a DELETE /v1/documents/{id} call). Both paths converge on the same two-step shred: destroy the wrapped data key on the row first (this is the moment the object becomes cryptographically unrecoverable, and it completes within the deleting request itself), then enqueue a janitor job that issues the physical DeleteObject call against the S3-compatible store, completing within 60 seconds. The documents row itself is soft-deleted (deleted_at set, Section 4.3) rather than removed, so billing and audit queries retain an accurate historical record without retaining any file content.

3.11 Environments #

Every environment runs the identical container images and Terraform-defined infrastructure shape; what differs is environment variables (Section 23.2), the Stripe mode, and the data seeded into it. No environment-specific code branches are permitted in the application layer — any behavior that must differ by environment is expressed as configuration, consistent with the twelve-factor discipline in Section 4.9.

3.12 Build and Release Overview #

Every push to a feature branch triggers CI: lint, type-check, unit tests, and a Preview environment deploy. Merging to the trunk branch triggers the full test suite including Playwright E2E and the pdfcore cross-host byte-equality check (Section 3.6.1), then an automatic deploy to Staging. A production release is a manually triggered promotion of a specific, already-validated Staging build artifact — production never builds from source directly. Container images are tagged with the Git commit SHA and the pdfcore build manifest hash from Section 3.6.4, so a production incident can be traced to an exact source revision and an exact engine build.

A production rollback is the same promotion mechanism run in reverse: selecting the immediately prior image tag and re-running the promotion step, which typically completes within the time it takes the container orchestrator to cycle running pods (well under the 99.9% monthly availability target's error budget, Section 18). The full CI/CD pipeline, environment-promotion tooling, and infrastructure-as- code layout are specified in Section 20.

4. Conventions & Engineering Standards #

4.1 TypeScript Strictness #

Every tsconfig.json in the repository extends a single base configuration in packages/config. The base configuration sets:

4.2 Linting, Formatting, Import Order, Path Aliases #

• ESLint uses a flat config in packages/config/eslint, extending typescript-eslint's strict and stylistic rule sets, the React and React Hooks recommended sets, and jsx-a11y (feeding directly into the WCAG 2.2 AA bar from Section 16). Every app and package extends this one shared config rather than defining its own rule set.
• Prettier is the sole formatter (no ESLint stylistic-formatting rules are enabled where Prettier already covers the case, avoiding the two tools fighting each other). Configuration: 2-space indentation, semicolons, double quotes for JSX attributes and single quotes elsewhere per Prettier's default JS convention, 100-character print width, trailing commas everywhere valid in the current target syntax.
• Import ordering is enforced by eslint-plugin-import's order rule in four groups, blank-line separated: (1) Node built-ins, (2) external packages, (3) internal packages via path alias (below), (4) relative imports. Within each group, alphabetical.
• Path aliases. Every app and package uses @/* to mean "this package's own src/ root," and cross-package imports use the package's published name (@pdfworks/contracts, @pdfworks/ui, @pdfworks/db) resolved via pnpm workspace linking — never a relative path that crosses a package boundary (../../packages/contracts/src/... is disallowed by an ESLint no-restricted-imports rule).
• No default exports, except pages. Every module exports named bindings; the sole exception is Next.js's file-system-routing convention, which requires a default export for page.tsx, layout.tsx, loading.tsx, error.tsx, and route.ts files. This keeps every other import statement self-documenting at the call site (import { MergeToolPage } from ... versus an anonymous default) and prevents accidental name drift between a module's file name and its exported symbol.
• File and folder naming. Files: kebab-case.ts / kebab-case.tsx. Folders: kebab-case. React component files are named after their primary export in kebab-case (tool-card.tsx exports ToolCard). Test files sit beside the code they test with a .test.ts/.test.tsx suffix (tool-card.test.tsx beside tool-card.tsx); Playwright E2E specs live in a top-level e2e/ directory per app, named after the user journey they cover (e2e/guest-merge-daily-cap.spec.ts, matching Section 2.7.1).
• Component naming. PascalCase, matching the file's primary export. Compound components use a dot-namespace convention (Dialog.Root, Dialog.Trigger) matching the Radix UI convention they wrap.
• Hook naming. useCamelCase, always starting with use, one hook per file, file named after the hook (use-job-polling.ts exports useJobPolling).

4.3 Canonical Conventions Table #

4.4 Shared-Contract Discipline #

packages/contracts holds exactly one Zod schema per API resource and per internal message shape (job payloads, webhook event bodies, form values that mirror an API request). Every other package imports these schemas rather than declaring its own:

• The web app binds react-hook-form to a contract schema via @hookform/resolvers/zod, so a form's client-side validation is byte-for-byte the same rule the API will apply.
• The API parses every request body and query-string object through the matching schema at the route-handler boundary (schema.parse(rawInput)), before any business logic runs — this is the one and only validation point; nothing downstream re-validates.
• The workers parse the BullMQ job payload through its schema on dequeue, so a malformed payload (which should be impossible given the API validated it at enqueue time, but a defense-in-depth check regardless) fails loudly rather than corrupting a document mid-pipeline.
• The published SDK (packages/sdk-js) imports the same schemas to type its method signatures, so a TypeScript consumer of the SDK gets the exact same type the server will accept, and a runtime input can optionally be validated client-side before the SDK issues the request.

How types flow. Every schema exports both the runtime validator and its inferred static type via z.infer<typeof schema>; no type in the system is hand-written as a duplicate of a schema's shape. Example:

// packages/contracts/src/documents.ts
import { z } from "zod";

export const documentSchema = z.object({
  id: z.string().startsWith("doc_"),
  filename: z.string().min(1).max(255),
  sizeBytes: z.number().int().positive(),
  mimeType: z.enum(["application/pdf"]),
  status: z.enum(["uploaded", "processing", "ready", "deleted"]),
  workspaceId: z.string().startsWith("wsp_").nullable(),
  createdAt: z.string().datetime(),
  deletedAt: z.string().datetime().nullable(),
});

export type Document = z.infer<typeof documentSchema>;

How the OpenAPI document is generated. packages/contracts also declares, per route, a thin route-metadata object (HTTP method, path, request schema, response schema, the error types the route can return) using @hono/zod-openapi's createRoute helper:

// packages/contracts/src/routes/documents.ts
import { createRoute } from "@hono/zod-openapi";
import { documentSchema } from "../documents";
import { errorEnvelopeSchema } from "../errors";

export const getDocumentRoute = createRoute({
  method: "get",
  path: "/v1/documents/{documentId}",
  request: {
    params: z.object({ documentId: z.string().startsWith("doc_") }),
  },
  responses: {
    200: { content: { "application/json": { schema: documentSchema } }, description: "The document." },
    404: { content: { "application/json": { schema: errorEnvelopeSchema } }, description: "Not found." },
  },
});

A single build step in packages/contracts walks every registered route and emits openapi.json, which is what docs.pdfworks.io renders and what the SDK's code-generation step consumes. The OpenAPI document is never hand-written or hand-edited; a route whose behavior changes without its schema changing is, by definition, undocumented drift and is caught by the contract test suite in Section 19.3.

4.5 Error Handling Philosophy #

• Typed result objects at every boundary. A function that can fail in an expected, handleable way (a validation failure, a quota exceeded, a not-found lookup) returns a discriminated union ({ ok: true, value: T } | { ok: false, error: AppError }) rather than throwing. This applies at every layer boundary: route handler to service function, service function to repository function, worker job handler to pdfcore binding call.
• Exceptions are reserved for programmer error — a violated invariant, an unreachable switch branch, a failed assertion — conditions that indicate a bug, not a valid input the caller should handle. These are allowed to throw and are caught only at the outermost boundary (the Hono error middleware, or a worker's top-level job handler), which converts them into the api_error type from the error envelope (Section 14.6) and reports them to Sentry (Section 1.1) with full context.
• Never swallow an error. A catch block that does not either (a) convert the error into a typed result the caller can act on, (b) re-throw, or (c) log and re-throw is a defect. An empty catch {} or a catch that only logs and continues silently is disallowed by an ESLint rule (no-empty combined with a repository-specific rule forbidding a catch block with no throw and no typed-result return).

4.6 The Error Envelope Rule #

There is exactly one error envelope shape in this system, defined once, canonically, in Section 14.6, with its code catalogue in Section 23.1. It is never redefined or restated here. The rule this section fixes, as a Convention: every layer of this system — route handlers, worker job handlers, the SDK's error class, and the UI's error-display components — constructs, receives, or renders exactly that Section 14.6 shape and never a locally invented one, even from a code path (a worker, a background job, an internal-only route) that has no end user directly reading the response; and the code catalogue is additive-only — a code, once shipped, is never repurposed to mean something else. This uniformity is what lets a single client-side error handler and a single SDK error class work everywhere. See Section 14.6 for the envelope's shape and Section 23.1 for the code catalogue.

4.7 The Job State Machine #

One state machine governs every asynchronous operation in the system — server-side jobs tracked in the jobs table and client-side jobs tracked in the browser's local job store use the identical state names, so the UI has exactly one vocabulary regardless of where an operation actually executes.

Terminal states are exactly succeeded, failed, canceled, expired — no other states exist, and no transition out of a terminal state is valid. Progress within running is represented as an integer 0–100 plus an optional free-text stage string (for example, "Extracting text layer" during an OCR job), both of which are informational only and never used as a state-transition trigger.

4.8 Async Patterns, Cancellation, Retry #

• Cancellation propagates via the standard AbortSignal/AbortController pair at every layer: a user clicking "Cancel" on a client-side tool aborts the signal passed into the pdfcore Comlink call, which the WASM binding layer checks between chunked operations (page-by-page during a large merge, for instance) and stops at the next checkpoint rather than mid-write. Server-side, canceling a job sets its row to canceled and publishes a BullMQ event the worker's job handler listens for, checked at the same kind of checkpoint boundaries. Every function in packages/pdfcore's TypeScript bindings and every API route handler that can run longer than a single tick accepts an AbortSignal as its last parameter — there is no separate cancellation channel to remember to wire up:

// packages/pdfcore/src/operations/merge.ts
export async function mergeDocuments(
  inputs: OpfsFileHandle[],
  signal: AbortSignal,
): Promise<Result<OpfsFileHandle, PdfCoreError>> {
  const output = await createOutputHandle();
  for (const [index, input] of inputs.entries()) {
    if (signal.aborted) {
      return { ok: false, error: { code: "operation_canceled", stage: `page_${index}` } };
    }
    await appendPages(output, input);
  }
  return { ok: true, value: output };
}

• Retry and backoff. Every BullMQ job that fails with a transient error is retried with exponential backoff and jitter. The exact per-queue attempt counts and backoff parameters (base delay, growth factor, jitter percentage, and the cap between attempts) are a job-orchestration operating parameter, not an engineering convention, and are defined once, in Section 13.3.5 — they are not restated here. The customer-facing webhook delivery retry schedule shown to a workspace owner in the dashboard is a related but distinct concern, defined separately in Section 14.10.6. What this convention fixes, regardless of which queue a job runs on, is the classification that decides whether a retry happens at all: an error is retried only when it is classified as transient (a network timeout talking to S3-compatible storage, a LibreOffice worker that exceeded a soft memory limit and was killed); an error classified as permanent (a malformed input PDF the structural validator in Section 17.5 rejected, an unsupported page count) fails immediately on the first attempt, since retrying a permanent failure only delays the user's error message without any chance of success. A job that exhausts its configured retry budget transitions to failed with the last attempt's error recorded on the row.
• Timeout budgets per layer. API route handlers: 30 seconds (anything longer must be an async job, not a synchronous request) — this is an API-layer convention, distinct from the job-level budgets below, so it is fixed here rather than alongside them. Worker and job wall-clock timeouts (the per-queue processing budgets for worker-media, worker-office, and esign jobs) are defined once, in Section 13.3.8, and are not restated here. Client-side pdfcore operations have no imposed timeout beyond the browser tab's own lifecycle, since they run entirely locally and blocking a pool worker thread does not affect the server. What this convention fixes, regardless of layer, is the outcome of an expiry: a server-side timeout expiry moves the job to expired (Section 4.7), never failed — the distinction lets the dashboard and the API report "this took too long" separately from "this failed," which drives different remediation on the operator's side (a queue capacity problem versus a pdfcore or conversion-pipeline defect).

4.9 Configuration and Secret Handling #

Configuration follows twelve-factor principles: every environment-specific value is an environment variable, never a checked-in config file with environment branches. No secret (API key, database password, KMS key ARN, webhook signing secret) is ever committed to the repository; .env.example files document every required variable name with a placeholder or safe default, never a real value. The full environment-variable catalogue is Section 23.2.

Boot-time validation. Every app and worker validates its complete configuration through a Zod schema (packages/config's env.ts pattern, one per app) at process start, before any request is served or any job is dequeued. A missing required variable, a malformed URL, or an out-of-range numeric value causes the process to exit immediately with a clear, single-line error naming the invalid variable — the process never starts in a partially configured state and never fails on the first request instead of at boot.

// apps/api/src/env.ts
import { z } from "zod";

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url(),
  S3_BUCKET_DOCUMENTS: z.string().min(1),
  STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
  STRIPE_WEBHOOK_SECRET: z.string().startsWith("whsec_"),
  KMS_MASTER_KEY_ARN: z.string().min(1),
  NODE_ENV: z.enum(["development", "test", "production"]),
});

export const env = envSchema.parse(process.env); // throws and exits on invalid config

Feature flags (Section 4.3) are read through one typed accessor (getFlag("euResidencyEnabled", workspaceId)) backed by the feature_flags table, never as a raw process.env boolean check scattered through business logic — this keeps every flag's evaluation auditable and toggleable without a redeploy.

4.10 Git Workflow and Review Standards #

• Trunk-based development. One long-lived branch (main); every change is a short-lived feature branch merged back within, at most, a few days. No long-lived release branches.
• Conventional commits. Every commit message follows <type>(<scope>): <summary>, types limited to feat, fix, refactor, test, docs, chore, perf, ci. The type and a squashed summary of the pull request's commits become the merge commit message, which in turn drives the automated changelog.
• Pull request template requires: a one-paragraph description of the change, the specific section of this specification it implements (when applicable), a manual test description, and a checklist covering: tests added or updated, no new TBD/placeholder content shipped, the Processing Location Indicator verified if a tool's execution location was touched (Section 2.5), and accessibility checked if a UI surface changed.
• Required checks, all blocking merge: type-check, lint, unit tests, the contract test suite (Section 19.3, verifying the OpenAPI document matches implemented routes), Playwright E2E on the changed app, and the pdfcore cross-host byte-equality check (Section 3.6.1) when packages/pdfcore changes.
• Review rules. Every pull request requires at least one approving review from someone other than the author before merge. A pull request touching packages/contracts requires review from someone familiar with every consumer package (web, API, workers, SDK), since a schema change is, by construction, a breaking-change candidate for all four.

4.11 Definition of Done #

A change is done when: it implements the specified behavior with no TBD/placeholder content; it has unit test coverage for its new logic and, where applicable, an E2E test for the user-facing journey it affects; it passes every required check in Section 4.10; it does not regress the performance budgets in Section 18.6 or the accessibility bar in Section 16; any tool whose execution location it touches has a verified, matching Processing Location Indicator (Section 2.5) enforced by the CI check described there; its error paths return the error envelope (Section 14.6) with an entry added to the error catalogue (Section 23.1) if a new code was introduced; and, if it introduces or changes a shared contract, the OpenAPI document (Section 4.4) has been regenerated and committed as part of the same pull request.

4.12 Documentation Standard #

Every exported function, type, and React component in packages/* (code intended for reuse across apps) carries a doc comment (/** ... */) stating its purpose, its parameters if non-obvious from their names and types, and any thrown-vs-returned error behavior per Section 4.5's discipline. Application-level code in apps/* — route handlers, page components, one-off business logic — does not require doc comments; its self-documentation is the typed function signature plus the shared contract schema it validates against (Section 4.4), and a doc comment restating a Zod schema's already -explicit shape is noise, not documentation. A doc comment is never a substitute for a clearer name or a smaller function; if a doc comment is needed to explain why a function's obvious-looking code does something non-obvious (a workaround for a specific PDFium quirk, for example), a plain // comment at the relevant line is preferred over a doc comment, since the explanation belongs next to the code it explains, not at the function's declaration.

// packages/pdfcore/src/operations/redact.ts

/**
 * Permanently removes the content under each region in `redactions` from `input`,
 * following the nine-step algorithm defined in this specification's redaction section.
 * Never performs an incremental save; always returns a fully rewritten document.
 *
 * @param input - The source document handle. Not mutated; a new handle is returned.
 * @param redactions - One or more page-relative regions to remove. Coordinates are in
 *   PDF user space (points, origin bottom-left), matching the page's own coordinate system.
 * @returns `ok: false` with `code: "redaction_verification_failed"` if the post-redaction
 *   verification pass (re-extraction and re-render check) finds any surviving content —
 *   in that case, the output is discarded and never returned to the caller.
 */
export async function redactDocument(
  input: OpfsFileHandle,
  redactions: RedactionRegion[],
  signal: AbortSignal,
): Promise<Result<OpfsFileHandle, PdfCoreError>> {
  // implementation
}

This is the reference shape every packages/pdfcore binding follows: a doc comment that would let a caller use the function correctly without opening its implementation, and nothing more speculative than that.

5. Data Model & Database Schema #

This section is the single canonical definition of persisted state for PDFWorks. Every other section that mentions a table, column, enum value, or index refers back to this one; none of them redefine it. All storage described here lives in a single PostgreSQL 18 database (packages/db in the monorepo), accessed exclusively through Drizzle ORM 0.45.x. No table in this section is optional: the executor creates all of them exactly as specified.

5.1 Entity-Relationship Overview #

5.1.1 Diagram #

The diagram groups the 44 tables into nine domains and shows the ownership edges that matter for cardinality and cascade behavior. Full column-level detail for every table follows in Sections 5.2–5.10.

graph TD
  subgraph Identity["Identity & Sessions"]
    users
    user_sessions
    user_mfa_factors
    user_recovery_codes
    email_verification_tokens
    password_reset_tokens
  end

  subgraph Teams["Workspaces & Teams"]
    workspaces
    workspace_members
    workspace_invitations
    guest_devices
  end

  subgraph Billing["Billing & Entitlements"]
    plans
    subscriptions
    subscription_items
    usage_records
    usage_daily_rollups
    spend_caps
    invoices
  end

  subgraph Docs["Documents & Storage"]
    documents
    document_blobs
  end

  subgraph Jobs["Jobs & Batch Processing"]
    jobs
    job_events
    job_artifacts
    batch_jobs
    batch_job_items
  end

  subgraph API["API Access & Webhooks"]
    api_keys
    api_key_scopes
    api_key_ip_rules
    webhook_endpoints
    webhook_deliveries
  end

  subgraph Esign["E-Signature"]
    envelopes
    envelope_documents
    envelope_signers
    envelope_fields
    envelope_audit_events
    envelope_reminders
    signature_assets
  end

  subgraph Config["Templates & Configuration"]
    templates
    ocr_language_packs
    feature_flags
  end

  subgraph Ops["Compliance, Audit & Operations"]
    audit_log
    rate_limit_state
    data_export_requests
    deletion_requests
    email_log
  end

  users -->|1:N| user_sessions
  users -->|1:N| user_mfa_factors
  users -->|1:N| workspace_members
  workspaces -->|1:N| workspace_members
  workspaces -->|1:N| workspace_invitations
  users -->|1:1| subscriptions
  workspaces -->|1:1| subscriptions
  plans -->|1:N| subscriptions
  subscriptions -->|1:N| subscription_items
  users -->|1:N| documents
  workspaces -.->|0:N| documents
  documents -->|1:N| document_blobs
  users -->|1:N| jobs
  jobs -->|1:N| job_events
  jobs -->|1:N| job_artifacts
  batch_jobs -->|1:N| batch_job_items
  batch_job_items -->|0:1| jobs
  users -->|1:N| api_keys
  api_keys -->|1:N| api_key_scopes
  api_keys -->|1:N| api_key_ip_rules
  webhook_endpoints -->|1:N| webhook_deliveries
  users -->|1:N| envelopes
  envelopes -->|1:N| envelope_documents
  envelopes -->|1:N| envelope_signers
  envelope_signers -->|1:N| envelope_fields
  envelopes -->|1:N| envelope_audit_events
  envelopes -->|1:N| envelope_reminders
  envelope_signers -.->|0:N| signature_assets
  users -->|1:N| templates

5.1.2 Entity Table #

5.1.3 Identifier Format #

Every table's primary key is id uuid, generated application-side as a UUIDv7 by calling uuidv7() (from the uuidv7 package) before insert — never gen_random_uuid(), never a database default. UUIDv7 embeds a millisecond timestamp in its high bits, so primary keys are monotonically sortable by creation time without a separate created_at index for coarse ordering.

Resources that are addressable directly through the public REST API (Section 14) also have a public ID: the prefix for that resource type, followed by an underscore, followed by the 128 bits of the UUID encoded as 26 characters of Crockford Base32 (alphabet 0123456789ABCDEFGHJKMNPQRSTVWXYZ, uppercase canonical, case-insensitive on decode, no padding character). The public ID is never stored as a separate column — it is a pure, deterministic function of the same 16 bytes as the internal id, computed in packages/contracts:

// packages/contracts/src/id.ts
import { z } from 'zod';

const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';

export function encodeId(prefix: string, id: string /* uuid, e.g. from users.id */): string {
  const bytes = Buffer.from(id.replace(/-/g, ''), 'hex'); // 16 bytes
  let bits = 0n;
  for (const b of bytes) bits = (bits << 8n) | BigInt(b);
  let out = '';
  for (let i = 0; i < 26; i++) {
    out = CROCKFORD[Number(bits & 0x1fn)] + out;
    bits >>= 5n;
  }
  return `${prefix}_${out}`;
}

export function decodeId(publicId: string): string {
  const [, encoded] = publicId.split(/_(.+)/); // split on first underscore only
  let bits = 0n;
  for (const ch of encoded.toUpperCase()) {
    const v = CROCKFORD.indexOf(ch);
    if (v === -1) throw new InvalidPublicIdError(publicId);
    bits = (bits << 5n) | BigInt(v);
  }
  const hex = bits.toString(16).padStart(32, '0').slice(-32);
  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
}

export const publicIdSchema = (prefix: string) =>
  z.string().regex(new RegExp(`^${prefix}_[0-9A-HJKMNP-TV-Z]{26}$`), 'invalid_public_id');

A request handler that receives a public ID decodes it back to the raw UUID and queries the primary key directly — there is no separate lookup index to maintain, and a malformed public ID fails Zod validation before it ever reaches a query. Example: doc_01H8XGJ4RS3K9QY0VJXNVXFPTZ decodes to the same bytes as internal id 018e1e6b-9a4f-7c21-8b3d-2f5a9e7c4d10.

Locked prefix assignments — the only thirteen resource types with a public ID:

Every other table's primary key is a UUIDv7 used only internally. It never appears in a URL or a JSON response body on its own; where a related row must be identified in a response, its parent's public ID is used together with a stable positional or role-based field (for example, an envelope_signer is addressed inside the envelope's JSON payload by its email and routingOrder, not by a bare ID).

5.1.4 Standard Columns #

To avoid repeating identical definitions 44 times, every table below has the following columns unless a per-table note says otherwise; they are omitted from the per-table column lists in Sections 5.2–5.10 and shown only in the Drizzle code:

All timestamp columns are timestamptz, always written and read in UTC. All foreign keys use ON UPDATE CASCADE uniformly (a no-op in practice since primary keys are immutable UUIDv7 values, but consistent behavior costs nothing); the ON DELETE behavior is chosen per relationship and stated explicitly for every foreign key below. Table names are snake_case and plural; column names are snake_case. No PostgreSQL enum type is used anywhere — every enumerated column is text plus a CHECK constraint, mirrored by a Zod enum in packages/contracts (full catalogue in Section 5.11).

5.1.5 Shared Drizzle Helpers #

Every code block in Sections 5.2–5.10 assumes these imports and helpers from packages/db/src/columns.ts:

import {
  pgTable, uuid, text, integer, bigint, boolean, timestamp, jsonb,
  smallint, numeric, date, customType, index, uniqueIndex, check, primaryKey,
} from 'drizzle-orm/pg-core';
import { sql } from 'drizzle-orm';

export const inet = customType<{ data: string }>({ dataType: () => 'inet' });
export const cidr = customType<{ data: string }>({ dataType: () => 'cidr' });

export const id = () => uuid('id').primaryKey();
export const createdAt = () => timestamp('created_at', { withTimezone: true }).notNull().defaultNow();
export const updatedAt = () => timestamp('updated_at', { withTimezone: true }).notNull().defaultNow();
export const deletedAt = () => timestamp('deleted_at', { withTimezone: true });

packages/db never uses .defaultRandom(), .$defaultFn(), or a Postgres-side UUID generator for id — the application layer (a single createId() wrapper around uuidv7()) always supplies the value, so the same generator that produced the internal ID is the one whose output gets Base32-encoded into the public ID.

5.2 Identity & Sessions #

5.2.1 users #

The account and authentication root. Owner: user (self). Delete policy: soft. Retention: indefinite while active.

Primary key id. Foreign keys: default_workspace_id → workspaces(id) ON DELETE SET NULL — a workspace's deletion must never delete or corrupt the user record that happened to default into it. Unique: lower(email); stripe_customer_id. Indexes: ux_users_email_lower (lower(email)) — serves login lookup and signup duplicate-check; ix_users_stripe_customer_id (stripe_customer_id) — serves Stripe webhook resolution; ix_users_active (id) WHERE deleted_at IS NULL — serves admin active-user counts.

export const users = pgTable('users', {
  id: id(),
  email: text('email').notNull(),
  emailVerifiedAt: timestamp('email_verified_at', { withTimezone: true }),
  passwordHash: text('password_hash').notNull(),
  displayName: text('display_name').notNull(),
  avatarUrl: text('avatar_url'),
  defaultWorkspaceId: uuid('default_workspace_id').references(() => workspaces.id, { onDelete: 'set null' }),
  siteRole: text('site_role').notNull().default('user'),
  locale: text('locale').notNull().default('en'),
  timezone: text('timezone').notNull().default('UTC'),
  mfaEnabled: boolean('mfa_enabled').notNull().default(false),
  stripeCustomerId: text('stripe_customer_id'),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
  deletedAt: deletedAt(),
}, (table) => [
  uniqueIndex('ux_users_email_lower').on(sql`lower(${table.email})`),
  uniqueIndex('ux_users_stripe_customer_id').on(table.stripeCustomerId),
  check('ck_users_site_role', sql`${table.siteRole} in ('user', 'support', 'admin')`),
]);

5.2.2 user_sessions #

A better-auth login session. Owner: user. Delete policy: hard. Retention: until expiry or revoke, absolute max 90 days.

No updated_at on this table — a session row is replaced (new row) on rolling renewal rather than mutated, so the renewal history is auditable. Primary key id. Foreign keys: user_id → users(id) ON DELETE CASCADE — a session is meaningless once the account is gone. Unique: session_token_hash. Indexes: ux_user_sessions_token_hash (session_token_hash) — serves the per-request auth-middleware lookup (highest-frequency query in the system, Section 5.13 #1); ix_user_sessions_user_expiry (user_id, expires_at) — serves the account settings "active sessions" list and the janitor's expiry sweep.

export const userSessions = pgTable('user_sessions', {
  id: id(),
  userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
  sessionTokenHash: text('session_token_hash').notNull(),
  ipAddress: inet('ip_address'),
  userAgent: text('user_agent'),
  expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
  createdAt: createdAt(),
}, (table) => [
  uniqueIndex('ux_user_sessions_token_hash').on(table.sessionTokenHash),
  index('ix_user_sessions_user_expiry').on(table.userId, table.expiresAt),
]);

5.2.3 user_mfa_factors #

A registered TOTP factor. Owner: user. Delete policy: hard. Retention: indefinite while enabled.

No updated_at. Primary key id. Foreign keys: user_id → users(id) ON DELETE CASCADE. Unique: (user_id, type) — one TOTP factor per user. Indexes: ix_user_mfa_factors_user_id (user_id) — serves the login-flow "does this user have MFA" check.

export const userMfaFactors = pgTable('user_mfa_factors', {
  id: id(),
  userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
  type: text('type').notNull().default('totp'),
  secretCiphertext: bytea('secret_ciphertext').notNull(),
  secretKeyId: text('secret_key_id').notNull(),
  verifiedAt: timestamp('verified_at', { withTimezone: true }),
  createdAt: createdAt(),
}, (table) => [
  uniqueIndex('ux_user_mfa_factors_user_type').on(table.userId, table.type),
  check('ck_user_mfa_factors_type', sql`${table.type} = 'totp'`),
]);

bytea is imported alongside the other drizzle-orm/pg-core types; it was omitted from the shared import list in Section 5.1.5 for brevity and is assumed available in every code block below that uses it.

5.2.4 user_recovery_codes #

A single-use MFA backup code. Owner: user. Delete policy: hard. Retention: indefinite until used or MFA disabled.

No updated_at. Primary key id. Foreign keys: user_id → users(id) ON DELETE CASCADE. Unique: (user_id, code_hash). Indexes: ix_user_recovery_codes_unused (user_id) WHERE used_at IS NULL — serves the MFA-challenge "how many codes remain" check and the code-consumption lookup.

export const userRecoveryCodes = pgTable('user_recovery_codes', {
  id: id(),
  userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
  codeHash: text('code_hash').notNull(),
  usedAt: timestamp('used_at', { withTimezone: true }),
  createdAt: createdAt(),
}, (table) => [
  uniqueIndex('ux_user_recovery_codes_user_code').on(table.userId, table.codeHash),
  index('ix_user_recovery_codes_unused').on(table.userId).where(sql`${table.usedAt} is null`),
]);

5.2.5 email_verification_tokens #

A one-time email confirmation token. Owner: user. Delete policy: hard. Retention: 24 hours.

No updated_at. Primary key id. Foreign keys: user_id → users(id) ON DELETE CASCADE. Unique: token_hash. Indexes: ux_email_verification_tokens_hash (token_hash) — serves the verification-link click; ix_email_verification_tokens_user (user_id) WHERE consumed_at IS NULL — serves "resend verification" de-duplication.

export const emailVerificationTokens = pgTable('email_verification_tokens', {
  id: id(),
  userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
  tokenHash: text('token_hash').notNull(),
  newEmail: text('new_email'),
  expiresAt: timestamp('expires_at', { withTimezone: true }).notNull().default(sql`now() + interval '24 hours'`),
  consumedAt: timestamp('consumed_at', { withTimezone: true }),
  createdAt: createdAt(),
}, (table) => [
  uniqueIndex('ux_email_verification_tokens_hash').on(table.tokenHash),
  index('ix_email_verification_tokens_user_pending').on(table.userId).where(sql`${table.consumedAt} is null`),
]);

5.2.6 password_reset_tokens #

A one-time password reset token. Owner: user. Delete policy: hard. Retention: 1 hour.

No updated_at. Primary key id. Foreign keys: user_id → users(id) ON DELETE CASCADE. Unique: token_hash. Indexes: ux_password_reset_tokens_hash (token_hash) — serves the reset-link click.

export const passwordResetTokens = pgTable('password_reset_tokens', {
  id: id(),
  userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
  tokenHash: text('token_hash').notNull(),
  expiresAt: timestamp('expires_at', { withTimezone: true }).notNull().default(sql`now() + interval '1 hour'`),
  consumedAt: timestamp('consumed_at', { withTimezone: true }),
  requestedIp: inet('requested_ip'),
  createdAt: createdAt(),
}, (table) => [
  uniqueIndex('ux_password_reset_tokens_hash').on(table.tokenHash),
]);

5.3 Workspaces & Teams #

5.3.1 workspaces #

A Team's shared billing and membership boundary. Owner: workspace (self). Delete policy: soft.

Primary key id. Foreign keys: owner_user_id → users(id) ON DELETE RESTRICT — ownership must be explicitly transferred before the owning user can be deleted, preventing an orphaned workspace; plan_id → plans(id) ON DELETE RESTRICT — a plan in active use cannot be removed from the catalogue. Unique: slug. Indexes: ux_workspaces_slug (slug) — serves URL routing; ix_workspaces_owner (owner_user_id).

export const workspaces = pgTable('workspaces', {
  id: id(),
  name: text('name').notNull(),
  slug: text('slug').notNull(),
  ownerUserId: uuid('owner_user_id').notNull().references(() => users.id, { onDelete: 'restrict' }),
  planId: uuid('plan_id').notNull().references(() => plans.id, { onDelete: 'restrict' }),
  mfaEnforced: boolean('mfa_enforced').notNull().default(false),
  euDataResidency: boolean('eu_data_residency').notNull().default(false),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
  deletedAt: deletedAt(),
}, (table) => [
  uniqueIndex('ux_workspaces_slug').on(table.slug),
  index('ix_workspaces_owner').on(table.ownerUserId),
]);

5.3.2 workspace_members #

Membership and role. Owner: workspace. Delete policy: hard.

No updated_at, no deleted_at — a role change is an update to role directly; removal is a row delete. Primary key id. Foreign keys: workspace_id → workspaces(id) ON DELETE CASCADE; user_id → users(id) ON DELETE CASCADE; invited_by → users(id) ON DELETE SET NULL — preserves the membership row even if the inviter's account is later deleted. Unique: (workspace_id, user_id). Indexes: ux_workspace_members_ws_user (workspace_id, user_id) — serves the authorization check on every workspace-scoped request (Section 5.13 #7); ix_workspace_members_user (user_id) — serves "list my workspaces".

export const workspaceMembers = pgTable('workspace_members', {
  id: id(),
  workspaceId: uuid('workspace_id').notNull().references(() => workspaces.id, { onDelete: 'cascade' }),
  userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
  role: text('role').notNull().default('member'),
  invitedBy: uuid('invited_by').references(() => users.id, { onDelete: 'set null' }),
  joinedAt: timestamp('joined_at', { withTimezone: true }).notNull().defaultNow(),
}, (table) => [
  uniqueIndex('ux_workspace_members_ws_user').on(table.workspaceId, table.userId),
  index('ix_workspace_members_user').on(table.userId),
  check('ck_workspace_members_role', sql`${table.role} in ('owner', 'admin', 'member')`),
]);

5.3.3 workspace_invitations #

A pending email invitation. Owner: workspace. Delete policy: hard.

Primary key id. Foreign keys: workspace_id → workspaces(id) ON DELETE CASCADE; invited_by → users(id) ON DELETE CASCADE — an invitation from a now-deleted account is meaningless and is withdrawn. Unique: token_hash; partial unique (workspace_id, lower(email)) WHERE status = 'pending' — at most one live invite per email per workspace, while historical accepted/revoked rows are kept. Check: ck_workspace_invitations_role: role IN ('owner','admin','member'). Indexes: ux_workspace_invitations_token (token_hash) — serves the accept-invite click; ux_workspace_invitations_ws_email_pending as above.

export const workspaceInvitations = pgTable('workspace_invitations', {
  id: id(),
  workspaceId: uuid('workspace_id').notNull().references(() => workspaces.id, { onDelete: 'cascade' }),
  email: text('email').notNull(),
  role: text('role').notNull().default('member'),
  invitedBy: uuid('invited_by').notNull().references(() => users.id, { onDelete: 'cascade' }),
  tokenHash: text('token_hash').notNull(),
  status: text('status').notNull().default('pending'),
  expiresAt: timestamp('expires_at', { withTimezone: true }).notNull().default(sql`now() + interval '7 days'`),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
}, (table) => [
  uniqueIndex('ux_workspace_invitations_token').on(table.tokenHash),
  uniqueIndex('ux_workspace_invitations_ws_email_pending')
    .on(table.workspaceId, sql`lower(${table.email})`)
    .where(sql`${table.status} = 'pending'`),
  check('ck_workspace_invitations_role', sql`${table.role} in ('owner', 'admin', 'member')`),
  check('ck_workspace_invitations_status', sql`${table.status} in ('pending', 'accepted', 'revoked', 'expired')`),
]);

Concurrent-invitation handling. The partial unique index ux_workspace_invitations_ws_email_pending means two admins inviting the same email to the same workspace at the same moment will have their INSERTs race: the first commits, and the second raises a PostgreSQL 23505 unique_violation against that index. The invite-creation handler catches exactly that constraint violation (matched by index name, not by a generic "any unique error" handler, so an unrelated collision on token_hash — cryptographically negligible but not impossible to code defensively against — is not silently swallowed) and, instead of surfacing a database error to the caller, re-selects the existing pending row for (workspace_id, lower(email)) and returns it with the same success shape the INSERT path would have produced. The invite is therefore idempotent under concurrency: the second admin's action always succeeds and always resolves to one single live invitation, and no duplicate email is ever sent. This is enforced in apps/api/src/routes/workspaces/invitations.ts and covered by rule 11 in Section 5.18.

5.3.4 guest_devices #

Anonymous per-device quota tracking for unauthenticated visitors. Owner: system. Delete policy: hard, 30 days of inactivity.

Primary key id. No foreign keys — guests are unauthenticated by definition. Unique: device_fingerprint_hash. Indexes: ux_guest_devices_fingerprint (device_fingerprint_hash) — serves the per-request quota check; ix_guest_devices_ip_window (ip_hash, task_window_date) — serves abuse detection across devices sharing an IP.

export const guestDevices = pgTable('guest_devices', {
  id: id(),
  deviceFingerprintHash: text('device_fingerprint_hash').notNull(),
  ipHash: text('ip_hash').notNull(),
  tasksToday: smallint('tasks_today').notNull().default(0),
  taskWindowDate: date('task_window_date').notNull().defaultNow(),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
}, (table) => [
  uniqueIndex('ux_guest_devices_fingerprint').on(table.deviceFingerprintHash),
  index('ix_guest_devices_ip_window').on(table.ipHash, table.taskWindowDate),
]);

5.4 Billing & Entitlements #

5.4.1 plans #

The catalogue of billing plans, mirroring Section 12.2. Owner: system. Delete policy: hard, admin-only, rare.

Primary key id. No foreign keys. Unique: key; stripe_price_id. Check: ck_plans_price_nonneg: price_cents >= 0; ck_plans_key: key IN (...); ck_plans_billing_interval: billing_interval IN ('month','year'). Indexes: ux_plans_key (key) — serves entitlement lookups by plan key throughout the codebase.

export const plans = pgTable('plans', {
  id: id(),
  key: text('key').notNull(),
  name: text('name').notNull(),
  priceCents: integer('price_cents').notNull().default(0),
  currency: text('currency').notNull().default('usd'),
  billingInterval: text('billing_interval').notNull().default('month'),
  maxFileSizeBytes: bigint('max_file_size_bytes', { mode: 'number' }).notNull(),
  dailyServerTaskCap: integer('daily_server_task_cap'),
  batchMaxFiles: integer('batch_max_files'),
  envelopeMonthlyCap: integer('envelope_monthly_cap'),
  jobHistoryDays: integer('job_history_days').notNull(),
  stripePriceId: text('stripe_price_id'),
  active: boolean('active').notNull().default(true),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
}, (table) => [
  uniqueIndex('ux_plans_key').on(table.key),
  uniqueIndex('ux_plans_stripe_price_id').on(table.stripePriceId),
  check('ck_plans_price_nonneg', sql`${table.priceCents} >= 0`),
  check('ck_plans_key', sql`${table.key} in ('guest', 'free', 'pro', 'team', 'api_starter', 'api_growth', 'api_scale')`),
  check('ck_plans_billing_interval', sql`${table.billingInterval} in ('month', 'year')`),
]);

5.4.2 subscriptions #

A user's or workspace's active Stripe subscription. Owner: user or workspace (exactly one). Delete policy: none — status-driven.

Primary key id. Foreign keys: workspace_id → workspaces(id) ON DELETE CASCADE; user_id → users(id) ON DELETE CASCADE; plan_id → plans(id) ON DELETE RESTRICT. Unique: stripe_subscription_id. Check: ck_subscriptions_owner_xor: num_nonnulls(workspace_id, user_id) = 1 — a subscription belongs to exactly one owner kind, never both, never neither. Indexes: ux_subscriptions_stripe_id (stripe_subscription_id) — serves Stripe webhook resolution; ux_subscriptions_workspace (workspace_id) WHERE workspace_id IS NOT NULL; ux_subscriptions_user (user_id) WHERE user_id IS NOT NULL — both serve the entitlement lookup on every quota check (Section 5.13 #5).

export const subscriptions = pgTable('subscriptions', {
  id: id(),
  workspaceId: uuid('workspace_id').references(() => workspaces.id, { onDelete: 'cascade' }),
  userId: uuid('user_id').references(() => users.id, { onDelete: 'cascade' }),
  planId: uuid('plan_id').notNull().references(() => plans.id, { onDelete: 'restrict' }),
  stripeSubscriptionId: text('stripe_subscription_id').notNull(),
  status: text('status').notNull(),
  currentPeriodStart: timestamp('current_period_start', { withTimezone: true }).notNull(),
  currentPeriodEnd: timestamp('current_period_end', { withTimezone: true }).notNull(),
  cancelAtPeriodEnd: boolean('cancel_at_period_end').notNull().default(false),
  canceledAt: timestamp('canceled_at', { withTimezone: true }),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
}, (table) => [
  uniqueIndex('ux_subscriptions_stripe_id').on(table.stripeSubscriptionId),
  uniqueIndex('ux_subscriptions_workspace').on(table.workspaceId).where(sql`${table.workspaceId} is not null`),
  uniqueIndex('ux_subscriptions_user').on(table.userId).where(sql`${table.userId} is not null`),
  check('ck_subscriptions_owner_xor', sql`num_nonnulls(${table.workspaceId}, ${table.userId}) = 1`),
  check('ck_subscriptions_status', sql`${table.status} in ('trialing', 'active', 'past_due', 'canceled', 'incomplete', 'incomplete_expired', 'unpaid')`),
]);

5.4.3 subscription_items #

A line item on a subscription. Owner: follows the parent subscription. Delete policy: cascades with parent.

Primary key id. Foreign keys: subscription_id → subscriptions(id) ON DELETE CASCADE. Unique: stripe_subscription_item_id. Indexes: ix_subscription_items_subscription (subscription_id).

export const subscriptionItems = pgTable('subscription_items', {
  id: id(),
  subscriptionId: uuid('subscription_id').notNull().references(() => subscriptions.id, { onDelete: 'cascade' }),
  stripeSubscriptionItemId: text('stripe_subscription_item_id').notNull(),
  stripePriceId: text('stripe_price_id').notNull(),
  kind: text('kind').notNull(),
  quantity: integer('quantity').notNull().default(1),
  unitAmountCents: integer('unit_amount_cents'),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
}, (table) => [
  uniqueIndex('ux_subscription_items_stripe_id').on(table.stripeSubscriptionItemId),
  index('ix_subscription_items_subscription').on(table.subscriptionId),
  check('ck_subscription_items_kind', sql`${table.kind} in ('base', 'seat', 'metered_operations', 'metered_ocr_pages')`),
]);

5.4.4 usage_records #

One billable/metered event. Owner: user or workspace. Delete policy: hard, via partition drop (Section 5.14). Partitioned by month on occurred_at.

No updated_at — usage events are immutable once written. Primary key (id, occurred_at), declared as a composite primaryKey() in the table definition below — PostgreSQL requires a declaratively partitioned table's partition key to be part of every primary key and unique constraint, so a bare id primary key would make the defining migration fail the moment PARTITION BY RANGE (occurred_at) is applied. No other table holds a foreign key against usage_records.id, so the composite has no downstream foreign-key consequence; every join onto this table's data (e.g., job_id) instead goes outward, from this table to its parents. Foreign keys: workspace_id → workspaces(id) ON DELETE CASCADE; user_id → users(id) ON DELETE CASCADE; api_key_id → api_keys(id) ON DELETE SET NULL — usage history survives key revocation; job_id → jobs(id) ON DELETE SET NULL. Indexes: ix_usage_records_workspace_time (workspace_id, occurred_at), ix_usage_records_user_time (user_id, occurred_at), ix_usage_records_api_key_time (api_key_id, occurred_at) — all three serve billing-period aggregation queries.

export const usageRecords = pgTable('usage_records', {
  id: uuid('id').notNull(),
  workspaceId: uuid('workspace_id').references(() => workspaces.id, { onDelete: 'cascade' }),
  userId: uuid('user_id').references(() => users.id, { onDelete: 'cascade' }),
  apiKeyId: uuid('api_key_id').references(() => apiKeys.id, { onDelete: 'set null' }),
  jobId: uuid('job_id').references(() => jobs.id, { onDelete: 'set null' }),
  metric: text('metric').notNull(),
  quantity: integer('quantity').notNull().default(1),
  occurredAt: timestamp('occurred_at', { withTimezone: true }).notNull().defaultNow(),
  stripeMeterEventId: text('stripe_meter_event_id'),
  createdAt: createdAt(),
}, (table) => [
  primaryKey({ columns: [table.id, table.occurredAt] }),
  index('ix_usage_records_workspace_time').on(table.workspaceId, table.occurredAt),
  index('ix_usage_records_user_time').on(table.userId, table.occurredAt),
  index('ix_usage_records_api_key_time').on(table.apiKeyId, table.occurredAt),
  check('ck_usage_records_metric', sql`${table.metric} in ('operation', 'ocr_page', 'envelope_sent')`),
]);
// Declared PARTITION BY RANGE (occurred_at) in the migration SQL; Drizzle's schema builder
// models the logical column set, and partition DDL is hand-written in the migration file
// per Section 5.16 — drizzle-kit does not generate partition clauses.

5.4.5 usage_daily_rollups #

Daily aggregate usage per owner and metric, the table entitlement checks actually read (Section 5.13 #5) so the hot path never scans raw usage_records. Owner: user or workspace. Delete policy: hard, periodic purge.

No deleted_at. Primary key id. No foreign keys (polymorphic owner, see above). Unique: (owner_type, owner_id, metric, usage_date). Indexes: ux_usage_daily_rollups_owner_metric_date as above — serves both the upsert and the entitlement read.

export const usageDailyRollups = pgTable('usage_daily_rollups', {
  id: id(),
  ownerType: text('owner_type').notNull(),
  ownerId: uuid('owner_id').notNull(),
  metric: text('metric').notNull(),
  usageDate: date('usage_date').notNull(),
  quantity: integer('quantity').notNull().default(0),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
}, (table) => [
  uniqueIndex('ux_usage_daily_rollups_owner_metric_date').on(table.ownerType, table.ownerId, table.metric, table.usageDate),
  check('ck_usage_daily_rollups_owner_type', sql`${table.ownerType} in ('user', 'workspace')`),
  check('ck_usage_daily_rollups_metric', sql`${table.metric} in ('operation', 'ocr_page', 'envelope_sent', 'server_task')`),
]);

5.4.6 spend_caps #

An optional per-API-key monthly spend ceiling. Owner: follows the parent key. Delete policy: cascades with key.

Primary key id. Foreign keys: api_key_id → api_keys(id) ON DELETE CASCADE. Unique: api_key_id — at most one cap row per key. Check: ck_spend_caps_cap_positive: cap_cents > 0. Indexes: ux_spend_caps_api_key (api_key_id) — serves the pre-request spend check (Section 5.13 #11).

export const spendCaps = pgTable('spend_caps', {
  id: id(),
  apiKeyId: uuid('api_key_id').notNull().references(() => apiKeys.id, { onDelete: 'cascade' }),
  capCents: integer('cap_cents').notNull(),
  period: text('period').notNull().default('month'),
  currentPeriodSpendCents: integer('current_period_spend_cents').notNull().default(0),
  enabled: boolean('enabled').notNull().default(false),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
}, (table) => [
  uniqueIndex('ux_spend_caps_api_key').on(table.apiKeyId),
  check('ck_spend_caps_cap_positive', sql`${table.capCents} > 0`),
  check('ck_spend_caps_period', sql`${table.period} = 'month'`),
]);

5.4.7 invoices #

A read-model mirror of Stripe invoices — never written by application billing logic, only synced from Stripe webhook events. Owner: user or workspace. Delete policy: none.

Primary key id. Foreign keys: workspace_id → workspaces(id) ON DELETE CASCADE; user_id → users(id) ON DELETE CASCADE. Unique: stripe_invoice_id. Check: ck_invoices_owner_xor: num_nonnulls(workspace_id, user_id) = 1. Indexes: ux_invoices_stripe_id (stripe_invoice_id) — serves webhook upsert; ix_invoices_workspace (workspace_id, created_at DESC), ix_invoices_user (user_id, created_at DESC) — serve the billing-history page.

export const invoices = pgTable('invoices', {
  id: id(),
  workspaceId: uuid('workspace_id').references(() => workspaces.id, { onDelete: 'cascade' }),
  userId: uuid('user_id').references(() => users.id, { onDelete: 'cascade' }),
  stripeInvoiceId: text('stripe_invoice_id').notNull(),
  status: text('status').notNull(),
  amountDueCents: integer('amount_due_cents').notNull(),
  amountPaidCents: integer('amount_paid_cents').notNull().default(0),
  currency: text('currency').notNull().default('usd'),
  hostedInvoiceUrl: text('hosted_invoice_url'),
  invoicePdfUrl: text('invoice_pdf_url'),
  periodStart: timestamp('period_start', { withTimezone: true }),
  periodEnd: timestamp('period_end', { withTimezone: true }),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
}, (table) => [
  uniqueIndex('ux_invoices_stripe_id').on(table.stripeInvoiceId),
  index('ix_invoices_workspace').on(table.workspaceId, table.createdAt),
  index('ix_invoices_user').on(table.userId, table.createdAt),
  check('ck_invoices_owner_xor', sql`num_nonnulls(${table.workspaceId}, ${table.userId}) = 1`),
  check('ck_invoices_status', sql`${table.status} in ('draft', 'open', 'paid', 'uncollectible', 'void')`),
]);

5.5 Documents & Storage #

5.5.1 documents #

Server-side file metadata only — file bytes are never stored in PostgreSQL. Owner: user (+ optional workspace). Delete policy: soft.

Primary key id. Foreign keys: owner_user_id → users(id) ON DELETE CASCADE; workspace_id → workspaces(id) ON DELETE SET NULL — a workspace deletion demotes the document to personal rather than orphaning it; job_id → jobs(id) ON DELETE SET NULL. Check: ck_documents_size_positive: size_bytes > 0; ck_documents_mime_type (Section 5.11 list); ck_documents_status. Indexes: ix_documents_owner_created (owner_user_id, created_at DESC) WHERE deleted_at IS NULL — serves the "My Files" list (Section 5.13 #2); ix_documents_workspace (workspace_id) WHERE deleted_at IS NULL.

export const documents = pgTable('documents', {
  id: id(),
  ownerUserId: uuid('owner_user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
  workspaceId: uuid('workspace_id').references(() => workspaces.id, { onDelete: 'set null' }),
  jobId: uuid('job_id').references(() => jobs.id, { onDelete: 'set null' }),
  filename: text('filename').notNull(),
  mimeType: text('mime_type').notNull(),
  pageCount: integer('page_count'),
  sizeBytes: bigint('size_bytes', { mode: 'number' }).notNull(),
  sha256: text('sha256').notNull(),
  status: text('status').notNull().default('active'),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
  deletedAt: deletedAt(),
}, (table) => [
  index('ix_documents_owner_created').on(table.ownerUserId, table.createdAt).where(sql`${table.deletedAt} is null`),
  index('ix_documents_workspace').on(table.workspaceId).where(sql`${table.deletedAt} is null`),
  check('ck_documents_size_positive', sql`${table.sizeBytes} > 0`),
  check('ck_documents_status', sql`${table.status} in ('active', 'processing', 'expired', 'deleted')`),
]);

5.5.2 document_blobs #

The encrypted object-storage pointer. Owner: follows the parent document. Delete policy: hard, never soft — this is the row whose deletion cryptographically shreds the underlying bytes (Section 5.15).

No updated_at, no deleted_at — the row is deleted outright. Primary key id. Foreign keys: document_id → documents(id) ON DELETE CASCADE. Unique: storage_key. Indexes: ux_document_blobs_storage_key (storage_key); ix_document_blobs_expires_at (expires_at) — serves the janitor sweep (Section 5.13 #12, Section 5.15).

export const documentBlobs = pgTable('document_blobs', {
  id: id(),
  documentId: uuid('document_id').notNull().references(() => documents.id, { onDelete: 'cascade' }),
  storageKey: text('storage_key').notNull(),
  storageBucket: text('storage_bucket').notNull(),
  wrappedDataKey: bytea('wrapped_data_key').notNull(),
  kmsKeyId: text('kms_key_id').notNull(),
  sizeBytes: bigint('size_bytes', { mode: 'number' }).notNull(),
  checksumSha256: text('checksum_sha256').notNull(),
  expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
  createdAt: createdAt(),
}, (table) => [
  uniqueIndex('ux_document_blobs_storage_key').on(table.storageKey),
  index('ix_document_blobs_expires_at').on(table.expiresAt),
]);

5.6 Jobs & Batch Processing #

5.6.1 jobs #

One asynchronous or synchronous processing operation, client-side or server-side. Owner: user (+ optional workspace). Delete policy: none — visibility windowed by plan, never physically deleted.

Primary key id. Foreign keys: owner_user_id → users(id) ON DELETE CASCADE; workspace_id → workspaces(id) ON DELETE SET NULL; api_key_id → api_keys(id) ON DELETE SET NULL; batch_job_id → batch_jobs(id) ON DELETE CASCADE; input_document_id → documents(id) ON DELETE SET NULL; output_document_id → documents(id) ON DELETE SET NULL — a job row must survive its documents' eventual purge, since job history outlives file retention. Check: ck_jobs_progress: progress BETWEEN 0 AND 100; ck_jobs_state, ck_jobs_execution_location, ck_jobs_priority_lane. Indexes: ix_jobs_owner_created (owner_user_id, created_at DESC) — serves job history (Section 5.13 #4); ix_jobs_state_queue (state, queue) WHERE state IN ('queued','running') — serves worker/dashboard polling; ix_jobs_batch (batch_job_id) WHERE batch_job_id IS NOT NULL; ix_jobs_id_poll (id) (the primary key itself, called out because client-side status polling — Section 5.13 #3 — is the single highest-volume read against this table).

export const jobs = pgTable('jobs', {
  id: id(),
  ownerUserId: uuid('owner_user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
  workspaceId: uuid('workspace_id').references(() => workspaces.id, { onDelete: 'set null' }),
  apiKeyId: uuid('api_key_id').references(() => apiKeys.id, { onDelete: 'set null' }),
  batchJobId: uuid('batch_job_id').references(() => batchJobs.id, { onDelete: 'cascade' }),
  tool: text('tool').notNull(),
  executionLocation: text('execution_location').notNull(),
  queue: text('queue'),
  priorityLane: text('priority_lane').notNull().default('standard'),
  state: text('state').notNull().default('queued'),
  progress: smallint('progress').notNull().default(0),
  stage: text('stage'),
  inputDocumentId: uuid('input_document_id').references(() => documents.id, { onDelete: 'set null' }),
  outputDocumentId: uuid('output_document_id').references(() => documents.id, { onDelete: 'set null' }),
  errorCode: text('error_code'),
  errorMessage: text('error_message'),
  deterministicTimestamp: timestamp('deterministic_timestamp', { withTimezone: true }),
  startedAt: timestamp('started_at', { withTimezone: true }),
  finishedAt: timestamp('finished_at', { withTimezone: true }),
  expiresAt: timestamp('expires_at', { withTimezone: true }),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
}, (table) => [
  index('ix_jobs_owner_created').on(table.ownerUserId, table.createdAt),
  index('ix_jobs_state_queue').on(table.state, table.queue).where(sql`${table.state} in ('queued', 'running')`),
  index('ix_jobs_batch').on(table.batchJobId).where(sql`${table.batchJobId} is not null`),
  check('ck_jobs_progress', sql`${table.progress} between 0 and 100`),
  check('ck_jobs_state', sql`${table.state} in ('queued', 'running', 'succeeded', 'failed', 'canceled', 'expired')`),
  check('ck_jobs_execution_location', sql`${table.executionLocation} in ('client', 'server')`),
  check('ck_jobs_priority_lane', sql`${table.priorityLane} in ('standard', 'priority')`),
]);

5.6.2 job_events #

Progress/state transition log for a job. Owner: follows the parent job. Delete policy: hard, partition drop. Partitioned by month on occurred_at.

Primary key (id, occurred_at), declared as a composite primaryKey() below — PostgreSQL requires the partition key to be part of every primary key on a declaratively partitioned table, so a bare id primary key would make the defining PARTITION BY RANGE (occurred_at) migration fail. No other table holds a foreign key against job_events.id, so the composite has no downstream foreign-key consequence. Foreign keys: job_id → jobs(id) ON DELETE CASCADE. Indexes: ix_job_events_job_occurred (job_id, occurred_at) — serves the job-detail event timeline and SSE backfill.

export const jobEvents = pgTable('job_events', {
  id: uuid('id').notNull(),
  jobId: uuid('job_id').notNull().references(() => jobs.id, { onDelete: 'cascade' }),
  eventType: text('event_type').notNull(),
  progress: smallint('progress'),
  message: text('message'),
  occurredAt: timestamp('occurred_at', { withTimezone: true }).notNull().defaultNow(),
  createdAt: createdAt(),
}, (table) => [
  primaryKey({ columns: [table.id, table.occurredAt] }),
  index('ix_job_events_job_occurred').on(table.jobId, table.occurredAt),
  check('ck_job_events_event_type', sql`${table.eventType} in ('queued', 'started', 'progress', 'succeeded', 'failed', 'canceled', 'expired', 'retried')`),
]);

5.6.3 job_artifacts #

A non-primary output of a job: a log, a redaction report, a preview thumbnail. Owner: follows the parent job. Delete policy: hard, with the job's blob purge.

Primary key id. Foreign keys: job_id → jobs(id) ON DELETE CASCADE; document_id → documents(id) ON DELETE SET NULL. Indexes: ix_job_artifacts_job (job_id).

export const jobArtifacts = pgTable('job_artifacts', {
  id: id(),
  jobId: uuid('job_id').notNull().references(() => jobs.id, { onDelete: 'cascade' }),
  documentId: uuid('document_id').references(() => documents.id, { onDelete: 'set null' }),
  kind: text('kind').notNull(),
  storageKey: text('storage_key'),
  createdAt: createdAt(),
}, (table) => [
  index('ix_job_artifacts_job').on(table.jobId),
  check('ck_job_artifacts_kind', sql`${table.kind} in ('output_document', 'log', 'redaction_report', 'preview_thumbnail')`),
]);

5.6.4 batch_jobs #

A batch of many single-tool jobs. Owner: user (+ optional workspace). Delete policy: none, visibility windowed.

Primary key id. Foreign keys: owner_user_id → users(id) ON DELETE CASCADE; workspace_id → workspaces(id) ON DELETE SET NULL; api_key_id → api_keys(id) ON DELETE SET NULL. Check: ck_batch_jobs_total_positive: total_items > 0. Indexes: ix_batch_jobs_owner_created (owner_user_id, created_at DESC).

export const batchJobs = pgTable('batch_jobs', {
  id: id(),
  ownerUserId: uuid('owner_user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
  workspaceId: uuid('workspace_id').references(() => workspaces.id, { onDelete: 'set null' }),
  apiKeyId: uuid('api_key_id').references(() => apiKeys.id, { onDelete: 'set null' }),
  tool: text('tool').notNull(),
  state: text('state').notNull().default('queued'),
  totalItems: integer('total_items').notNull(),
  completedItems: integer('completed_items').notNull().default(0),
  failedItems: integer('failed_items').notNull().default(0),
  finishedAt: timestamp('finished_at', { withTimezone: true }),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
}, (table) => [
  index('ix_batch_jobs_owner_created').on(table.ownerUserId, table.createdAt),
  check('ck_batch_jobs_total_positive', sql`${table.totalItems} > 0`),
]);

5.6.5 batch_job_items #

One item within a batch. Owner: follows the parent batch. Delete policy: none, visibility windowed.

Primary key id. Foreign keys: batch_job_id → batch_jobs(id) ON DELETE CASCADE; job_id → jobs(id) ON DELETE SET NULL. Unique: (batch_job_id, sequence). Indexes: ux_batch_job_items_batch_seq (batch_job_id, sequence) — serves ordered item listing.

export const batchJobItems = pgTable('batch_job_items', {
  id: id(),
  batchJobId: uuid('batch_job_id').notNull().references(() => batchJobs.id, { onDelete: 'cascade' }),
  jobId: uuid('job_id').references(() => jobs.id, { onDelete: 'set null' }),
  sequence: smallint('sequence').notNull(),
  state: text('state').notNull().default('queued'),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
}, (table) => [
  uniqueIndex('ux_batch_job_items_batch_seq').on(table.batchJobId, table.sequence),
]);

5.7 API Access & Webhooks #

5.7.1 api_keys #

A public API credential. Owner: user or workspace (exactly one). Delete policy: soft.

Primary key id. Foreign keys: workspace_id → workspaces(id) ON DELETE CASCADE; owner_user_id → users(id) ON DELETE CASCADE. Unique: key_hash. Check: ck_api_keys_owner_xor: num_nonnulls(workspace_id, owner_user_id) = 1; ck_api_keys_prefix; ck_api_keys_environment. Indexes: ux_api_keys_key_hash (key_hash) — serves the auth check on every public API request (Section 5.13 #6, the single highest-frequency query against this table).

export const apiKeys = pgTable('api_keys', {
  id: id(),
  workspaceId: uuid('workspace_id').references(() => workspaces.id, { onDelete: 'cascade' }),
  ownerUserId: uuid('owner_user_id').references(() => users.id, { onDelete: 'cascade' }),
  name: text('name').notNull(),
  keyPrefix: text('key_prefix').notNull(),
  keyHash: text('key_hash').notNull(),
  lastFour: text('last_four').notNull(),
  environment: text('environment').notNull(),
  lastUsedAt: timestamp('last_used_at', { withTimezone: true }),
  revokedAt: timestamp('revoked_at', { withTimezone: true }),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
  deletedAt: deletedAt(),
}, (table) => [
  uniqueIndex('ux_api_keys_key_hash').on(table.keyHash),
  check('ck_api_keys_owner_xor', sql`num_nonnulls(${table.workspaceId}, ${table.ownerUserId}) = 1`),
  check('ck_api_keys_prefix', sql`${table.keyPrefix} in ('pk_live_', 'pk_test_')`),
  check('ck_api_keys_environment', sql`${table.environment} in ('live', 'test')`),
]);

5.7.2 api_key_scopes #

A permission scope granted to a key. Owner: follows the parent key. Delete policy: cascades with key.

No updated_at. Primary key id. Foreign keys: api_key_id → api_keys(id) ON DELETE CASCADE. Unique: (api_key_id, scope). Indexes: ix_api_key_scopes_key (api_key_id) — serves the per-request scope check, read alongside the key-hash lookup.

export const apiKeyScopes = pgTable('api_key_scopes', {
  id: id(),
  apiKeyId: uuid('api_key_id').notNull().references(() => apiKeys.id, { onDelete: 'cascade' }),
  scope: text('scope').notNull(),
  createdAt: createdAt(),
}, (table) => [
  uniqueIndex('ux_api_key_scopes_key_scope').on(table.apiKeyId, table.scope),
  check('ck_api_key_scopes_scope', sql`${table.scope} in ('documents:read', 'documents:write', 'jobs:read', 'jobs:write', 'envelopes:read', 'envelopes:write', 'webhooks:manage')`),
]);

5.7.3 api_key_ip_rules #

A CIDR allowlist entry for a key. Owner: follows the parent key. Delete policy: cascades with key.

No updated_at. Primary key id. Foreign keys: api_key_id → api_keys(id) ON DELETE CASCADE. Unique: (api_key_id, cidr). Indexes: ix_api_key_ip_rules_key (api_key_id).

export const apiKeyIpRules = pgTable('api_key_ip_rules', {
  id: id(),
  apiKeyId: uuid('api_key_id').notNull().references(() => apiKeys.id, { onDelete: 'cascade' }),
  cidr: cidr('cidr').notNull(),
  createdAt: createdAt(),
}, (table) => [
  uniqueIndex('ux_api_key_ip_rules_key_cidr').on(table.apiKeyId, table.cidr),
]);

5.7.4 webhook_endpoints #

A customer-configured webhook target. Owner: user or workspace. Delete policy: soft.

Primary key id. Foreign keys: workspace_id → workspaces(id) ON DELETE CASCADE; owner_user_id → users(id) ON DELETE CASCADE. Check: ck_webhook_endpoints_owner_xor: num_nonnulls(workspace_id, owner_user_id) = 1. Indexes: ix_webhook_endpoints_workspace (workspace_id) WHERE deleted_at IS NULL; ix_webhook_endpoints_user (owner_user_id) WHERE deleted_at IS NULL.

The status state machine. active is the only state in which nothing unusual is happening; failing and disabled both mean the endpoint has a delivery problem, at increasing severity:

• active → failing: the moment consecutive_failures reaches 3 as a delivery attempt's terminal failure is recorded (Section 14.10). The transition and the failure-recording write happen in the same database transaction, so consecutive_failures and status can never disagree.
• While failing: deliveries are not paused — every subscribed event continues to be attempted on the normal retry schedule (Section 14.10.6) exactly as it would from active. The one behavioral difference is notification: at the instant of the active → failing transition, and again once every 24 hours for as long as the endpoint remains failing, a transactional email is sent to the workspace owner (or, for a personal key, the owning user) identifying the endpoint URL and the most recent failure's HTTP status/error. This is the only owner-facing signal that a webhook is unhealthy short of the endpoint's own monitoring.
• failing → disabled: the moment consecutive_failures reaches 10, OR the endpoint has been continuously failing for 14 days without a single successful delivery, whichever comes first. Once disabled, delivery attempts stop entirely — no further retries are scheduled for events that arrive while the endpoint is disabled, and webhook_deliveries rows are still written for observability but immediately marked exhausted rather than pending.
• failing → active: any single successful delivery (an HTTP 2xx response recorded against any attempt) resets consecutive_failures to 0 and moves status back to active immediately. No manual action is required.
• disabled → active: requires an explicit action by the endpoint's owner — re-saving the endpoint (even with no field changes) in the dashboard or via PATCH /v1/webhook-endpoints/{id} (Section 14.10). Reactivation resets consecutive_failures to 0, sets status to active, and delivery resumes for events emitted from that point forward; events that arrived while disabled are not retroactively delivered.

Every transition above is applied by the same delivery-attempt handler that writes the corresponding webhook_deliveries row, inside one transaction, so webhook_endpoints.status/consecutive_failures and the delivery log can never drift apart.

export const webhookEndpoints = pgTable('webhook_endpoints', {
  id: id(),
  workspaceId: uuid('workspace_id').references(() => workspaces.id, { onDelete: 'cascade' }),
  ownerUserId: uuid('owner_user_id').references(() => users.id, { onDelete: 'cascade' }),
  url: text('url').notNull(),
  description: text('description'),
  secretCiphertext: bytea('secret_ciphertext').notNull(),
  secretKeyId: text('secret_key_id').notNull(),
  previousSecretCiphertext: bytea('previous_secret_ciphertext'),
  previousSecretExpiresAt: timestamp('previous_secret_expires_at', { withTimezone: true }),
  subscribedEvents: text('subscribed_events').array().notNull().default(sql`'{}'::text[]`),
  status: text('status').notNull().default('active'),
  consecutiveFailures: smallint('consecutive_failures').notNull().default(0),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
  deletedAt: deletedAt(),
}, (table) => [
  index('ix_webhook_endpoints_workspace').on(table.workspaceId).where(sql`${table.deletedAt} is null`),
  index('ix_webhook_endpoints_user').on(table.ownerUserId).where(sql`${table.deletedAt} is null`),
  check('ck_webhook_endpoints_owner_xor', sql`num_nonnulls(${table.workspaceId}, ${table.ownerUserId}) = 1`),
  check('ck_webhook_endpoints_status', sql`${table.status} in ('active', 'disabled', 'failing')`),
]);

5.7.5 webhook_deliveries #

One delivery attempt of one event to one endpoint. Owner: follows the parent endpoint. Delete policy: hard, partition drop. Partitioned by month on created_at.

No updated_at (status changes are appended as new attempt rows, not mutated in place, except the terminal status/delivered_at/response_* update on the current attempt). Primary key (id, created_at), declared as a composite primaryKey() below — PostgreSQL requires the partition key to be part of every primary key on a declaratively partitioned table, so a bare id primary key would make the defining PARTITION BY RANGE (created_at) migration fail. No other table holds a foreign key against webhook_deliveries.id, so the composite has no downstream foreign-key consequence. Foreign keys: webhook_endpoint_id → webhook_endpoints(id) ON DELETE CASCADE. Indexes: ix_webhook_deliveries_endpoint_created (webhook_endpoint_id, created_at DESC) — serves the delivery-log UI; ix_webhook_deliveries_retry (status, next_retry_at) WHERE status = 'pending' — serves the retry worker (Section 5.13 #10).

export const webhookDeliveries = pgTable('webhook_deliveries', {
  id: uuid('id').notNull(),
  webhookEndpointId: uuid('webhook_endpoint_id').notNull().references(() => webhookEndpoints.id, { onDelete: 'cascade' }),
  eventType: text('event_type').notNull(),
  payload: jsonb('payload').notNull(),
  attempt: smallint('attempt').notNull().default(1),
  status: text('status').notNull().default('pending'),
  responseStatusCode: smallint('response_status_code'),
  responseBodyExcerpt: text('response_body_excerpt'),
  nextRetryAt: timestamp('next_retry_at', { withTimezone: true }),
  deliveredAt: timestamp('delivered_at', { withTimezone: true }),
  createdAt: createdAt(),
}, (table) => [
  primaryKey({ columns: [table.id, table.createdAt] }),
  index('ix_webhook_deliveries_endpoint_created').on(table.webhookEndpointId, table.createdAt),
  index('ix_webhook_deliveries_retry').on(table.status, table.nextRetryAt).where(sql`${table.status} = 'pending'`),
  check('ck_webhook_deliveries_status', sql`${table.status} in ('pending', 'delivered', 'failed', 'exhausted')`),
]);

5.8 E-Signature #

5.8.1 envelopes #

An e-signature request (Section 10). Owner: user (+ optional workspace). Delete policy: soft.

Primary key id. Foreign keys: owner_user_id → users(id) ON DELETE CASCADE; workspace_id → workspaces(id) ON DELETE SET NULL. Check: ck_envelopes_status; ck_envelopes_routing; ck_envelopes_expiry_max: expires_at <= created_at + interval '30 days' — enforces the hard 30-day ceiling from Section 6 at the database layer, not just in application code. Indexes: ix_envelopes_owner_created (owner_user_id, created_at DESC); ix_envelopes_workspace (workspace_id) WHERE deleted_at IS NULL.

export const envelopes = pgTable('envelopes', {
  id: id(),
  ownerUserId: uuid('owner_user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
  workspaceId: uuid('workspace_id').references(() => workspaces.id, { onDelete: 'set null' }),
  title: text('title').notNull(),
  status: text('status').notNull().default('draft'),
  routing: text('routing').notNull().default('sequential'),
  expiresAt: timestamp('expires_at', { withTimezone: true }).notNull().default(sql`now() + interval '14 days'`),
  reminderCadenceDays: smallint('reminder_cadence_days').array().notNull().default(sql`'{3,7,12}'::smallint[]`),
  completedAt: timestamp('completed_at', { withTimezone: true }),
  voidedAt: timestamp('voided_at', { withTimezone: true }),
  voidReason: text('void_reason'),
  finalDocumentHash: text('final_document_hash'),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
  deletedAt: deletedAt(),
}, (table) => [
  index('ix_envelopes_owner_created').on(table.ownerUserId, table.createdAt),
  index('ix_envelopes_workspace').on(table.workspaceId).where(sql`${table.deletedAt} is null`),
  check('ck_envelopes_status', sql`${table.status} in ('draft', 'sent', 'in_progress', 'completed', 'voided', 'expired', 'declined')`),
  check('ck_envelopes_routing', sql`${table.routing} in ('sequential', 'parallel')`),
  check('ck_envelopes_expiry_max', sql`${table.expiresAt} <= ${table.createdAt} + interval '30 days'`),
]);

5.8.2 envelope_documents #

A document attached to an envelope. Owner: follows the parent envelope. Delete policy: cascades with envelope.

No updated_at. Primary key id. Foreign keys: envelope_id → envelopes(id) ON DELETE CASCADE; document_id → documents(id) ON DELETE RESTRICT — a document referenced by a live envelope cannot be independently deleted; the envelope must be voided or completed first, which releases the reference through the normal blob-retention path. Unique: (envelope_id, sequence). Indexes: ix_envelope_documents_envelope (envelope_id).

export const envelopeDocuments = pgTable('envelope_documents', {
  id: id(),
  envelopeId: uuid('envelope_id').notNull().references(() => envelopes.id, { onDelete: 'cascade' }),
  documentId: uuid('document_id').notNull().references(() => documents.id, { onDelete: 'restrict' }),
  sequence: smallint('sequence').notNull().default(1),
  createdAt: createdAt(),
}, (table) => [
  uniqueIndex('ux_envelope_documents_envelope_seq').on(table.envelopeId, table.sequence),
]);

5.8.3 envelope_signers #

A signer, approver, or CC recipient. Owner: follows the parent envelope. Delete policy: cascades with envelope.

Primary key id. Foreign keys: envelope_id → envelopes(id) ON DELETE CASCADE. Unique: access_token_hash. Check: ck_envelope_signers_role; ck_envelope_signers_status. Indexes: ux_envelope_signers_access_token (access_token_hash) — serves the unauthenticated signer-portal session lookup (Section 5.13 #8); ix_envelope_signers_envelope_order (envelope_id, routing_order) — serves sequential-routing progression checks.

export const envelopeSigners = pgTable('envelope_signers', {
  id: id(),
  envelopeId: uuid('envelope_id').notNull().references(() => envelopes.id, { onDelete: 'cascade' }),
  role: text('role').notNull(),
  routingOrder: smallint('routing_order').notNull().default(1),
  name: text('name').notNull(),
  email: text('email').notNull(),
  status: text('status').notNull().default('pending'),
  otpCodeHash: text('otp_code_hash'),
  otpVerifiedAt: timestamp('otp_verified_at', { withTimezone: true }),
  consentedAt: timestamp('consented_at', { withTimezone: true }),
  signedAt: timestamp('signed_at', { withTimezone: true }),
  declinedAt: timestamp('declined_at', { withTimezone: true }),
  declineReason: text('decline_reason'),
  accessTokenHash: text('access_token_hash').notNull(),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
}, (table) => [
  uniqueIndex('ux_envelope_signers_access_token').on(table.accessTokenHash),
  index('ix_envelope_signers_envelope_order').on(table.envelopeId, table.routingOrder),
  check('ck_envelope_signers_role', sql`${table.role} in ('signer', 'approver', 'cc')`),
  check('ck_envelope_signers_status', sql`${table.status} in ('pending', 'notified', 'viewed', 'consented', 'in_progress', 'signed', 'declined', 'bounced', 'delegated')`),
]);

5.8.4 envelope_fields #

A placed field: signature, initials, free text, checkbox, etc. Owner: follows the parent envelope. Delete policy: cascades with envelope.