282 lines
22 KiB
Markdown
282 lines
22 KiB
Markdown
# Roadmap: Teressa Copeland Homes
|
|
|
|
## Overview
|
|
|
|
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.
|
|
|
|
## Milestones
|
|
|
|
- ✅ **v1.0 Core Document Signing Platform** - Phases 1-7 (shipped 2026-03-21)
|
|
- 🚧 **v1.1 Smart Document Preparation** - Phases 8-13 (in progress)
|
|
|
|
## Phases
|
|
|
|
**Phase Numbering:**
|
|
- Integer phases (1, 2, 3): Planned milestone work
|
|
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
|
|
|
|
Decimal phases appear between their surrounding integers in numeric order.
|
|
|
|
<details>
|
|
<summary>✅ v1.0 Core Document Signing Platform (Phases 1-7) — SHIPPED 2026-03-21</summary>
|
|
|
|
- [x] **Phase 1: Foundation** - Next.js project, local PostgreSQL database schema, and single-agent authentication (local dev; eventual home Docker server) (completed 2026-03-19)
|
|
- [x] **Phase 2: Marketing Site** - Public-facing hero, bio, contact form, testimonials, and listings placeholder
|
|
- [x] **Phase 3: Agent Portal Shell** - Client management (create/view/profile) and dashboard skeleton with document status (completed 2026-03-19)
|
|
- [x] **Phase 4: PDF Ingest** - Agent PDF upload, local file storage pipeline, browser rendering, and document record creation (completed 2026-03-20)
|
|
- [x] **Phase 5: PDF Fill and Field Mapping** - Drag-and-drop signature field placement, coordinate conversion, and agent text fill
|
|
- [x] **Phase 6: Signing Flow** - Complete end-to-end signing ceremony with legal compliance: email delivery, signing page, canvas capture, audit trail (completed 2026-03-21)
|
|
- [x] **Phase 7: Audit Trail and Download** - Secure signed PDF download, document status tracking, and client-facing confirmation screen (completed 2026-03-21)
|
|
|
|
### Phase 1: Foundation
|
|
**Goal**: Agent can log in, reach the portal, and the infrastructure that every subsequent phase depends on is in place
|
|
**Depends on**: Nothing (first phase)
|
|
**Requirements**: AUTH-01, AUTH-02, AUTH-03, AUTH-04
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Agent can log in with email and password and reach a portal page (blank dashboard is acceptable)
|
|
2. Agent session persists after browser refresh and tab close — agent does not have to log in again
|
|
3. Visiting any `/agent/*` route while unauthenticated redirects to the login page (not a 404 or blank screen)
|
|
4. Agent can log out from the portal and is returned to the login page
|
|
5. Local PostgreSQL database is running and schema is applied (`db:migrate`), seed account created, and `npm run dev` serves the app at localhost:3000
|
|
**Plans**: 3 plans
|
|
|
|
Plans:
|
|
- [x] 01-01-PLAN.md — Next.js scaffold, Drizzle schema, Auth.js v5 config, route-protection middleware, seed script
|
|
- [x] 01-02-PLAN.md — Branded login page, agent portal layout, dashboard stub, logout mechanism
|
|
- [x] 01-03-PLAN.md — Local environment setup (.env.local, db:migrate, db:seed) and local auth flow verification (checkpoint)
|
|
|
|
### Phase 2: Marketing Site
|
|
**Goal**: Visitors can find Teressa online, see her brand, view the listings placeholder, and submit a contact inquiry
|
|
**Depends on**: Phase 1
|
|
**Requirements**: MKTG-01, MKTG-02, MKTG-03, MKTG-04
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Visitor sees Teressa's professional photo and warm introductory bio in the hero section at teressacopelandhomes.com
|
|
2. Visitor sees a testimonials section with client reviews on the homepage
|
|
3. Visitor sees a "listings coming soon" placeholder section (full WFRMLS listings deferred to v2)
|
|
4. Visitor can submit a contact form with name, email, phone, and message — and the submission is received
|
|
**Plans**: 3 plans
|
|
|
|
Plans:
|
|
- [x] 02-01-PLAN.md — Static page shell: sticky nav, split-panel hero, testimonials carousel, listings placeholder, footer
|
|
- [x] 02-02-PLAN.md — Contact form: Nodemailer SMTP mailer, server action with Zod + honeypot, ContactSection client component
|
|
- [x] 02-03-PLAN.md — Human verification checkpoint: full homepage review across all four MKTG requirements
|
|
|
|
### Phase 3: Agent Portal Shell
|
|
**Goal**: Agent can manage clients and see all documents with their current status at a glance
|
|
**Depends on**: Phase 1
|
|
**Requirements**: CLIENT-01, CLIENT-02, CLIENT-03, DASH-01, DASH-02
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Agent can create a client record with name and email address
|
|
2. Agent can view a list of all clients
|
|
3. Agent can view a client's profile page and see the documents associated with that client
|
|
4. Agent can see all documents in the dashboard with their current status (Draft / Sent / Viewed / Signed) and which client each was sent to and when
|
|
**Plans**: 4 plans
|
|
|
|
Plans:
|
|
- [x] 03-01-PLAN.md — Drizzle schema (clients + documents tables), DB migration, middleware + auth config updated for /portal prefix
|
|
- [x] 03-02-PLAN.md — Portal layout with top nav, StatusBadge, DocumentsTable shared components, client server actions
|
|
- [x] 03-03-PLAN.md — Dashboard page (filterable documents table) + Clients list page (card grid + create modal) + seed data
|
|
- [x] 03-04-PLAN.md — Client profile page (edit/delete/documents table) + full Phase 3 human verification checkpoint
|
|
|
|
### Phase 4: PDF Ingest
|
|
**Goal**: Agent can upload a PDF form, see it rendered in the browser, and it is stored safely on the local filesystem / Docker volume
|
|
**Depends on**: Phase 3
|
|
**Requirements**: DOC-01, DOC-02, DOC-03
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Agent can upload a PDF form (manual upload — no utahrealestate.com scraping) and the document appears in the portal
|
|
2. Agent can view the uploaded PDF rendered in the browser on the document detail page
|
|
3. The forms library reflects updated forms on at least a monthly basis (automated sync or manual re-upload path defined and working)
|
|
4. Uploaded PDFs are stored in the local uploads directory (Docker volume on home server) and survive server restarts
|
|
**Plans**: 4 plans
|
|
|
|
Plans:
|
|
- [x] 04-01-PLAN.md — Schema (form_templates + documents columns), migration, seed script
|
|
- [x] 04-02-PLAN.md — API routes: forms-library, documents POST, documents/[id]/file
|
|
- [x] 04-03-PLAN.md — Add Document modal, PDF viewer page, react-pdf install
|
|
- [x] 04-04-PLAN.md — Full Phase 4 human verification checkpoint
|
|
|
|
### Phase 5: PDF Fill and Field Mapping
|
|
**Goal**: Agent can place signature fields on any page of a PDF and fill in client/property text fields before sending
|
|
**Depends on**: Phase 4
|
|
**Requirements**: DOC-04, DOC-05, DOC-06
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Agent can drag and drop signature fields onto any page of a PDF document and the fields appear at the correct position on the page
|
|
2. Signature field coordinates are stored in PDF user space (bottom-left origin) — verified by a unit test against an actual Utah real estate form
|
|
3. Agent can fill in text fields (property address, client names, dates, prices) on the document before sending
|
|
4. Agent can assign the prepared document to a specific client and initiate a signing request
|
|
**Plans**: 4 plans
|
|
|
|
Plans:
|
|
- [x] 05-01-PLAN.md — Schema extension (signatureFields, textFillData, assignedClientId, preparedFilePath JSONB columns), migration 0003, @cantoo/pdf-lib prepare utility, GET/PUT /api/documents/[id]/fields, POST /api/documents/[id]/prepare
|
|
- [x] 05-02-PLAN.md — dnd-kit FieldPlacer component: drag-and-drop signature field placement, Y-axis coordinate conversion, blue rectangle overlay, field persistence
|
|
- [x] 05-03-PLAN.md — TextFillForm + PreparePanel: key-value text fill form, client selector dropdown, Prepare and Send workflow
|
|
- [x] 05-04-PLAN.md — Full Phase 5 human verification checkpoint
|
|
|
|
### Phase 6: Signing Flow
|
|
**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
|
|
**Depends on**: Phase 5
|
|
**Requirements**: SIGN-01, SIGN-02, SIGN-03, SIGN-04, SIGN-05, SIGN-06, LEGAL-01, LEGAL-02, LEGAL-04
|
|
**Success Criteria** (what must be TRUE):
|
|
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
|
|
**Plans**: 6 plans
|
|
|
|
Plans:
|
|
- [x] 06-01-PLAN.md — Schema migration 0005 (signingTokens + auditEvents tables + 3 documents columns), signing utility library (token.ts, audit.ts, embed-signature.ts), npm install signature_pad + @react-email
|
|
- [x] 06-02-PLAN.md — Branded signing request email (React Email), signing-mailer utilities, POST /api/documents/[id]/send route, document_prepared audit logging in prepare route
|
|
- [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
|
|
- [x] 06-05-PLAN.md — Confirmation page (/sign/[token]/confirmed), 15-min client download token, GET /api/sign/[token]/download route
|
|
- [x] 06-06-PLAN.md — DNS (SPF/DKIM/DMARC) verification checkpoint (LEGAL-04 gate)
|
|
|
|
### Phase 7: Audit Trail and Download
|
|
**Goal**: Agent can download any signed PDF securely, and signed documents are never accessible via guessable public URLs
|
|
**Depends on**: Phase 6
|
|
**Requirements**: SIGN-07, LEGAL-03
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Agent can download the signed PDF from the dashboard via an authenticated presigned URL (5-minute TTL)
|
|
2. Signed PDFs are stored in a private local directory (not publicly accessible) — a direct or guessable URL returns an access error, not the file
|
|
3. Document status in the dashboard updates correctly to "Signed" after a signing ceremony completes
|
|
**Plans**: 3 plans
|
|
|
|
Plans:
|
|
- [x] 07-01-PLAN.md — Agent download token utilities (createAgentDownloadToken/verifyAgentDownloadToken in token.ts) + GET /api/documents/[id]/download route with 5-min presigned JWT and path traversal guard
|
|
- [x] 07-02-PLAN.md — PreparePanel Signed-state panel with Download button, document detail page server-side token generation, DocumentsTable Date Signed column, dashboard signedAt select
|
|
- [x] 07-03-PLAN.md — Full Phase 7 human verification checkpoint (SIGN-07 + LEGAL-03)
|
|
|
|
</details>
|
|
|
|
### 🚧 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)
|
|
- [x] **Phase 9: Client Property Address** - Add property address to client profiles for AI pre-fill data sourcing (completed 2026-03-21)
|
|
- [x] **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 (completed 2026-03-21)
|
|
- [x] **Phase 11: Agent Saved Signature and Signing Workflow** - Draw once, save, apply to agent signature fields during document preparation before sending to client (completed 2026-03-21)
|
|
- [ ] **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
|
|
**Plans**: 2 plans
|
|
|
|
Plans:
|
|
- [x] 08-01-PLAN.md — Discriminated union type extension in schema.ts, Drizzle migration, backward-compat fallback in all field-reading paths
|
|
- [ ] 08-02-PLAN.md — Signing page type filter (sign route line 88 + SigningPageClient.tsx type branching) + human verification checkpoint
|
|
|
|
### Phase 9: Client Property Address
|
|
**Goal**: Agent can store a property address on a client profile so it is available as structured data for AI pre-fill
|
|
**Depends on**: Phase 8
|
|
**Requirements**: CLIENT-04, CLIENT-05
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Agent can add or edit a property address on any client profile from the portal
|
|
2. Property address is saved to the database and displayed on the client profile page
|
|
3. Property address is returned alongside client name when the prepare-document pipeline fetches client data (available as a pre-fill source)
|
|
**Plans**: 1 plan
|
|
|
|
Plans:
|
|
- [ ] 09-01-PLAN.md — DB schema migration, server actions, ClientModal input, ClientProfileClient display, PreparePanel state pre-seed (CLIENT-04, CLIENT-05)
|
|
|
|
### Phase 10: Expanded Field Types End-to-End
|
|
**Goal**: Agent can place text, checkbox, initials, and date field markers on any PDF and the prepared document embeds each type correctly
|
|
**Depends on**: Phase 8
|
|
**Requirements**: FIELD-01, FIELD-02, FIELD-03, FIELD-04
|
|
**Success Criteria** (what must be TRUE):
|
|
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**: 3 plans
|
|
|
|
Plans:
|
|
- [x] 10-01-PLAN.md — FieldPlacer palette: 5 typed tokens with distinct colors; type-aware field overlays and DragOverlay ghost
|
|
- [x] 10-02-PLAN.md — preparePdf() type-branched rendering (checkbox X, date placeholder, initials placeholder, text bg); POST route signable filter + date stamp at sign time
|
|
- [x] 10-03-PLAN.md — SigningPageClient initials capture + overlay suppression; SignatureModal title prop; human verification checkpoint
|
|
|
|
### 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
|
|
**Depends on**: Phase 10
|
|
**Requirements**: AGENT-01, AGENT-02, AGENT-03, AGENT-04
|
|
**Success Criteria** (what must be TRUE):
|
|
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**: 3 plans
|
|
|
|
Plans:
|
|
- [ ] 11-01-PLAN.md — DB migration (agentSignatureData TEXT on users), GET/PUT /api/agent/signature routes, AgentSignaturePanel (draw + save + thumbnail), /portal/profile page, PortalNav Profile link, FieldPlacer agent-signature palette token
|
|
- [ ] 11-02-PLAN.md — preparePdf() agentSignatureData param + embedPng/drawImage at agent-sig coordinates; prepare route fetches agentSignatureData + 422 guard when sig missing
|
|
- [x] 11-03-PLAN.md — Full Phase 11 human verification checkpoint (draw, save, place, prepare, verify embedded in PDF + absent from client signing page) (completed 2026-03-21)
|
|
|
|
### 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
|
|
**Plans**: TBD
|
|
|
|
Plans:
|
|
- [ ] 13-01-PLAN.md — lib/ai/extract-text.ts (pdfjs-dist legacy build, server-only), lib/ai/field-placement.ts (GPT-4o-mini structured output, manual JSON schema, server-only guard), aiCoordsToPagePdfSpace() utility + unit test
|
|
- [ ] 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
|
|
|
|
## Progress
|
|
|
|
**Execution Order:**
|
|
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13
|
|
|
|
| Phase | Milestone | Plans Complete | Status | Completed |
|
|
|-------|-----------|----------------|--------|-----------|
|
|
| 1. Foundation | v1.0 | 3/3 | Complete | 2026-03-19 |
|
|
| 2. Marketing Site | v1.0 | 3/3 | Complete | 2026-03-21 |
|
|
| 3. Agent Portal Shell | v1.0 | 4/4 | Complete | 2026-03-19 |
|
|
| 4. PDF Ingest | v1.0 | 4/4 | Complete | 2026-03-20 |
|
|
| 5. PDF Fill and Field Mapping | v1.0 | 4/4 | Complete | 2026-03-21 |
|
|
| 6. Signing Flow | v1.0 | 6/6 | Complete | 2026-03-21 |
|
|
| 7. Audit Trail and Download | v1.0 | 3/3 | Complete | 2026-03-21 |
|
|
| 8. Schema Foundation and Signing Page Safety | 2/2 | Complete | 2026-03-21 | - |
|
|
| 9. Client Property Address | 1/1 | Complete | 2026-03-21 | - |
|
|
| 10. Expanded Field Types End-to-End | v1.1 | 3/3 | Complete | 2026-03-21 |
|
|
| 11. Agent Saved Signature and Signing Workflow | 3/3 | Complete | 2026-03-21 | - |
|
|
| 12. Filled Document Preview | v1.1 | 0/2 | Not started | - |
|
|
| 13. AI Field Placement and Pre-fill | v1.1 | 0/4 | Not started | - |
|