Files

Chandler Copeland e36c6c8ee2 docs: complete project research

2026-03-21 11:28:42 -06:00

29 KiB

Raw Blame History

Feature Research

Domain: Real estate agent website + document signing portal — v1.1 Smart Document Preparation Researched: 2026-03-21 Confidence: HIGH for field types and signing flows (strong industry evidence); MEDIUM for AI field detection accuracy (implementation approach has a critical constraint); HIGH for document preview expectations

Scope Note

This file covers only the v1.1 milestone features. The existing v1.0 features (agent portal, client management, PDF upload/preview, drag-drop field placement, PreparePanel text fill, email-link signing, presigned download) are already built and validated.

New features under research:

AI-assisted field placement and pre-fill (gpt-4o-mini)
Expanded field types: text, checkbox, initials, date, agent signature
Agent saved signature + sign-first workflow
Filled document preview before sending

Feature Landscape

Table Stakes (Users Expect These)

Features a real estate agent would expect from any "smart document prep" upgrade. Missing these makes the v1.1 feel like a half-measure.

Feature	Why Expected	Complexity	Notes
Initials field type	Every Utah standard form (REPC, listing agreement, addenda) has initials lines on every page — initialing page-by-page is a core legal convention	MEDIUM	At signing time: initials block shows a condensed canvas (not full signature); auto-scrolls to each initials field after previous completion; behaves identically to signature field but smaller canvas
Date field type	Date-of-signing is required on nearly every field block; agents expect it to auto-fill at signing moment, not require client to type a date	LOW	Industry standard: date field is a read-only "Date Signed" stamp — system fills it at the moment the signer completes the signature block; client never types a date; dotloop and DocuSign both implement this as locked/auto-populated
Checkbox field type	Utah REPC and addenda use boolean checkboxes throughout (mediation clauses, contingency elections, disclosure acknowledgments)	LOW	At signing time: client taps/clicks to check; visual distinction (empty square vs. checked square); must be assigned to a specific signer or it defaults to "no one" and never gets checked (dotloop behavior confirmed)
Agent signature field type	Agent needs to counter-sign documents before sending; this is a separate field type from client signature — tied to agent's saved signature, not client's canvas	MEDIUM	Distinct from client signature: pre-filled by agent in the prep flow; client sees it as already signed when they open the document; not a client-facing interactive field
Agent signs before sending	Industry convention in real estate: the listing agent or buyer's agent signs first to demonstrate they've reviewed and authorized the document, then sends to client for counter-signature	MEDIUM	Sign-first is the dominant pattern; agent signs as Routing Order 1, client signs as Routing Order 2; DocuSign community documentation confirms this as the standard real estate workflow
Filled document preview before send	Agents expect to see the document exactly as the client will see it — with all pre-filled text, agent signature, and field placement visible — before hitting Send	MEDIUM	Preview must show: pre-filled text values, agent signature applied, all field markers overlaid on the PDF; client-facing fields should appear interactive but not be submittable from the preview

Differentiators (Competitive Advantage)

Features that go beyond the baseline — meaningful specifically for this app's single-agent, Utah-forms workflow.

Feature	Value Proposition	Complexity	Notes
AI field placement via gpt-4o-mini	Teressa can click one button and have all signature, initials, date, checkbox, and text fields placed on a Utah standard form automatically — eliminating the manual drag-drop session for known forms	HIGH	Critical constraint: gpt-4o does not reliably return accurate pixel coordinates from images (< 3% accuracy in bounding box studies). Correct approach: extract PDF text with positional metadata via pdf-lib or pdfjs-dist, then use gpt-4o-mini for semantic understanding of field labels ("Buyer's Signature", "Date", "Initial Here") and return normalized page coordinates calculated from the text's own bounding box data — not from vision inference. AI does the label-understanding; the PDF SDK does the coordinate math.
AI pre-fill of text fields	Client name, property address, and date fields can be populated from client profile data + property data without manual typing in PreparePanel	MEDIUM	gpt-4o-mini maps known data (client.firstName, client.lastName, client.email, property.address) to identified text fields by label proximity. Low risk of hallucination because input is structured profile data, not free text inference. Model simply matches "Buyer" label to client name.
Agent saved signature (draw once, reuse)	Agent draws signature once on first use; it is stored as a PNG data URL and applied to any agent signature field with one click — eliminating per-document re-drawing	MEDIUM	Standard in every major real estate e-sig tool (DocuSign, dotloop, SkySlope); agents expect this; re-drawing every document is a daily friction point. Stored in agent profile. Can be cleared and redrawn. Display a "preview" of the saved signature before applying.
Property address on client profile	Teressa adds the property address to the client record so AI pre-fill knows what to insert into property address fields across all documents for that transaction	LOW	Simple field addition to client profile schema; enables AI pre-fill to be property-specific without Teressa re-typing the address on every document

