docs: create milestone v1.1 roadmap (6 phases)
This commit is contained in:
Chandler Copeland
@@ -4,6 +4,13 @@
|
||||
|
||||
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:**
|
||||
@@ -12,16 +19,17 @@ A dual-product build: a public real estate marketing site for a solo Utah agent
|
||||
|
||||
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)
|
||||
- [ ] **Phase 2: Marketing Site** - Public-facing hero, bio, contact form, testimonials, and listings placeholder
|
||||
- [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)
|
||||
- [ ] **Phase 5: PDF Fill and Field Mapping** - Drag-and-drop signature field placement, coordinate conversion, and agent text fill
|
||||
- [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 Details
|
||||
|
||||
### 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)
|
||||
@@ -35,9 +43,9 @@ Decimal phases appear between their surrounding integers in numeric order.
|
||||
**Plans**: 3 plans
|
||||
|
||||
Plans:
|
||||
- [ ] 01-01-PLAN.md — Next.js scaffold, Drizzle schema, Auth.js v5 config, route-protection middleware, seed script
|
||||
- [ ] 01-02-PLAN.md — Branded login page, agent portal layout, dashboard stub, logout mechanism
|
||||
- [ ] 01-03-PLAN.md — Local environment setup (.env.local, db:migrate, db:seed) and local auth flow verification (checkpoint)
|
||||
- [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
|
||||
@@ -51,9 +59,9 @@ Plans:
|
||||
**Plans**: 3 plans
|
||||
|
||||
Plans:
|
||||
- [ ] 02-01-PLAN.md — Static page shell: sticky nav, split-panel hero, testimonials carousel, listings placeholder, footer
|
||||
- [ ] 02-02-PLAN.md — Contact form: Nodemailer SMTP mailer, server action with Zod + honeypot, ContactSection client component
|
||||
- [ ] 02-03-PLAN.md — Human verification checkpoint: full homepage review across all four MKTG requirements
|
||||
- [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
|
||||
@@ -84,10 +92,10 @@ Plans:
|
||||
**Plans**: 4 plans
|
||||
|
||||
Plans:
|
||||
- [ ] 04-01-PLAN.md — Schema (form_templates + documents columns), migration, seed script
|
||||
- [ ] 04-02-PLAN.md — API routes: forms-library, documents POST, documents/[id]/file
|
||||
- [ ] 04-03-PLAN.md — Add Document modal, PDF viewer page, react-pdf install
|
||||
- [ ] 04-04-PLAN.md — Full Phase 4 human verification checkpoint
|
||||
- [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
|
||||
@@ -102,9 +110,9 @@ 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
|
||||
- [ ] 05-02-PLAN.md — dnd-kit FieldPlacer component: drag-and-drop signature field placement, Y-axis coordinate conversion, blue rectangle overlay, field persistence
|
||||
- [ ] 05-03-PLAN.md — TextFillForm + PreparePanel: key-value text fill form, client selector dropdown, Prepare and Send workflow
|
||||
- [ ] 05-04-PLAN.md — Full Phase 5 human verification checkpoint
|
||||
- [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
|
||||
@@ -123,10 +131,10 @@ 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
|
||||
- [ ] 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
|
||||
- [ ] 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
|
||||
- [ ] 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
|
||||
- [ ] 06-05-PLAN.md — Confirmation page (/sign/[token]/confirmed), 15-min client download token, GET /api/sign/[token]/download route
|
||||
- [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
|
||||
@@ -140,21 +148,134 @@ Plans:
|
||||
**Plans**: 3 plans
|
||||
|
||||
Plans:
|
||||
- [ ] 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
|
||||
- [ ] 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-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.
|
||||
|
||||
- [ ] **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
|
||||
- [ ] **Phase 9: Client Property Address** - Add property address to client profiles for AI pre-fill data sourcing
|
||||
- [ ] **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
|
||||
**Plans**: TBD
|
||||
|
||||
Plans:
|
||||
- [ ] 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**: TBD
|
||||
|
||||
Plans:
|
||||
- [ ] 09-01-PLAN.md — DB migration (propertyAddress nullable TEXT on clients table), server action update, ClientModal form field, client profile display
|
||||
|
||||
### 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**: 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
|
||||
**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**: 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
|
||||
**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
|
||||
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13
|
||||
|
||||
| Phase | Plans Complete | Status | Completed |
|
||||
|-------|----------------|--------|-----------|
|
||||
| 1. Foundation | 1/3 | Complete | 2026-03-19 |
|
||||
| 2. Marketing Site | 2/3 | In Progress| |
|
||||
| 3. Agent Portal Shell | 4/4 | Complete | 2026-03-19 |
|
||||
| 4. PDF Ingest | 4/4 | Complete | 2026-03-20 |
|
||||
| 5. PDF Fill and Field Mapping | 3/4 | In Progress| |
|
||||
| 6. Signing Flow | 6/6 | Complete | 2026-03-21 |
|
||||
| 7. Audit Trail and Download | 4/4 | Complete | 2026-03-21 |
|
||||
| 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 | v1.1 | 0/2 | Not started | - |
|
||||
| 9. Client Property Address | v1.1 | 0/1 | Not started | - |
|
||||
| 10. Expanded Field Types End-to-End | v1.1 | 0/3 | Not started | - |
|
||||
| 11. Agent Saved Signature and Signing Workflow | v1.1 | 0/3 | Not started | - |
|
||||
| 12. Filled Document Preview | v1.1 | 0/2 | Not started | - |
|
||||
| 13. AI Field Placement and Pre-fill | v1.1 | 0/4 | Not started | - |
|
||||
|
||||
Reference in New Issue
Block a user