# Quillmark eSign — Product Requirements (v7.0)

Quillmark eSign is a control panel for sending documents for electronic signature. A sender designs a workflow (recipients, document templates, placed fields), launches it as a transaction, and each recipient completes a signing ceremony through a personal link. A Mouse Lab page exercises pointer, scroll, hover and drag interactions.

**Problem.** Senders need to prepare multi-party signing packets accurately, with fields exactly where they were placed, and signers need a guided, tamper-resistant ceremony with a clear audit trail.

## Users
- **Sender (agent / administrator)** — Build a workflow, place fields on pages, send it and track progress, decline and void outcomes.
- **Signer** — Open a personal link, consent, adopt a signature, fill required fields and finish with confidence.
- **Approver** — Sign only after earlier signers in the routing order have signed.

## Goals
- A field is stored exactly where the sender placed it, in page point coordinates, at any zoom level.
- A workflow cannot be sent until every problem is fixed, and all problems are reported at once.
- Signing is consent-gated, ordered, single-use and fully audited.

## Sign-in and session (AUTH)

Cookie-based sign-in for the control panel with protected routes.

- **FR-AUTH-01** (Must) Anonymous visits to any control-panel page redirect to the sign-in page with the original path preserved; valid credentials open the dashboard.
  - Visiting the dashboard anonymously redirects to the sign-in page with ?next=/cp/dashboard and heading "Sign in to the eSign Control Panel"
  - After sign-in the dashboard heading is "eSign Control Panel" with "Welcome back, <name>."
  - The user menu shows the email and role and a "Sign Out" entry
- **FR-AUTH-02** (Must) Failed sign-ins show distinct messages for missing and wrong credentials and do not leave the sign-in page.
  - Empty fields: "Enter your username and password."
  - Wrong credentials: "Invalid username or password."
- **FR-AUTH-03** (Should) After sign-in the user lands on the page originally requested; signing out protects the pages again.
  - A deep link to Transactions returns to Transactions after sign-in
  - After Sign Out the same link redirects to sign-in again

## Dashboard (DSH)

Counters, recent activity and shortcuts to start a workflow.

- **FR-DSH-01** (Must) The dashboard shows five counters (Drafts, Out for Signature, Completed, Declined, Voided) that equal the number of workflows in each status, plus recent activity.
  - A fresh session shows Drafts 1, Out for Signature 1, Completed 1, Declined 0, Voided 0
  - Recent activity lists "Vendor agreement — Okafor" (Draft), "Beneficiary change — Tanaka" (Out for Signature) and "Brokerage onboarding — Rivera" (Completed)
  - Clicking the Out for Signature counter opens Transactions filtered to that status
- **FR-DSH-02** (Should) "Start a workflow" offers four types, each with a description; choosing one creates a draft and opens its setup.
  - Types: Send for Signature, Sign & Send, In-Person Signing, Sign Only
  - Choosing Send for Signature opens "Workflow Setup WF-0004" with one empty Signer row and the Drafts counter becomes 2

## Workflows (WFL)

List, create, edit lock and delete workflows.

- **FR-WFL-01** (Should) The Workflows table lists every workflow and supports text search, status filter and sorting by column.
  - A fresh session lists 3 rows; the draft offers Edit and Delete, the others View only
  - Searching "tanaka" leaves only "Beneficiary change — Tanaka"
  - A filter with no matches shows "No workflows match your filters."
  - Clicking the Name header twice sorts ascending then descending and flips the arrow
- **FR-WFL-02** (Could) "+ New Workflow" replaces itself with a type chooser "What would you like to do?" that can be closed; the Workflow Designer menu entry opens it directly.
  - The close (×) control restores the button
  - Workflow Designer > New Workflow opens the page with the chooser already open
- **FR-WFL-03** (Should) Only drafts can be deleted, and only after confirmation.
  - Dialog "Delete workflow?" states the workflow and its task placements will be permanently removed
  - Cancel keeps the row; confirming removes it and lowers the Drafts counter