Anti-Features (Commonly Requested, Often Problematic)

Feature	Why Requested	Why Problematic	Alternative
AI generates pixel-perfect field placement from visual PDF analysis	"Just have AI look at the PDF image and tell me where the fields are"	gpt-4o and Claude 3.5 Sonnet return accurate pixel coordinates less than 3% of the time in bounding box studies (February 2025 research); placing a signature field 200px from the actual signature line produces a broken document	Extract text positions from the PDF's own data structures via pdfjs-dist or pdf-lib; use AI for label-matching only; compute coordinates from extracted text bounding boxes
AI auto-fill replaces the agent's PreparePanel review	"AI should fill everything and I just hit Send"	For legal documents, pre-fill values that are wrong create liability; purchase price, closing date, earnest money must be agent-verified before the document goes to a client	AI pre-fills obvious known values (names, address); agent reviews in PreparePanel and edits before sending; preview step is the final check
AI confidence thresholds surface to the agent	"Show me which fields AI isn't sure about"	Confidence scoring UX adds noise; solo agent workflow doesn't need a triage interface; if a field is missed, the agent sees it in preview	If AI misses a field, agent adds it manually in the existing drag-drop UI; preview step catches any gaps
Signature type-in fallback for agent signature	"Let agent type their name as their signature"	Typed signatures have lower perceived legal weight in real estate; clients may question them; canvas signature is the industry standard for agent counter-signatures	Canvas-drawn signature stored and reused; never degrade to typed for agent's own signature
Per-document redraw option for agent signature	"Maybe I want to sign slightly differently for important contracts"	Adds decision fatigue at the exact moment agents want speed; the value of saved signature is consistency and one-click application	Store one saved signature; provide a "Re-draw my signature" option in agent profile settings only, not in the per-document flow
Fully locked preview (no corrections possible)	"The preview is just a review step — agent can't change anything"	If the preview reveals a mistake (wrong address pre-filled, agent signature in wrong position), the agent needs to correct it before sending; a read-only preview that requires going back to square one increases frustration	Preview includes a back-to-edit button; light inline corrections (move a field, fix a pre-filled value) should be possible from or after the preview

Feature Dependencies

[v1.0 Client Management]
    └──enables──> [Property Address Field on Client Profile] (new field addition)
                      └──enables──> [AI Pre-fill of Text Fields]

[v1.0 PDF Upload + Rendering]
    └──enables──> [AI Field Detection] (needs PDF text extraction)
    └──enables──> [Expanded Field Types] (builds on existing field overlay system)

[v1.0 Drag-Drop Field Placement UI]
    └──extended by──> [Expanded Field Types (checkbox, initials, date, agent sig)]
    └──enhanced by──> [AI Field Detection] (pre-populates fields; agent adjusts)

[v1.0 PreparePanel (text fill)]
    └──enhanced by──> [AI Pre-fill] (populates known values automatically)
    └──enables──> [Filled Document Preview] (preview shows PreparePanel values rendered)

[Agent Saved Signature]
    └──requires──> [Agent Profile / Settings storage]
    └──enables──> [Agent Signature Field Type] (one-click apply)
    └──enables──> [Agent Signs First Workflow]

[Agent Signs First Workflow]
    └──requires──> [Agent Saved Signature]
    └──requires──> [Agent Signature Field Type]
    └──enables──> [Filled Document Preview] (preview makes most sense after agent signs)

[Filled Document Preview]
    └──requires──> [Agent Signs First Workflow] (or at minimum: PreparePanel fill complete)
    └──requires──> [Expanded Field Types] (all field types must render correctly in preview)
    └──gates──> [Send to Client] (Send button lives in or after the preview step)

Dependency Notes

