diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index d6152ef..5690c3b 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -106,42 +106,42 @@ Which phases cover which requirements. Updated during roadmap creation. | Requirement | Phase | Status | |-------------|-------|--------| -| MKTG-01 | Phase 2 | Pending | -| MKTG-02 | Phase 2 | Pending | -| MKTG-03 | Phase 2 | Pending | -| MKTG-04 | Phase 2 | Pending | | AUTH-01 | Phase 1 | Pending | | AUTH-02 | Phase 1 | Pending | | AUTH-03 | Phase 1 | Pending | | AUTH-04 | Phase 1 | Pending | +| MKTG-01 | Phase 2 | Pending | +| MKTG-02 | Phase 2 | Pending | +| MKTG-03 | Phase 2 | Pending | +| MKTG-04 | Phase 2 | Pending | | CLIENT-01 | Phase 3 | Pending | | CLIENT-02 | Phase 3 | Pending | | CLIENT-03 | Phase 3 | Pending | +| DASH-01 | Phase 3 | Pending | +| DASH-02 | Phase 3 | Pending | | DOC-01 | Phase 4 | Pending | | DOC-02 | Phase 4 | Pending | | DOC-03 | Phase 4 | Pending | | DOC-04 | Phase 5 | Pending | | DOC-05 | Phase 5 | Pending | | DOC-06 | Phase 5 | Pending | -| DASH-01 | Phase 3 | Pending | -| DASH-02 | Phase 3 | Pending | | SIGN-01 | Phase 6 | Pending | | SIGN-02 | Phase 6 | Pending | | SIGN-03 | Phase 6 | Pending | | SIGN-04 | Phase 6 | Pending | | SIGN-05 | Phase 6 | Pending | | SIGN-06 | Phase 6 | Pending | -| SIGN-07 | Phase 7 | Pending | | LEGAL-01 | Phase 6 | Pending | | LEGAL-02 | Phase 6 | Pending | -| LEGAL-03 | Phase 7 | Pending | | LEGAL-04 | Phase 6 | Pending | +| SIGN-07 | Phase 7 | Pending | +| LEGAL-03 | Phase 7 | Pending | **Coverage:** - v1 requirements: 28 total - Mapped to phases: 28 -- Unmapped: 0 ✓ +- Unmapped: 0 --- *Requirements defined: 2026-03-19* -*Last updated: 2026-03-19 after initial definition* +*Last updated: 2026-03-19 after roadmap creation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..dc59a4c --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,133 @@ +# 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. + +- [ ] **Phase 1: Foundation** - Next.js project, database schema, Vercel Blob storage, and three-layer agent authentication +- [ ] **Phase 2: Marketing Site** - Public-facing hero, bio, contact form, testimonials, and listings placeholder +- [ ] **Phase 3: Agent Portal Shell** - Client management (create/view/profile) and dashboard skeleton with document status +- [ ] **Phase 4: PDF Ingest** - Agent PDF upload, Vercel Blob storage pipeline, browser rendering, and document record creation +- [ ] **Phase 5: PDF Fill and Field Mapping** - Drag-and-drop signature field placement, coordinate conversion, and agent text fill +- [ ] **Phase 6: Signing Flow** - Complete end-to-end signing ceremony with legal compliance: email delivery, signing page, canvas capture, audit trail +- [ ] **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. Database schema is deployed to Neon, Vercel Blob bucket is created, and the project is deployed to Vercel with environment variables wired +**Plans**: TBD + +Plans: none yet + +### 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**: TBD + +Plans: none yet + +### 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**: TBD + +Plans: none yet + +### Phase 4: PDF Ingest +**Goal**: Agent can upload a PDF form, see it rendered in the browser, and it is stored safely in Vercel Blob +**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 Vercel Blob (not local filesystem) and survive server restarts +**Plans**: TBD + +Plans: none yet + +### 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**: TBD + +Plans: none yet + +### 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**: TBD + +Plans: none yet + +### 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 private Vercel Blob storage — 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 | 0/? | Not started | - | +| 2. Marketing Site | 0/? | Not started | - | +| 3. Agent Portal Shell | 0/? | Not started | - | +| 4. PDF Ingest | 0/? | Not started | - | +| 5. PDF Fill and Field Mapping | 0/? | Not started | - | +| 6. Signing Flow | 0/? | Not started | - | +| 7. Audit Trail and Download | 0/? | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..3e0473f --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,65 @@ +# Project State + +## Project Reference + +See: .planning/PROJECT.md (updated 2026-03-19) + +**Core value:** Teressa can prepare and send any real estate form to a client for signing in minutes, from her browser, without leaving her site. +**Current focus:** Phase 1 - Foundation + +## Current Position + +Phase: 1 of 7 (Foundation) +Plan: 0 of ? in current phase +Status: Ready to plan +Last activity: 2026-03-19 — Roadmap created; ready to plan Phase 1 + +Progress: [░░░░░░░░░░] 0% + +## Performance Metrics + +**Velocity:** +- Total plans completed: 0 +- Average duration: - +- Total execution time: 0 hours + +**By Phase:** + +| Phase | Plans | Total | Avg/Plan | +|-------|-------|-------|----------| +| - | - | - | - | + +**Recent Trend:** +- Last 5 plans: none yet +- Trend: - + +*Updated after each plan completion* + +## Accumulated Context + +### Decisions + +Decisions are logged in PROJECT.md Key Decisions table. +Recent decisions affecting current work: + +- Custom e-signature over DocuSign: lower ongoing cost for solo agent; full brand control +- Next.js full-stack: single repo for marketing + web app via API routes +- Email-link signing (no client account): lowest friction for clients; standard in real estate +- utahrealestate.com forms scraping: AVOID — violates ToS; use manual PDF upload instead + +### Pending Todos + +None yet. + +### Blockers/Concerns + +- WFRMLS vendor enrollment takes 2-4 weeks — start process immediately, build Phase 2 listings with mock data while waiting +- Phase 6 (Signing Flow) warrants a /gsd:research-phase before planning — JWT one-time enforcement + ESIGN/UETA audit + mobile touch has edge cases +- DNS (SPF/DKIM/DMARC) for teressacopelandhomes.com must be configured before any signing link reaches a real client (Phase 6 acceptance criterion) +- Exact WFRMLS required IDX disclaimer text must be obtained directly from WFRMLS before listings feature ships (Phase 2) + +## Session Continuity + +Last session: 2026-03-19 +Stopped at: Roadmap created — 7 phases, 28/28 v1 requirements mapped +Resume file: None