- **FR-WFL-04** (Must) Workflows that are no longer drafts are locked: they cannot be edited or deleted in the UI or through the API.
  - Opening a sent workflow redirects to its transaction details
  - Editing a sent workflow returns 409 "Workflow is Out for Signature; only drafts can be edited"
  - Deleting one returns 409 "Only drafts can be deleted — void the transaction instead"
  - An unknown workflow returns 404 "Workflow not found"
- **FR-WFL-05** (Could) Sign & Send and Sign Only workflows start with the signed-in user as the first signer; unknown workflow types are rejected.
  - Sign Only: recipient 1 is the signed-in user with role Signer
  - Sign & Send: recipient 1 is the signed-in user followed by an empty recipient 2
  - Creating a workflow with an unknown type returns 422 "type must be one of send, sign-send, in-person, self"

## Recipients (REC)

Who signs, in which order.

- **FR-REC-01** (Should) Recipients can be added, reordered, given a role and removed, and picking a known contact fills the email.
  - Choosing contact "Mei Tanaka" fills mei.tanaka@example.com
  - Moving recipient 2 up swaps the order and shows an "Unsaved changes" badge
  - Save shows "Workflow saved." and the order survives a reload
- **FR-REC-02** (Could) Saving a recipient with a malformed email is refused by the server and the draft stays unsaved.
  - Message "Recipient 1: “not-an-email” is not a valid email address"

## Document templates (DOC)

Attach PDFs from a searchable template library.

- **FR-DOC-01** (Must) Choosing a template in the searchable dropdown attaches it; the document processes for about 3 seconds before it can be tagged.
  - Typing "brokerage" lists 5 options (BrokerageAccountApp, BrokerageAmendment, BrokerageAuthorization, BrokerageDisclosure, BrokerageWaiver, each .pdf)
  - Picking one shows "Processing: <file>", a Documents row with 4 pages and status Processing
  - Tag Document does nothing while Processing and opens the Tasks Editor once the status is Ready
- **FR-DOC-02** (Could) The dropdown is keyboard operable and shows a no-results tip.
  - A search with no match shows "No results found..."
  - Typing, ArrowDown and Enter picks the highlighted option
- **FR-DOC-03** (Should) A workflow holds at most 5 distinct documents; removing a document removes its tasks.
  - Attaching the same template twice alerts "<file> is already attached"
  - After 5 documents the dropdown is disabled; a 6th via the API returns 422 "A workflow can hold at most 5 documents"
  - An unknown template returns 422 "templateId does not match a document template"

## Tasks editor (TSK)

Place and edit signing fields on rendered pages.

- **FR-TSK-01** (Must) Dragging a task type from the list onto a page places it where the pointer is released, in PDF points.
  - The editor shows 4 pages of 612×792 pt and 10 task types
  - A Signature marker is 180×36 and appears under the drop point; its Left / Top match the drop point, not the page centre
  - An announcement "Signature placed on page 1 at (…) via drag-and-drop" is made
- **FR-TSK-02** (Should) Double-click or Enter on a task type places it centred on the page in view.
  - Initials (64×30) lands at Left / Top 274, 381 on page 1
  - Date Signed placed by keyboard lands at 251, 385
- **FR-TSK-03** (Should) Placed markers can be moved, resized (minimum 12×12) and nudged with arrow keys, always staying within the page, and Save keeps their new position and size.
  - Moving right by 100 px at 100% zoom raises Left by about 100 and keeps Top
  - ArrowLeft stops at Left 0; dragging past the right edge clamps so Left + width ≤ 612
  - Save shows "Saved 1 task(s)" and a reload shows the position the marker had when saved
- **FR-TSK-04** (Should) The task properties dialog validates numeric input against the page bounds.
  - Left 500 with width 180: "The task must fit inside the page (612 × 792 pt)."
  - Left "abc": "left must be a number"
  - Left 100, Top 600: "Task updated" and the marker moves
- **FR-TSK-05** (Could) Zoom changes how large pages and markers are drawn but never their stored point coordinates.
  - Zooming to 150% leaves Left / Top unchanged
  - A task dropped at 150% is stored as screen offset ÷ 1.5
  - Fit width shows a non-preset percentage