AI Field Detection requires PDF text extraction, not vision: The correct implementation extracts text with positional bounding boxes from the PDF (via pdfjs-dist getTextContent() or pdf-lib) and passes labeled text positions to gpt-4o-mini for semantic field-type classification. The AI returns field type + which extracted text object to anchor to; the coordinate calculation uses the text object's own transform data. This avoids the coordinate-from-vision accuracy problem entirely.
Expanded field types extend the existing field overlay system: The v1.0 signature field is already rendered as an overlay div on the PDF canvas with stored x/y/page/width/height. Adding checkbox, initials, date, and agent signature types means adding field-type discriminants to the same data model and rendering different UI chrome per type. Not a new system — an extension.
Agent Saved Signature is a prerequisite for Agent Signs First: The one-click agent signing workflow only makes sense if the agent's signature is already stored. Without it, the agent would need to draw their signature in the agent-facing flow, which is equivalent to the client signing flow — functional but not the intended UX.
Filled Document Preview gates Send: The preview is the final checkpoint. Send to Client should only be reachable from the preview screen (or with explicit bypass). This prevents the common mistake of sending the wrong document version.
Date fields must be non-editable by the client at signing time: Date fields auto-populate at the moment the client completes the signing session. This is the DocuSign "Date Signed" pattern — a read-only auto-stamped field, not a calendar picker. The client cannot alter the date. This is legally important (it records when they actually signed, not a date they type in).
Checkbox fields must be signer-assigned to function: Based on dotloop behavior, checkboxes default to "no one" if not explicitly assigned to a signer role. In this app's model, the agent assigns each checkbox to either the agent role (pre-checked during agent signing) or the client role (checked by client during signing). Unassigned checkboxes that are pre-checked by the agent are treated as acknowledgment fields (not interactive for the client).

v1.1 Feature Definitions

v1.1 Launch Features (the four areas)

