468 lines
39 KiB
Markdown
468 lines
39 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.
|
|
|
|
v1.2 extends the platform to multiple signers in parallel and ships a production-ready Docker Compose deployment with correct SMTP and secret injection.
|
|
|
|
v1.3 adds a document template system — agent creates reusable field layouts with signer role labels and text hints, then applies them when starting new client documents so the same PDF never needs to be field-mapped from scratch.
|
|
|
|
## Milestones
|
|
|
|
- ✅ **v1.0 Core Document Signing Platform** - Phases 1-7 (shipped 2026-03-21)
|
|
- 🚧 **v1.1 Smart Document Preparation** - Phases 8-13 (in progress)
|
|
- 📋 **v1.2 Multi-Signer and Deployment Hardening** - Phases 14-17 (planned)
|
|
- 📋 **v1.3 Document Templates** - Phases 18-20 (planned)
|
|
|
|
## 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)
|
|
- [x] **Phase 11.1: Agent and Client Initials (INSERTED)** - Agent draws initials once, saves to profile, places agent-initials fields (embedded at prepare time); client-initials fields already wired via existing 'initials' type (completed 2026-03-21)
|
|
- [x] **Phase 12: Filled Document Preview** - Agent sees a live filled preview of the fully-prepared document before the Send button is available (completed 2026-03-21)
|
|
- [x] **Phase 12.1: Per-Field Text Editing and Quick-Fill (INSERTED)** - Agent clicks a text field box to edit its value inline; PreparePanel shows quick-fill suggestions (client name, address, etc.) when a field is selected; text fill data is keyed by field ID (completed 2026-03-21)
|
|
- [ ] **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
|
|
|
|
### 📋 v1.2 Multi-Signer and Deployment Hardening (Planned)
|
|
|
|
**Milestone Goal:** A single document can be sent to multiple signers in parallel, each receiving their own link and seeing only their own fields, with automatic completion notifications — plus a production-ready Docker Compose setup that correctly passes secrets so email works reliably.
|
|
|
|
- [x] **Phase 14: Multi-Signer Schema** - Additive DB migration enabling multi-signer field routing, per-signer token identity, and race-safe completion detection (completed 2026-04-03)
|
|
- [x] **Phase 15: Multi-Signer Backend** - Token creation loop, signer-aware signing flow, atomic completion detection, parallel email dispatch and final PDF delivery (completed 2026-04-03)
|
|
- [x] **Phase 16: Multi-Signer UI** - PreparePanel signer list, FieldPlacer signer assignment and color-coding, send-block validation, per-signer dashboard status (completed 2026-04-03)
|
|
- [x] **Phase 17: Docker Deployment** - Three-stage Dockerfile, docker-compose.yml with named uploads volume and env_file secrets, health endpoint, SMTP fix (completed 2026-04-03)
|
|
|
|
### 📋 v1.3 Document Templates (Planned)
|
|
|
|
**Milestone Goal:** Agent creates reusable document templates with pre-placed fields (including AI auto-placement) so the same PDF never needs to be field-mapped from scratch for every client.
|
|
|
|
- [x] **Phase 18: Template Schema and CRUD API** - New `document_templates` table with Drizzle migration; list, create, rename, and soft-delete API routes (completed 2026-04-06)
|
|
- [ ] **Phase 19: Template Editor UI** - FieldPlacer `onPersist` abstraction, template editor page at `/portal/templates/[id]`, AI auto-place wired to template context, signer role label support, save template
|
|
- [ ] **Phase 20: Apply Template and Portal Nav** - "Start from template" option in AddDocumentModal, apply operation with field snapshot and role-to-email mapping, text hint quick-fill, Templates portal nav section and list page
|
|
|
|
## 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 11.1: Agent and Client Initials (INSERTED)
|
|
|
|
**Goal**: Agent draws initials once, saves to their profile, places agent-initials fields on documents (embedded at prepare time, invisible to client); the existing 'initials' type already handles client-initials end-to-end with no changes required
|
|
**Requirements**: INIT-01, INIT-02, INIT-03, INIT-04
|
|
**Depends on**: Phase 11
|
|
**Plans**: 3 plans
|
|
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Agent can draw and save initials on the profile page — thumbnail displayed
|
|
2. Agent can update (replace) saved initials at any time
|
|
3. Agent can place agent-initials token in FieldPlacer; prepared PDF embeds the initials PNG at each agent-initials field coordinate; field never surfaces to client during signing
|
|
4. The existing 'initials' token in FieldPlacer continues to work for client-initials; client is prompted to initial each field during signing session (no code changes needed — confirmed by Plan 01 verification)
|
|
|
|
Plans:
|
|
- [ ] 11.1-01-PLAN.md — DB migration (agentInitialsData TEXT on users), GET/PUT /api/agent/initials routes, AgentInitialsPanel component, profile page section, FieldPlacer agent-initials palette token (orange), isClientVisibleField() + SignatureFieldType updates
|
|
- [ ] 11.1-02-PLAN.md — preparePdf() agentInitialsData param + embedPng/drawImage at agent-initials coordinates; prepare route fetches agentInitialsData + 422 guard; confirm 'initials' (client-initials) unchanged
|
|
- [x] 11.1-03-PLAN.md — Full Phase 11.1 human verification checkpoint (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**: 2 plans
|
|
|
|
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
|
|
- [x] 12-02-PLAN.md — Send button gating logic (disabled until preview generated, re-disabled on field change) + full Phase 12 human verification checkpoint (completed 2026-03-21)
|
|
|
|
### Phase 12.1: Per-Field Text Editing and Quick-Fill (INSERTED)
|
|
**Goal**: Agent clicks a text field box on the PDF to select it, types a value directly (or clicks a quick-fill suggestion from the PreparePanel), and each text field holds its own independent value keyed by field ID — replacing the broken positional text fill approach from Phase 12
|
|
**Depends on**: Phase 12
|
|
**Requirements**: TXTF-01, TXTF-02, TXTF-03
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Clicking a text field box on the PDF selects it and allows the agent to type a value for that specific field
|
|
2. Each text field box independently holds its own value (keyed by field ID) — changing one field does not affect others
|
|
3. When a text field is selected, PreparePanel shows quick-fill suggestion buttons (Client Name, Property Address, Client Email) that insert the corresponding value into the selected field
|
|
4. Text fill values entered per-field appear correctly embedded in the preview PDF and the final prepared PDF
|
|
5. The staleness token (previewToken) is reset when any text field value changes
|
|
**Plans**: 2 plans
|
|
|
|
Plans:
|
|
- [x] 12.1-01-PLAN.md — preparePdf() field-ID-keyed text lookup + Strategy B removal; FieldPlacer click-to-select inline input; PdfViewer + PdfViewerWrapper optional prop chain
|
|
- [x] 12.1-02-PLAN.md — DocumentPageClient selectedFieldId + textFillData shared state; PreparePanel QuickFillPanel + TextFillForm removal; 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.1
|
|
**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**: 4 plans
|
|
|
|
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: auth + OPENAI_API_KEY guards, extract PDF text, call classifyFieldsWithAI, write fields to DB, return { fields, textFillData }
|
|
- [ ] 13-03-PLAN.md — UI wiring: aiPlacementKey prop in FieldPlacer + PdfViewerWrapper thread-through; "AI Auto-place Fields" button (violet) in PreparePanel; DocumentPageClient handleAiAutoPlace with textFillData merge and preview reset
|
|
- [ ] 13-04-PLAN.md — Integration test with full 20-page Utah REPC + full Phase 13 human verification checkpoint
|
|
|
|
### Phase 14: Multi-Signer Schema
|
|
**Goal**: The database schema is ready for multi-signer documents — signers are first-class records on documents, tokens carry signer identity, and the completion guard column prevents race conditions — with zero breakage to existing single-signer documents
|
|
**Depends on**: Phase 13
|
|
**Requirements**: MSIGN-08
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Drizzle migration applies cleanly to the production Neon database with no data loss on existing documents or signing tokens
|
|
2. Existing single-signer documents continue to prepare, send, and sign exactly as before — the new nullable columns are invisible to the legacy code paths
|
|
3. `SignatureFieldData` TypeScript interface has an optional `signerEmail` field; `signingTokens` table has a nullable `signerEmail` TEXT column; `documents` table has `signers` JSONB and `completionTriggeredAt` TIMESTAMP columns
|
|
4. The `completionTriggeredAt` guard column is present and its purpose is verified: an `UPDATE ... WHERE completionTriggeredAt IS NULL RETURNING` query atomically claims it exactly once per document
|
|
**Plans**: 1 plan
|
|
|
|
Plans:
|
|
- [x] 14-01-PLAN.md — schema.ts multi-signer additions (SignatureFieldData.signerEmail, DocumentSigner interface, documents.signers JSONB, documents.completionTriggeredAt, signingTokens.signerEmail) + Drizzle migration 0010
|
|
|
|
**UI hint**: no
|
|
|
|
### Phase 15: Multi-Signer Backend
|
|
**Goal**: The server correctly creates one signing token per signer, filters each signer's signing page to their own fields, and detects completion atomically — all signers receive their links at once, and when the last signer signs all parties get the final PDF
|
|
**Depends on**: Phase 14
|
|
**Requirements**: MSIGN-05, MSIGN-06, MSIGN-07, MSIGN-10, MSIGN-11
|
|
**Success Criteria** (what must be TRUE):
|
|
1. When the agent sends a two-signer document, both signers receive their unique signing links in a single send operation (parallel email dispatch, no sequential dependency)
|
|
2. Each signer's GET /api/sign/[token] response contains only the fields tagged to that signer's email — fields belonging to other signers are absent from the response
|
|
3. The POST /api/sign/[token] handler rejects any field submission where the field's signerEmail does not match the token's signerEmail (server-enforced ownership)
|
|
4. When the last signer submits, `completionTriggeredAt` is claimed atomically — only one handler triggers final PDF assembly regardless of concurrent submissions
|
|
5. Agent receives a notification email and all signers receive the final merged PDF link when all signing tokens for the document are claimed
|
|
**Plans**: 3 plans
|
|
|
|
Plans:
|
|
- [x] 15-01-PLAN.md — Token utility extensions (signerEmail param, signer-download JWT), sendSignerCompletionEmail mailer, public signer download route
|
|
- [x] 15-02-PLAN.md — Send route rewrite: multi-signer token loop with Promise.all dispatch, legacy single-signer fallback, APP_BASE_URL rename
|
|
- [x] 15-03-PLAN.md — Sign handler rewrite: GET signer-filtered fields, POST signer-scoped operations + accumulate PDF + atomic completion + notifications
|
|
**UI hint**: no
|
|
|
|
### Phase 16: Multi-Signer UI
|
|
**Goal**: Agent can name and add multiple signers from PreparePanel, assign each field to a specific signer in FieldPlacer with color-coded visual distinction, and cannot accidentally send a document with unassigned client-facing fields
|
|
**Depends on**: Phase 15
|
|
**Requirements**: MSIGN-01, MSIGN-02, MSIGN-03, MSIGN-04, MSIGN-09
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Agent can add two or more signer email addresses in PreparePanel before sending — signers are saved to the document record and the list is editable until send
|
|
2. Each field placed in FieldPlacer has a signer assignment dropdown; selecting a signer changes the field's color to that signer's assigned color
|
|
3. If the agent clicks Send with any client-facing field (signature, initials, date, text) having no signer assigned, the send is blocked and a clear error message identifies the unassigned fields
|
|
4. The dashboard document detail view shows a per-signer completion row for each signer (who has signed, who hasn't, with timestamps)
|
|
**Plans**: 4 plans
|
|
|
|
Plans:
|
|
- [x] 16-01-PLAN.md — DocumentPageClient signers state threading, server page initialSigners prop, PdfViewerWrapper prop pass-through
|
|
- [ ] 16-02-PLAN.md — PreparePanel signer list UI (add/remove by email, colored dots, auto-assigned colors) + send-block validation
|
|
- [ ] 16-03-PLAN.md — FieldPlacer active signer selector dropdown + per-signer field coloring + validation overlay
|
|
- [ ] 16-04-PLAN.md — Dashboard N/M signed badge (signingTokens count query, DocumentsTable badge rendering)
|
|
**UI hint**: yes
|
|
|
|
### Phase 17: Docker Deployment
|
|
**Goal**: The application runs reliably in a Docker container on the production server — secrets are injected at runtime, email delivers correctly, uploaded files survive container restarts, and a health check confirms database connectivity
|
|
**Depends on**: Phase 16
|
|
**Requirements**: DEPLOY-01, DEPLOY-02, DEPLOY-03, DEPLOY-04, DEPLOY-05
|
|
**Success Criteria** (what must be TRUE):
|
|
1. `docker compose up` starts the application and `GET /api/health` returns 200 OK with a successful database ping
|
|
2. SMTP credentials are read from `.env.production` via `env_file:` in docker-compose.yml — a signing link email and a completion notification email both deliver successfully from the running container
|
|
3. The `APP_BASE_URL` variable (renamed from `NEXT_PUBLIC_BASE_URL`) is injected at container runtime — signing link URLs in emails contain the correct production domain, not localhost
|
|
4. Uploaded PDF files written inside the container persist after `docker compose down && docker compose up` (named Docker volume mounted at /app/uploads)
|
|
5. The Docker image uses `node:20-slim` (Debian-based) — `@napi-rs/canvas` native binary loads without errors at container startup
|
|
**Plans**: 2 plans
|
|
|
|
Plans:
|
|
- [x] 17-01-PLAN.md — Enable standalone output, limit DB pool to 5, remove @vercel/blob, add /api/health endpoint
|
|
- [x] 17-02-PLAN.md — Dockerfile (three-stage, node:20-slim, linux/amd64), docker-compose.yml (env_file, DNS fix, named volume), .dockerignore, .env.production.example
|
|
**UI hint**: no
|
|
|
|
### Phase 18: Template Schema and CRUD API
|
|
**Goal**: The `document_templates` table exists in the database and agents can create, rename, list, and soft-delete templates via API — every subsequent template feature depends on this foundation
|
|
**Depends on**: Phase 17
|
|
**Requirements**: TMPL-01, TMPL-02, TMPL-03, TMPL-04
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Agent can create a new template by selecting a PDF from the forms library — a `document_templates` row is inserted with the chosen `formTemplateId` FK and an empty field layout
|
|
2. Agent can rename a template and the new name is persisted and reflected immediately in the template list
|
|
3. Agent can delete a template — the row is soft-deleted (`archivedAt` set, not removed from DB) and disappears from the active list; no `ON DELETE CASCADE` touches any documents created from it
|
|
4. Agent can retrieve a list of all active templates showing form name and field count — archived templates are filtered out
|
|
**Plans**: 2 plans
|
|
|
|
Plans:
|
|
- [x] 18-01-PLAN.md — Drizzle schema: documentTemplates table definition + 0012 migration
|
|
- [x] 18-02-PLAN.md — CRUD API routes: GET/POST /api/templates, PATCH/DELETE /api/templates/[id]
|
|
**UI hint**: no
|
|
|
|
### Phase 19: Template Editor UI
|
|
**Goal**: Agent can open any template in a full field-placement editor, use AI auto-place, assign signer role labels instead of real emails, set text hints on text fields, and save the template — reusing the existing FieldPlacer component without duplication
|
|
**Depends on**: Phase 18
|
|
**Requirements**: TMPL-05, TMPL-06, TMPL-07, TMPL-08, TMPL-09
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Agent can open a template at `/portal/templates/[id]` and see the source PDF rendered with any previously saved fields overlaid — the editor uses the existing FieldPlacer drag-drop interface unchanged
|
|
2. Agent can click "AI Auto-place" in the template editor and fields are placed on the template (routed through a `/api/templates/[id]/ai-prepare` route, not the document route)
|
|
3. Signer assignment in the template editor accepts role labels ("Buyer", "Seller", "Agent") rather than email addresses — role strings are stored in the `signerEmail` slot and the editor does not reject them as invalid emails
|
|
4. Agent can set a text hint on any text field — the hint is stored in the template and is visible as a placeholder label in the editor
|
|
5. Agent can click Save and the current field layout (with role labels and text hints) is persisted to `document_templates.signatureFields` — a subsequent page reload shows the saved state
|
|
**Plans**: 3 plans
|
|
|
|
Plans:
|
|
- [ ] 19-01-PLAN.md — FieldPlacer/PdfViewer prop abstraction (onPersist, fieldsUrl, fileUrl), three template API routes (file, fields, ai-prepare), PortalNav Templates link
|
|
- [ ] 19-02-PLAN.md — Templates list page with create modal, template editor page (TemplatePageClient + TemplatePanel with roles, AI, save)
|
|
- [ ] 19-03-PLAN.md — Full Phase 19 human verification checkpoint (9-step E2E browser test)
|
|
**UI hint**: yes
|
|
|
|
|
|
|
|
### Phase 20: Apply Template and Portal Nav
|
|
**Goal**: Agent can start any new client document from a saved template — all fields are pre-loaded with fresh IDs, roles map to real signer emails, text hints appear as quick-fill suggestions — and "Templates" is a top-level portal destination
|
|
**Depends on**: Phase 19
|
|
**Requirements**: TMPL-10, TMPL-11, TMPL-12, TMPL-13, TMPL-14, TMPL-15, TMPL-16
|
|
**Success Criteria** (what must be TRUE):
|
|
1. "Start from template" tab is available in AddDocumentModal; agent can pick a template from the list and create a document with all template fields pre-loaded at their saved positions
|
|
2. Every field copied from the template has a freshly generated UUID — none of the template's original field IDs appear in the new document; editing the template afterward does not change the document's fields
|
|
3. Template signer roles are automatically pre-mapped to the client's contacts (first role to primary contact, second role to co-buyer if present); agent can override any mapping before sending
|
|
4. Text hints from the template appear as quick-fill suggestion buttons in the new document's PreparePanel
|
|
5. "Templates" appears in the portal top nav and `/portal/templates` lists all active templates with form name, field count, and last-updated date
|
|
**Plans**: TBD
|
|
**UI hint**: yes
|
|
|
|
## Progress
|
|
|
|
**Execution Order:**
|
|
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 11.1 → 12 → 12.1 → 13 → 14 → 15 → 16 → 17 → 18 → 19 → 20
|
|
|
|
| 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 | 2/2 | Complete | 2026-03-21 |
|
|
| 9. Client Property Address | v1.1 | 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 | v1.1 | 3/3 | Complete | 2026-03-21 |
|
|
| 11.1. Agent and Client Initials (INSERTED) | v1.1 | 3/3 | Complete | 2026-03-21 |
|
|
| 12. Filled Document Preview | v1.1 | 2/2 | Complete | 2026-03-21 |
|
|
| 12.1. Per-Field Text Editing and Quick-Fill (INSERTED) | v1.1 | 2/2 | Complete | 2026-03-21 |
|
|
| 13. AI Field Placement and Pre-fill | v1.1 | 3/4 | In Progress | - |
|
|
| 14. Multi-Signer Schema | v1.2 | 1/1 | Complete | 2026-04-03 |
|
|
| 15. Multi-Signer Backend | v1.2 | 3/3 | Complete | 2026-04-03 |
|
|
| 16. Multi-Signer UI | v1.2 | 1/4 | Complete | 2026-04-03 |
|
|
| 17. Docker Deployment | v1.2 | 2/2 | Complete | 2026-04-03 |
|
|
| 18. Template Schema and CRUD API | v1.3 | 2/2 | Complete | 2026-04-06 |
|
|
| 19. Template Editor UI | v1.3 | 0/TBD | Not started | - |
|
|
| 20. Apply Template and Portal Nav | v1.3 | 0/TBD | Not started | - |
|