- **FR-TSK-06** (Should) The tasks API validates processing state, task type, page, bounds and recipient.
  - Still processing: 409 "<file> is still processing"
  - Unknown type: 422 "Task 1 (Stamp): unknown task type. Allowed: Signature, Initials, Date Signed, Full Name, Email, Title, Company, Text, Checkbox, Attachment"
  - Page 9: 422 "Task 1 (Signature): page must be between 1 and 4"
  - Out of bounds: 422 "Task 1 (Signature): placement is outside the page (page is 612×792 pt)"
  - Unknown recipient: 422 "Task 1 (Signature): recipient 3 does not exist"
  - A valid set is saved and echoed with 200

## Send for signature (SND)

Validation and launch of a workflow as a transaction.

- **FR-SND-01** (Must) Send now is refused while the workflow has problems, and every problem is listed at once.
  - An empty draft lists: Enter a workflow title; Recipient 1: full name is required; Recipient 1: a valid email is required; Recipient 1 has no Signature task; Add at least one document
  - With documents still processing the list includes "Wait for documents to finish processing"
  - A recipient without a Signature task shows "<name> has no Signature task"
- **FR-SND-02** (Must) A complete workflow launches a transaction with a signing link per signer, and cannot be launched twice.
  - Message "Congratulations! You have successfully launched the Workflow to start your Transaction" and "Transaction TX-1003 is now out for signature."
  - Each signer gets an "Open signing link" to /esign/sign/<token>
  - The transaction drawer shows the signer Pending and audit entries Created and Sent
  - Sending again returns 409 "Workflow already Out for Signature"

## Signing ceremony (SGN)

The signer’s consent, signature, field entry and finish.

- **FR-SGN-01** (Must) A signer opens the link, consents, adopts a signature, completes required fields and finishes; a finished link cannot be reused.
  - Intro shows the workflow title, "From <sender> · for <name> (<role>)" and "<n> document(s), <m> field(s) for you to complete."; Continue is disabled until "I agree to use electronic records and signatures." is ticked
  - Document view shows "0 of 2 required" rising to "2 of 2 required" as fields are completed; Date inserts today as M/D/YYYY
  - Finish shows "All done!" — "All parties have signed. A completed copy will be emailed to everyone."
  - Reopening the link shows "Signed" — "You have already signed this document."
- **FR-SGN-02** (Should) Finish is enabled only after the signer has scrolled to the end of the document.
  - Disabled Finish shows the hint and tooltip "Scroll to the end of the document to enable Finish"
  - At the end the hint reads "Ready to finish"
- **FR-SGN-03** (Could) "Next ▸" scrolls to the next unfilled required field and is disabled when none remain.
- **FR-SGN-04** (Should) The Adopt Your Signature dialog supports select-style, draw and upload and validates each before adoption.
  - Empty pad: "Draw your signature in the box."
  - Non-image upload: "Upload a PNG, JPG, GIF or SVG image."
  - Image over 1 MB: "The image must be smaller than 1 MB."
  - Empty name in select-style: "Type your full name."
- **FR-SGN-05** (Must) The completion endpoint enforces consent, a signature, all required fields and single use, independent of the UI.
  - No consent: 422 "You must agree to use electronic records and signatures"
  - No signature: 422 "Adopt a signature first (draw, type or upload)"
  - Missing fields: 422 "<n> required field(s) still need your input" with the missing task ids
  - Empty drawn data: 422 "The drawn signature is empty — draw your signature in the box"
  - Success returns 200 with status Completed; repeating returns 409 "You have already signed"
  - An unknown token returns 404 "This signing link is invalid or has expired"
- **FR-SGN-06** (Must) Signers sign in routing order: a later signer sees a waiting page until earlier signers finish.
  - Early signer: "Not your turn yet" — "Waiting for Mei Tanaka to sign first"
  - After Mei finishes: "Thank you, Mei Tanaka. The document has been routed to Ola Nordmann." and Ola can then open the ceremony
  - The transaction then shows Mei Signed with a time, Ola Pending, progress "1 / 2 signed"
