red/.planning/ROADMAP.md

# 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)
- [ ] **Phase 7: Audit Trail and Download** - Secure signed PDF download, document status tracking, and client-facing confirmation screen

## 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**: TBD

Plans: none yet

## 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 | 0/? | Not started | - |