A dual-product build: a public real estate marketing site for a solo Utah agent and a private document-signing portal that replaces per-month third-party tools with a fully branded, custom implementation. The build proceeds in dependency order — foundation first, then independent public site, then the agent portal in three layers (shell, PDF ingest, PDF fill), then the signing ceremony as a complete vertical slice, then the final visibility and download layer. Every phase delivers a coherent, verifiable capability. The legally critical components (audit trail, one-time tokens, tamper-evident hash) are woven into Phase 6 from the start — they cannot be retrofitted.
v1.1 extends the platform with AI-assisted field placement, expanded field types (text, checkbox, initials, date, agent signature), agent saved signature with draw-once-reuse workflow, and a filled document preview before sending.
- [x]**Phase 7: Audit Trail and Download** - Secure signed PDF download, document status tracking, and client-facing confirmation screen (completed 2026-03-21)
**Goal**: Client receives an email link, opens the prepared PDF in any browser, draws a signature, and the signed document is stored with a complete, legally defensible audit trail
1. Client receives an email with a unique signing link and can open it in any browser (mobile or desktop) without creating an account
2. The signing link expires after 72 hours and can only be used once — a used or expired link shows "already signed" (never the canvas)
3. Client sees the prepared PDF with signature fields highlighted and can draw a freehand signature on a canvas on mobile and desktop (touch-action:none tested on iOS Safari and Android Chrome)
4. Client can save a default signature and apply it to a signature field without redrawing
5. Client sees a confirmation screen after successfully signing
6. The system logs all 6 audit trail events server-side (document prepared, email sent, link opened with IP/UA, document viewed, signature submitted, final PDF hash computed) — all timestamps are server-side
7. A SHA-256 hash of the final signed PDF is computed and stored immediately after signature embedding
8. DNS (SPF/DKIM/DMARC) is configured for teressacopelandhomes.com before any signing link is sent to a real client
- [x] 06-03-PLAN.md — Public /sign/[token] page (3 states: signing/already-signed/expired), react-pdf viewer with pulsing blue field overlays, sticky progress bar, GET /api/sign/[token] data route
- [x] 06-04-PLAN.md — SignatureModal (Draw/Type/Use Saved tabs, signature_pad with devicePixelRatio scaling), POST /api/sign/[token] with atomic usedAt enforcement, PDF embedding, SHA-256 hash
### 🚧 v1.1 Smart Document Preparation (In Progress)
**Milestone Goal:** Teressa can have AI auto-place and pre-fill all document fields with one click, sign as agent before sending, and preview the fully-prepared document before it reaches the client.
- [x]**Phase 8: Schema Foundation and Signing Page Safety** - Add type discriminant to SignatureFieldData JSONB and harden signing page — safety gate before any new field type ships (completed 2026-03-21)
- [ ]**Phase 10: Expanded Field Types End-to-End** - All new field types (text, checkbox, initials, date) available in field mapper UI and embedded correctly by the prepare pipeline
- [ ]**Phase 11: Agent Saved Signature and Signing Workflow** - Draw once, save, apply to agent signature fields during document preparation before sending to client
- [ ]**Phase 12: Filled Document Preview** - Agent sees a live filled preview of the fully-prepared document before the Send button is available
- [ ]**Phase 13: AI Field Placement and Pre-fill** - One-click AI auto-placement of all field types plus pre-fill of text fields from client profile data
## Phase Details
### Phase 8: Schema Foundation and Signing Page Safety
**Goal**: The codebase is safe to receive new field types — SignatureFieldData carries a type discriminant, the signing page filters by type atomically, and agent-signature fields can never surface to clients as required unsigned fields
**Depends on**: Phase 7
**Requirements**: FIELD-01
**Success Criteria** (what must be TRUE):
1.`SignatureFieldData` schema has a `type` discriminant field (`client-signature` | `initials` | `text` | `checkbox` | `date` | `agent-signature`) with backward-compatible fallback defaulting to `client-signature` for all v1.0 documents
2.`/api/sign/[token]` route filters `signatureFields` to client-visible types only — `agent-signature` fields are never returned to the signing page
3.`SigningPageClient.tsx` branches on field type and does not attempt to open the signature modal for non-client-signature types
4. Drizzle migration runs cleanly against the existing database with no data loss on existing documents
1. Agent can drag text, checkbox, initials, and date tokens from the FieldPlacer palette and place them on any page of a PDF
2. Prepared PDF embeds text fields as typed stamps, checkboxes as boolean marks, initials as placeholder markers, and date fields as auto-stamped signing-date values
3. Client signing page correctly handles initials fields (prompts for initials capture) and ignores text/checkbox/date fields (already embedded at prepare time)
4. A round-trip test (place all four types, prepare, open signing link) produces a correctly embedded PDF with no field type rendered in the wrong position
**Plans**: TBD
Plans:
- [ ] 10-01-PLAN.md — FieldPlacer palette: four new draggable tokens (text, checkbox, initials, date) with distinct visual affordances
- [ ] 10-02-PLAN.md — prepare-document.ts type-aware rendering switch: text stamp, checkbox embed, date auto-stamp, initials placeholder via @cantoo/pdf-lib
- [ ] 10-03-PLAN.md — Full Phase 10 human verification checkpoint (all four field types placed, prepared, and verified in PDF output)
### Phase 11: Agent Saved Signature and Signing Workflow
**Goal**: Agent draws a signature once, saves it to their profile, places agent signature fields on documents, and applies the saved signature during preparation — before the document is sent to the client
1. Agent can draw a signature on a canvas in the portal and save it to their account — a thumbnail of the saved signature is visible on the profile page
2. Agent can update (replace) their saved signature at any time
3. Agent can place agent signature field markers on a PDF from the FieldPlacer palette
4. When the agent prepares a document, their saved signature PNG is embedded at each agent-signature field coordinate — the field does not appear in the client signing session
**Plans**: TBD
Plans:
- [ ] 11-01-PLAN.md — DB migration (agentSignatureData TEXT on users table), GET/PUT /api/agent/signature routes, AgentSignaturePanel component (draw + save + thumbnail)
- [ ] 11-02-PLAN.md — FieldPlacer palette token for agent-signature type, prepare-document.ts PNG embed at agent-sig coordinates
- [ ] 11-03-PLAN.md — Full Phase 11 human verification checkpoint (draw, save, place, prepare, verify embedded in PDF + absent from client signing page)
### Phase 12: Filled Document Preview
**Goal**: Agent sees a live filled preview of the fully-prepared document — with all text, signatures, and field stamps embedded — before the Send button becomes available
**Depends on**: Phase 11
**Requirements**: PREV-01
**Success Criteria** (what must be TRUE):
1. A "Preview" button is available on the document prepare page and opens a modal showing the fully-prepared PDF rendered with all embedded content
2. The Send button is disabled until the agent has generated at least one preview of the current field state
3. If the agent changes any fields after previewing, the Send button is re-disabled until a fresh preview is generated (staleness detection)
4. The preview PDF uses a versioned path and does not overwrite the final prepared PDF (legal integrity of prepared document is preserved)
**Plans**: TBD
Plans:
- [ ] 12-01-PLAN.md — POST /api/documents/[id]/preview route (reuses preparePdf in preview mode, versioned path, staleness token), PreviewModal component with react-pdf rendering + ArrayBuffer copy
- [ ] 12-02-PLAN.md — Send button gating logic (disabled until preview generated, re-disabled on field change) + full Phase 12 human verification checkpoint
### Phase 13: AI Field Placement and Pre-fill
**Goal**: Agent clicks one button and AI auto-places all field types on the PDF in correct positions and pre-fills text fields with known client and property data
**Depends on**: Phase 12
**Requirements**: AI-01, AI-02
**Success Criteria** (what must be TRUE):
1. Agent can click "AI Auto-place" and the system extracts text from the PDF, classifies field labels via GPT-4o-mini, and populates the FieldPlacer with placed fields — no manual drag required
2. AI-placed text fields are pre-filled with client name, property address, and signing date where those values are available from the client profile
3. AI placement produces correct field positions on a full 20-page Utah REPC — coordinates convert correctly from percentage-based AI output to PDF user-space points (Y-axis inversion verified by unit test)
4. Agent can review, adjust, or delete any AI-placed field before proceeding to prepare — AI placement is a starting point, not a lock
- [ ] 13-02-PLAN.md — POST /api/documents/[id]/ai-prepare route (orchestrate extract + AI call + coordinate conversion + field write), "AI Auto-place" button in PreparePanel with loading state
- [ ] 13-03-PLAN.md — AI pre-fill: map client profile fields (name, property address, date) to placed text fields; agent review step before fields are committed
- [ ] 13-04-PLAN.md — Integration test with full 20-page Utah REPC + full Phase 13 human verification checkpoint