- **FR-SGN-07** (Should) A signer can decline with a reason, which sets the transaction to Declined.
  - An empty reason shows "Tell the sender why you are declining."
  - Confirmation "Declined" — "You declined to sign. The sender has been notified."
  - The dashboard moves the workflow from Out for Signature to Declined

## Transactions (TRX)

Track and void sent workflows.

- **FR-TRX-01** (Should) Transactions lists every sent workflow (never drafts) with progress, searchable, and a details drawer with recipients, documents and audit trail.
  - A fresh session lists TX-1002 (0 / 2 signed, "Mei Tanaka → Ola Nordmann") and TX-1001 (Completed)
  - Searching "nordmann" leaves only TX-1002
  - The drawer shows an "Open signing link" with Copy (briefly "Copied!") only for the active signer; waiting signers have no link
  - Closing the drawer removes ?open from the address
- **FR-TRX-02** (Should) Voiding a transaction needs a reason of at least 5 characters and invalidates its signing links; completed transactions cannot be voided.
  - A short reason: "Give a reason of at least 5 characters."
  - Voided shows "Voided: <reason>" and no Void button
  - A voided signing link shows "Transaction voided" — "This transaction was voided by the sender"
  - Voiding a Completed workflow returns 409 "Cannot void a Completed workflow"

## Mouse Lab (LAB)

A page of pointer, scroll, hover and drag exercises.

- **FR-LAB-01** (Could) Mouse Lab shows nine numbered sections and an event log; the "I have read everything" button is enabled only after its inner scroll area is scrolled to the bottom, and the infinite feed loads 20 envelopes at a time up to 200.
  - Reaching the end shows "No more envelopes"
- **FR-LAB-02** (Could) The kanban board (HTML5 drag) and the sortable list (pointer drag) apply moves and keep them for the session.
  - Dragging "Verify ID" to Done gives To do 2, Done 2
  - Dragging "Alpha" below "Charlie" shows "Order: Bravo, Charlie, Alpha, Delta, Echo, Foxtrot"
  - Both survive a reload and are returned by the lab state API
- **FR-LAB-03** (Could) Free drag, long-press (1 s hold to confirm), single/double/middle/right clicks and inline rename are recognised and logged.
  - Dropping the box in the zone shows "inside the drop zone ✔"
  - Holding 1 s shows "Confirmed ✔"; releasing early resets the fill
  - Right click opens no browser context menu
- **FR-LAB-04** (Could) Hover-only controls, canvas pointer tracking, the movable dialog and Ctrl+wheel zoom work.
  - Hovering "@jordan.rivera" shows a card "Jordan Rivera — Account owner · 4 envelopes"
  - Row actions Edit and Archive appear only on the hovered row
  - Canvas shows "x … · y …" and "Pointer outside" when left
  - Ctrl+wheel changes zoom; Reset returns 100%

## Non-functional requirements

- **NFR-01** (Must) Each browser session sees its own copy of the data; workflows created in one session are invisible to another.
  - A second session sees only the 3 seeded workflows and Drafts 1
  - Opening another session’s workflow shows "This workflow does not exist (or belongs to another session)."
- **NFR-02** (Could) On a 375 px wide viewport the navigation collapses behind a "Toggle navigation" button, closes after navigating, and tables stack their rows with labels.

## Glossary and rules

- **Workflow** — A draft package of recipients, documents and placed tasks; becomes a transaction when sent.
- **Transaction** — A sent workflow with per-recipient progress and an audit trail.
- **Task** — A field placed on a page (Signature, Initials, Date Signed, Full Name, Email, Title, Company, Text, Checkbox, Attachment).
- **Point** — PDF unit; pages are 612×792 pt and stored coordinates are in points regardless of zoom.

## Out of scope

- Real PDF rendering (pages are generated images)
- Email delivery
- Legal validity of signatures
- The Document Templates menu (coming soon)