161 lines
12 KiB
Markdown
161 lines
12 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.
|
|
|
|
## 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.
|
|
|
|
- [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 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 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)
|
|
**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:
|
|
- [ ] 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)
|
|
|
|
### 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:
|
|
- [ ] 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
|
|
|
|
### 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:
|
|
- [ ] 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
|
|
|
|
### 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
|
|
- [ ] 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
|
|
|
|
### 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
|
|
- [ ] 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-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:
|
|
- [ ] 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-03-PLAN.md — Full Phase 7 human verification checkpoint (SIGN-07 + LEGAL-03)
|
|
|
|
## Progress
|
|
|
|
**Execution Order:**
|
|
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7
|
|
|
|
| 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 |
|