Property address on client profile — add propertyAddress field to client schema; display and edit in client detail view; used as AI pre-fill source for property address fields in documents
Expanded field types: checkbox — checkbox field type in field placement sidebar; renders as empty square overlay; at signing: client taps to check; stores boolean checked state in document record; embeds checkmark into final PDF
Expanded field types: initials — initials field type; renders as smaller signature canvas at signing time; same capture mechanics as signature (canvas drawing, stored as PNG); labeled "Initial Here" vs "Sign Here"
Expanded field types: date — date field type; renders as read-only overlay; auto-populates with signing timestamp when client completes signing session; client cannot edit; embed formatted date string into final PDF
Expanded field types: agent signature — agent signature field type placed by agent during prep; displays agent's saved signature image in preview and in the document sent to client; client sees it as already-signed; not interactive for client
Agent saved signature — canvas draw interface on agent profile/settings; stores as base64 PNG; persists across sessions; "Re-draw" clears and prompts re-capture; shown as thumbnail in profile settings
Agent signs first workflow — after field placement and PreparePanel fill, agent applies saved signature to all agent-signature fields; clicking an agent-sig field applies the stored PNG; all agent-sig fields must be filled before Proceed to Preview is enabled
AI field placement — single "Auto-place Fields" button in the prep flow; PDF text extracted via pdfjs-dist with bounding boxes; payload sent to gpt-4o-mini with label-to-field-type mapping prompt; AI returns field type + text anchor identifier; system computes coordinates from text bounding box; places fields on PDF overlay; agent reviews and adjusts; always falls back gracefully to manual placement if AI returns nothing
AI pre-fill — after AI field placement, text fields with high-confidence label matches (buyer name, seller name, property address, today's date) are pre-populated from client profile data; agent reviews in PreparePanel; agent can edit any pre-filled value
Filled document preview — full-page PDF render with all overlays visible: pre-filled text values, agent signature rendered in-place, all client-facing fields shown with their type chrome (empty sig box, unchecked checkbox, "Initial Here" box, date placeholder); Send to Client button lives here; Back to Edit button returns to PreparePanel

Defer to v1.2

AI confidence display to agent — show which fields AI was uncertain about; adds UI complexity; agent can see and correct in preview instead; defer until volume of AI misses proves it necessary
Template save from AI placement — save AI-generated field layout as a reusable template per form type; high value but requires template management UI; defer until AI placement is validated as accurate
Multiple agent signature fields — currently one agent sig is the typical pattern; multiple is possible with the field system but needs UX thought (which signature applies where); defer

Feature Prioritization Matrix (v1.1)

Feature	User Value	Implementation Cost	Priority
Agent saved signature	HIGH	LOW	P1
Initials field type	HIGH	LOW	P1
Date field (auto-stamp)	HIGH	LOW	P1
Checkbox field type	HIGH	LOW	P1
Agent signature field type	HIGH	MEDIUM	P1
Agent signs first workflow	HIGH	MEDIUM	P1
Filled document preview	HIGH	MEDIUM	P1
Property address on client profile	HIGH	LOW	P1
AI pre-fill from profile data	HIGH	MEDIUM	P1
AI field placement (gpt-4o-mini + text extraction)	HIGH	HIGH	P1
AI field placement template save	MEDIUM	HIGH	P3
AI confidence display to agent	LOW	MEDIUM	P3

Priority key:

P1: Must have for v1.1 launch
P2: Should have, add when possible
P3: Nice to have, future consideration

Behavioral Specifications by Feature

(1) AI-Assisted Field Detection

How it works in production tools: Apryse, Instafill, and DocuSign Iris (January 2026) all use a hybrid approach: PDF structure parsing to extract text positions, then LLM for semantic classification. Raw vision-based bounding box inference is not production-viable — GPT-4o returns accurate pixel coordinates in under 3% of attempts in published benchmarks.

Accuracy expectations: On structured Utah standard forms (REPC, listing agreements, addenda), which have consistent label patterns ("Buyer's Signature", "Seller's Initials", "Date", "Property Address"), label-matching accuracy should be HIGH (90%+) because the label text is predictable. The risk is on non-standard addenda or scanned/image-based PDFs where text extraction fails.

Fallback hierarchy:

PDF has extractable text → text extraction + AI label matching → place fields at text positions (HIGH confidence path)
PDF is image-based (scanned) → AI cannot extract text → show message "Auto-placement requires a text-based PDF. Place fields manually." → agent falls back to drag-drop
AI returns no fields or low-confidence results → show "AI couldn't detect fields confidently. Review the placement or add fields manually." → pre-filled fields from AI are shown as suggestions with a different visual treatment; agent confirms or removes each one

What the agent sees: A "Detecting fields..." loading state (2-5 seconds), then fields appear on the PDF overlay. A summary count: "AI placed 14 fields — 8 signature, 3 date, 2 initials, 1 checkbox. Review and adjust." Misplaced fields can be dragged or deleted.

gpt-4o-mini vs gpt-4o: Use gpt-4o-mini for this task. The task is classification and mapping (semantic understanding of form labels), not complex reasoning. gpt-4o-mini handles this at lower cost (~0.15-0.60 cents per PDF page vs gpt-4o's 2.5-10 cents). At Teressa's volume (solo agent, dozens of documents per month), either is negligible cost.

(2) Expanded Field Types at Signing Time

Initials: Renders as a smaller version of the signature canvas ("Initial Here" label instead of "Sign Here"). Client draws their initials. Same capture mechanics as signature (canvas, PNG data URL). Stored separately from signature so audit trail distinguishes "initialed page 3" from "signed on page 8". The industry convention on Utah forms is to initial every page — this field type handles that pattern.

Checkboxes: Renders as an empty square (24x24px). Client taps or clicks to toggle. A checkmark renders inside on selection. Toggle is allowed before final submission (client can uncheck and recheck). At submission, the checked/unchecked state is embedded as a drawn checkmark or empty box in the PDF. Checkboxes assigned to agent are pre-checked during agent signing flow and appear pre-checked when client opens the document (read-only from client perspective).

Date fields: Auto-stamp pattern only — no calendar picker for the client. The field shows a placeholder ("Date will be filled at signing") when the agent previews. At the moment the client clicks "Complete Signing", all date fields are stamped with the UTC timestamp formatted as the local date (e.g., "March 21, 2026"). This matches DocuSign's "Date Signed" field behavior. The client cannot type a date. This is the legally correct approach — it records when they actually signed.

Agent signature fields: The agent places these during prep. During agent signing (before preview), clicking an agent-sig field applies the stored PNG. The PNG renders at the field's bounding box dimensions. When the document is sent to the client, these fields are already filled and read-only. The client cannot modify or remove the agent's signature.

(3) Agent Counter-Signature Flow

Sign-first is the industry norm: In real estate, the agent (representing one party) typically signs first to show they've reviewed and authorized the document, then it routes to the client. This is confirmed by DocuSign's recommended routing for real estate: agent at Order 1, client at Order 2. Dotloop's auto-date behavior applies the same timestamp logic to the agent's first signature.

Saved vs. per-document redraw: All major tools store a saved signature. DocuSign calls it "Adopted Signature." Dotloop stores it per account. SkySlope DigiSign stores it account-wide. Per-document redraw exists in some tools as an option but agents rarely use it. The saved pattern is the standard because: (a) agents sign dozens of documents per transaction, (b) consistency across documents matters for authenticity, (c) re-drawing adds 30-60 seconds per document that adds up across a week.

Implementation pattern for this app: Agent Profile page has a "My Signature" section with a canvas draw interface. On first use (when an agent tries to apply a signature to a field), if no signature is saved, the app prompts them to draw and save one. After saving, applying is one click. "Re-draw Signature" in profile settings clears and prompts a new canvas session.

What happens if no agent signature fields exist in the document: If the agent places no agent-sig fields, the "Agent Signing" step is skipped and the flow goes directly from PreparePanel to Preview. The workflow should not require agent signature — it should be optional based on whether agent-sig fields were placed.

(4) Document Preview Before Sending

What users expect to see: The industry standard preview (DocuSign, BoldSign, Adobe Sign) shows the document exactly as the recipient will see it: all filled fields rendered in-place, all empty fields visible with their interaction chrome (highlighted boxes for client-interactive fields). The agent is not in "edit mode" — they're seeing the client's view.

What users expect to be able to do: The most common expectation is a Back button to return to editing. Users do not expect to edit inline in the preview, but they do expect: (a) ability to scroll through all pages, (b) see a "Document is ready to send" or "X fields still need agent action" status, (c) confirm the send action from the preview. A "Download Preview" option (PDF download of the current state) is valued but not table stakes.

Common pre-send mistake preview prevents: Sending the wrong version of a document is the most-cited error in the industry. Agents also commonly send documents with unfilled agent signature fields (forgot to sign). The preview step catches both: the agent can see if their signature is missing from any agent-sig fields, and the document version is explicitly what they reviewed.

Preview in the context of this app: The preview should render using the same PDF.js rendering pipeline as the existing prep view, but with all overlay fields in "signed/filled" visual state rather than "editable" state. Pre-filled text values appear as rendered text on the PDF. Agent signature fields show the saved signature PNG. Client-interactive fields (signature, initials, checkbox) show their placeholder chrome (highlighted box, "Sign Here" label) so the agent can see what the client will see. Date fields show "—" or "Auto-fill on signing."

Competitor Feature Analysis (v1.1 Scope)

Feature	DocuSign	Dotloop	SkySlope DigiSign	This App (v1.1)
AI field placement	DocuSign Iris (Jan 2026) — AI auto-places via agreement analysis	No AI placement — template-based only	Smart Suite auto-audit, not field placement	gpt-4o-mini + pdfjs text extraction; Utah-specific label patterns
Initials field	Yes — condensed signature canvas	Yes — same as signature but labeled "Initial"	Yes	Canvas draw, labeled "Initial Here"; same capture as signature
Date field behavior	"Date Signed" — auto-stamp, locked, client cannot edit	Auto-date/time stamp on signature and initials	Add time/date to signatures automatically	Auto-stamp at signing session completion; client cannot type a date
Checkbox field	Yes — toggle checkbox	Yes — binary check	Yes	Tap/click toggle; embed checkmark or empty box into PDF
Agent saved signature	Yes — "Adopted Signature" stored account-wide	Yes — stored per account	Yes	Canvas-drawn, stored in agent profile as PNG
Agent signs first	Yes — Routing Order 1 agent, Order 2 client	Yes — sequential signing order supported	Yes	Agent signing step before preview; agent-sig fields pre-filled before client sees doc
Pre-send preview	Yes — "Preview" step shows filled document	Yes — document preview in loop before sharing	Yes	Full PDF render with all overlays in filled state; Send button lives in preview
AI pre-fill from contact data	Yes — Rooms for Real Estate prefills from transaction data	Yes — via transaction record	Yes — via transaction file	Pre-fill from client profile (name, email, property address)

Sources

AI field detection and coordinate accuracy:

Auto-detect PDF Form Fields with Smart Data Extraction — Apryse
SAM 2 + GPT-4o Cascading Foundation Models — Edge AI and Vision Alliance (Feb 2025) — confirms GPT-4o returns accurate bounding box coordinates in fewer than 3% of attempts
GPT-4o Model: Image Coordinate Recognition — OpenAI Community
Case Study: Real Estate Law Flat PDF Form Automation — Instafill.ai (Feb 2026)
Intelligent Document Processing for Real Estate — Syntora
Using Confidence Scoring to Reduce Risk in AI-Driven Decisions — Multimodal.dev
Understanding Accuracy and Confidence in Azure Document Intelligence — Microsoft Learn

Field types and signing behavior:

Agent counter-signature and routing order:

Prefill fields before sending envelope for signature — DocuSign Community — confirms agent at routing order 1, client at routing order 2 as real estate standard
Mastering Sequential Multi-Signer Workflows — Docomotion
Best Electronic Signature Software for Real Estate in 2026 — SignEasy
Lone Wolf Authentisign — Real estate's leading eSignature solution

Document preview and prefill:

Utah REPC form specifics:

Feature research for: Teressa Copeland Homes — v1.1 Smart Document Preparation Researched: 2026-03-21

29 KiB Raw Blame History