171 lines
15 KiB
Markdown
171 lines
15 KiB
Markdown
---
|
|
gsd_state_version: 1.0
|
|
milestone: v1.1
|
|
milestone_name: smart-document-preparation
|
|
status: unknown
|
|
last_updated: "2026-03-21T17:02:31.470Z"
|
|
progress:
|
|
total_phases: 7
|
|
completed_phases: 7
|
|
total_plans: 28
|
|
completed_plans: 28
|
|
---
|
|
|
|
# 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 7 - Audit Trail and Download
|
|
|
|
## Current Position
|
|
|
|
Phase: Not started (defining requirements)
|
|
Plan: —
|
|
Status: Defining requirements for v1.1 — Smart Document Preparation
|
|
Last activity: 2026-03-21 — Milestone v1.1 started (13 requirements defined, roadmap pending)
|
|
|
|
Progress: [░░░░░░░░░░] 0% (v1.1 not started)
|
|
|
|
## Performance Metrics
|
|
|
|
**Velocity:**
|
|
- Total plans completed: 2
|
|
- Average duration: 4 min
|
|
- Total execution time: 0.1 hours
|
|
|
|
**By Phase:**
|
|
|
|
| Phase | Plans | Total | Avg/Plan |
|
|
|-------|-------|-------|----------|
|
|
| 01-foundation | 2/3 | 8 min | 4 min |
|
|
| 02-marketing-site | 2/3 | 8 min | 4 min |
|
|
|
|
**Recent Trend:**
|
|
- Last 5 plans: 01-01 (6 min), 01-02 (2 min), 02-01 (4 min), 02-02 (4 min)
|
|
- Trend: stable
|
|
|
|
*Updated after each plan completion*
|
|
| Phase 02-marketing-site P01 | 5 | 2 tasks | 8 files |
|
|
| Phase 03-agent-portal-shell P01 | 3 | 2 tasks | 6 files |
|
|
| Phase 03-agent-portal-shell P02 | 8 | 3 tasks | 5 files |
|
|
| Phase 03-agent-portal-shell P03 | 9 | 3 tasks | 7 files |
|
|
| Phase 03-agent-portal-shell P04 | 5 | 2 tasks | 3 files |
|
|
| Phase 04-pdf-ingest P01 | 8 | 2 tasks | 7 files |
|
|
| Phase 04-pdf-ingest P02 | 1 | 2 tasks | 3 files |
|
|
| Phase 04-pdf-ingest P04-03 | 5 | 2 tasks | 8 files |
|
|
| Phase 05-pdf-fill-and-field-mapping P02 | 1 | 2 tasks | 2 files |
|
|
| Phase 05-pdf-fill-and-field-mapping P03 | 3 | 2 tasks | 4 files |
|
|
| Phase 06-signing-flow P01 | 2 | 2 tasks | 8 files |
|
|
| Phase 06-signing-flow P02 | 2 | 2 tasks | 4 files |
|
|
| Phase 06-signing-flow P03 | 3 | 2 tasks | 6 files |
|
|
| Phase 06-signing-flow P04 | 7 | 2 tasks | 4 files |
|
|
| Phase 06-signing-flow P05 | 3 | 2 tasks | 4 files |
|
|
| Phase 06-signing-flow P06 | 2 | 2 tasks | 2 files |
|
|
| Phase 07-audit-trail-and-download P01 | 2 | 2 tasks | 2 files |
|
|
| Phase 07-audit-trail-and-download P02 | 2 | 2 tasks | 6 files |
|
|
| Phase 07-audit-trail-and-download P03 | 0 | 1 task (checkpoint) | 0 files |
|
|
| Phase 07-audit-trail-and-download P04 | 1 | 2 tasks | 2 files |
|
|
|
|
## 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
|
|
- Infrastructure: local PostgreSQL (Docker) + local `npm run dev`; no Vercel, no Neon, no cloud storage — home Docker server is eventual target
|
|
- [Phase 01-foundation]: Lazy Proxy singleton for db/index.ts prevents neon() crash during Next.js build when DATABASE_URL absent
|
|
- [Phase 01-foundation]: next-auth pinned to exact version 5.0.0-beta.30; middleware.ts at project root not src/; force-dynamic on auth route
|
|
- [Phase 01-foundation 01-02]: PasswordField extracted as co-located client sub-component — keeps login page.tsx as pure server component
|
|
- [Phase 01-foundation 01-02]: loginAction re-throws non-AuthError (NEXT_REDIRECT must bubble) — critical Auth.js v5 server action pattern
|
|
- [Phase 01-foundation 01-02]: Brand colors applied via inline style props — Tailwind JIT may miss one-off hex values
|
|
- [Phase 02-marketing-site]: CSS hover classes in server components — onMouseEnter/onMouseLeave not valid in server component props; use className with style blocks instead
|
|
- [Phase 02-marketing-site]: lucide-react installed for marketing site icons (Home, Menu, X, ChevronLeft, ChevronRight)
|
|
- [Phase 02-marketing-site 02-02]: nodemailer pinned to ^7.0.7 — v8 conflicts with next-auth@5.0.0-beta.30 peerOptional dep
|
|
- [Phase 02-marketing-site 02-02]: useActionState imported from 'react' not 'react-dom' — React 19 canonical API (useFormState removed in React 19)
|
|
- [Phase 02-marketing-site 02-02]: Honeypot silent success pattern — bots receive status:success without email sent, preventing bot discovery of rejection
|
|
- [Phase 03-agent-portal-shell]: documentStatusEnum exported before documents table in schema.ts — pgEnum must precede referencing table or drizzle-kit may omit CREATE TYPE from migration
|
|
- [Phase 03-agent-portal-shell]: Portal route protection: add new prefix to both middleware.ts matcher array AND auth.config.ts authorized callback isPortalRoute check — mirrors existing /agent pattern
|
|
- [Phase 03-agent-portal-shell]: Post-login redirect changed from /agent/dashboard to /portal/dashboard — agent portal lives at /portal prefix going forward
|
|
- [Phase 03-agent-portal-shell]: Zod v4 uses .issues not .errors for ZodError — updated plan-specified .errors[0].message to .issues[0].message in client server actions
|
|
- [Phase 03-agent-portal-shell]: updateClient uses bind pattern (id pre-bound) so useActionState passes prevState + formData as remaining args — caller does updateClient.bind(null, clientId)
|
|
- [Phase 03-agent-portal-shell]: PortalNav is a client component (usePathname requires use client); active link state driven by pathname.startsWith(href) with gold border-b-2 underline
|
|
- [Phase 03-agent-portal-shell]: DashboardFilters extracted to separate file — use client directive must be at file top in Next.js, cannot be inlined inside server component file
|
|
- [Phase 03-agent-portal-shell]: ClientsPageClient extracted to _components/ClientsPageClient.tsx for cleaner server/client split following project convention
|
|
- [Phase 03-agent-portal-shell]: Seed script requires DOTENV_CONFIG_PATH=.env.local — dotenv/config reads .env by default but project uses .env.local
|
|
- [Phase 03-agent-portal-shell 03-04]: ClientProfileClient extracted to _components/ClientProfileClient.tsx (not inlined) — consistent with project convention for client sub-components
|
|
- [Phase 03-agent-portal-shell 03-04]: deleteClient called directly from async event handler in client component — Next.js 15+ supports calling server actions as async functions without form wrappers
|
|
- [Phase 03-agent-portal-shell 03-04]: ConfirmDialog message constructed with client name inline — reusable with title + message string props, no JSX message needed
|
|
- [Phase 04-pdf-ingest 04-01]: formTemplates table uses text PK (crypto.randomUUID()) — consistent with all other tables in schema.ts
|
|
- [Phase 04-pdf-ingest 04-01]: formTemplateId and filePath are nullable — custom uploads have no template; legacy document rows need no file path
|
|
- [Phase 04-pdf-ingest 04-01]: seed:forms uses onConflictDoUpdate on filename — filename is natural unique key for idempotent monthly sync re-runs
|
|
- [Phase 04-pdf-ingest]: uploads/ at project root not under public/ — PDFs never accessible as static files
|
|
- [Phase 04-pdf-ingest]: Relative paths stored in DB (clients/{clientId}/{uuid}.pdf) — absolute paths would break on server move
|
|
- [Phase 04-pdf-ingest]: Path traversal guard on both write (POST) and read (GET /file) — prevents directory escape via malicious clientId or filePath
|
|
- [Phase 04-pdf-ingest]: react-pdf v9 requires transpilePackages in next.config.ts — ships as ESM, Next.js webpack must transpile
|
|
- [Phase 04-pdf-ingest]: pdfjs worker uses new URL(import.meta.url) pattern — no CDN URL; works in local/Docker environments without internet access
|
|
- [Phase 04-pdf-ingest]: documentsRelations added to schema.ts — required for Drizzle db.query relational API with-relations support
|
|
- [Phase 04-pdf-ingest 04-04]: Phase 4 declared complete after human agent verified all 7 browser verification steps pass — forms library, modal, PDF render, file storage, and auth guards confirmed working
|
|
- [Phase 05-pdf-fill-and-field-mapping 05-01]: @cantoo/pdf-lib used instead of pdf-lib — packages conflict; @cantoo is the maintained fork with same API
|
|
- [Phase 05-pdf-fill-and-field-mapping 05-01]: signatureFields and textFillData stored as JSONB in documents table — flexible schema for field arrays and key/value maps without additional tables
|
|
- [Phase 05-pdf-fill-and-field-mapping 05-01]: Atomic write (tmp → rename) for prepared PDFs — prevents corrupting source PDF on partial write failure
|
|
- [Phase 05-pdf-fill-and-field-mapping 05-01]: form.flatten() called BEFORE drawing signature rectangles — required order; if reversed, AcroForm overlay obscures drawn rectangles
|
|
- [Phase 05-pdf-fill-and-field-mapping 05-01]: jest + ts-jest chosen for unit tests — straightforward TypeScript test support without ESM complications for coordinate formula tests
|
|
- [Phase 05-pdf-fill-and-field-mapping 05-01]: Y-flip formula pdfY = ((renderedH - screenY) / renderedH) * originalHeight is scale-invariant — verified at 1:1 and 50% zoom in test suite
|
|
- [Phase 05-pdf-fill-and-field-mapping 05-02]: DragOverlay used for ghost rendering — avoids transform-based dragging which breaks coordinate math relative to droppable container
|
|
- [Phase 05-pdf-fill-and-field-mapping 05-02]: containerRef.getBoundingClientRect() called at drop time (not stale pageInfo.width) — captures current rendered size after zoom changes
|
|
- [Phase 05-pdf-fill-and-field-mapping 05-02]: activatorEvent + delta pattern for final drop coordinates — activatorEvent gives client position at drag start, delta gives displacement
|
|
- [Phase 05-pdf-fill-and-field-mapping 05-02]: top: top - heightPx on overlay divs — pdfToScreenCoords returns y of bottom-left corner; must shift up by field height for DOM top-left origin
|
|
- [Phase 05-pdf-fill-and-field-mapping]: PreparePanel canPrepare guard: only show prepare form for Draft status — read-only message for Sent/Signed
|
|
- [Phase 05-pdf-fill-and-field-mapping]: currentClientId defaults to doc.assignedClientId ?? doc.clientId — allows reassigning client before preparing
|
|
- [Phase 06-signing-flow 06-01]: SIGNING_JWT_SECRET uses real openssl rand -base64 32 value (not placeholder) — generated at plan execution time
|
|
- [Phase 06-signing-flow 06-01]: auditEventTypeEnum defined before auditEvents table in schema.ts — pgEnum must precede referencing table (established Phase 3 pattern)
|
|
- [Phase 06-signing-flow 06-01]: Signing utilities live in src/lib/signing/ — server-only, never import from client components
|
|
- [Phase 06-signing-flow 06-01]: JWT jti stored in signingTokens table on createSigningToken — enables one-time-use enforcement in later plans
|
|
- [Phase 06-signing-flow 06-01]: SHA-256 hash computed from disk after atomic rename — never from in-memory bytes (LEGAL-02)
|
|
- [Phase 06-signing-flow]: Sender address hardcoded as teressa@teressacopelandhomes.com — matches brand identity requirement in CONTEXT.md
|
|
- [Phase 06-signing-flow]: sendMail failure triggers 502 without DB status update — document stays in current state if email delivery fails
|
|
- [Phase 06-signing-flow]: Status update in send/route.ts guarded by status=Draft — prevents downgrading Sent/Signed documents
|
|
- [Phase 06-signing-flow]: SigningPageClientWrapper uses dynamic import (ssr:false) — react-pdf requires browser APIs that cannot run server-side
|
|
- [Phase 06-signing-flow]: PDF served via /api/sign/[token]/pdf (token-authenticated) not /api/documents/[id]/file (agent-authenticated) — signing page is public
|
|
- [Phase 06-signing-flow 06-04]: signedFields changed from Set<string> to Map<string,string> (fieldId->dataURL) to support signature preview image in signed overlays
|
|
- [Phase 06-signing-flow 06-04]: POST /api/sign/[token] atomic claim via Drizzle UPDATE...WHERE isNull(usedAt).returning() — 0 rows = 409, PDF never written on race condition
|
|
- [Phase 06-signing-flow 06-04]: /sign/[token]/confirmed is static server component — token already used at this point, no re-validation needed
|
|
- [Phase 06-signing-flow 06-04]: sendAgentNotificationEmail is fire-and-forget via .then().catch() — email failure must never prevent the signing confirmation from reaching the client
|
|
- [Phase 06-signing-flow 06-05]: Download token uses purpose:'download' claim with same SIGNING_JWT_SECRET — no DB record needed for 15-min ephemeral download authorization
|
|
- [Phase 06-signing-flow 06-05]: Buffer cast to Uint8Array for Response constructor BodyInit compatibility in Next.js 16 TypeScript strict mode
|
|
- [Phase 06-signing-flow 06-05]: router.push replaces window.location.href for confirmed page navigation — SPA navigation consistent with Next.js App Router patterns
|
|
- [Phase 07-audit-trail-and-download]: Agent download token uses same SIGNING_JWT_SECRET with purpose:'agent-download' claim; 5-min TTL; no DB record needed for ephemeral presigned download authorization
|
|
- [Phase 07-audit-trail-and-download]: Token documentId vs route [id] cross-check added as defense-in-depth: valid token for doc A cannot download doc B (403)
|
|
- [Phase 07-audit-trail-and-download 07-02]: agentDownloadUrl generated in server component (page.tsx) not in PreparePanel — PreparePanel is 'use client' and cannot call createAgentDownloadToken (server-only)
|
|
- [Phase 07-audit-trail-and-download 07-02]: Download button is a plain anchor tag — browser follows href directly, Content-Disposition:attachment header in API route drives save dialog
|
|
- [Phase 07-audit-trail-and-download 07-02]: signedAt added to both dashboard and client profile queries — all document tables show consistent Date Signed column
|
|
- [Phase 07-audit-trail-and-download 07-03]: Phase 7 declared complete after human confirmation of all 4 browser verification criteria — SIGN-07 and LEGAL-03 verified working end-to-end in live browser
|
|
- [Phase 07-audit-trail-and-download]: /file route reads doc.filePath only — signedFilePath fallback removed per LEGAL-03; presigned /download?adt=[token] is sole signed PDF download path
|
|
- [Phase 07-audit-trail-and-download]: PdfViewer Download anchor wrapped in {docStatus \!== 'Signed' && ...} — toolbar download hidden for Signed docs, PDF still loads via /file for in-browser display
|
|
|
|
### 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)
|
|
- WFRMLS vendor enrollment takes 2-4 weeks — start process immediately, build Phase 2 listings with mock data while waiting (moved from Blockers)
|
|
|
|
## Session Continuity
|
|
|
|
Last session: 2026-03-21
|
|
Stopped at: Completed 07-04-PLAN.md — LEGAL-03 gap closure complete, all 28 plans done
|
|
Resume file: None
|