752a6b7509
- SUMMARY.md created for phase 18 plan 01 - STATE.md: plan advanced to 18-02, progress 97%, decisions recorded - ROADMAP.md: phase 18 progress updated (1/2 plans complete) - REQUIREMENTS.md: TMPL-01 marked complete
301 lines
16 KiB
Markdown
301 lines
16 KiB
Markdown
# Requirements: Teressa Copeland Homes
|
||
|
||
**Defined:** 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.
|
||
|
||
## v1 Requirements
|
||
|
||
### Marketing Site
|
||
|
||
- [x] **MKTG-01**: Visitor sees a hero section with Teressa's professional photo and warm introductory bio
|
||
- [x] **MKTG-02**: Visitor sees a "listings coming soon" placeholder section (full WFRMLS listings integration deferred to v2 pending vendor API enrollment)
|
||
- [x] **MKTG-03**: Visitor can submit a contact form with name, email, phone, and message
|
||
- [x] **MKTG-04**: Visitor sees a testimonials section with client reviews on the homepage
|
||
|
||
### Authentication
|
||
|
||
- [x] **AUTH-01**: Agent (Teressa) can log in to the portal with email and password
|
||
- [x] **AUTH-02**: Agent session persists across browser refresh and tab closes
|
||
- [x] **AUTH-03**: All agent portal routes are protected — unauthenticated users are redirected to login
|
||
- [x] **AUTH-04**: Agent can log out from any portal page
|
||
|
||
### Client Management
|
||
|
||
- [x] **CLIENT-01**: Agent can create a client record with name and email address
|
||
- [x] **CLIENT-02**: Agent can view a list of all clients
|
||
- [x] **CLIENT-03**: Agent can view a client's profile and their associated documents
|
||
|
||
### Document Management
|
||
|
||
- [x] **DOC-01**: Agent can browse and import PDF forms from the utahrealestate.com vendor API (vendor.utahrealestate.com/webapi) — investigate API capability; fall back to manual upload if forms API is not available
|
||
- [x] **DOC-02**: Forms library syncs automatically on at least a monthly basis to reflect new/updated forms
|
||
- [x] **DOC-03**: Agent can view an imported PDF document in the browser
|
||
- [x] **DOC-04**: Agent can drag-and-drop to place signature fields on any page of a PDF document
|
||
- [x] **DOC-05**: Agent can fill in text fields on a document (property address, client names, dates, prices) before sending
|
||
- [x] **DOC-06**: Agent can assign a document to a specific client and send a signing request
|
||
|
||
### Dashboard
|
||
|
||
- [x] **DASH-01**: Agent can see all documents with their current status: Draft / Sent / Viewed / Signed
|
||
- [x] **DASH-02**: Agent can see which client each document was sent to and when
|
||
|
||
|
||
### Signing Flow
|
||
|
||
- [x] **SIGN-01**: Client receives an email with a unique link to sign the document (no account required)
|
||
- [x] **SIGN-02**: Signing link expires after 72 hours and can only be used once
|
||
- [x] **SIGN-03**: Client opens the link in any browser and sees the prepared PDF with signature fields highlighted
|
||
- [x] **SIGN-04**: Client can draw a freehand signature on a canvas (works on mobile and desktop)
|
||
- [x] **SIGN-05**: Client can save a default signature and click a signature field to apply it without redrawing
|
||
- [x] **SIGN-06**: Client sees a confirmation screen after successfully signing
|
||
- [x] **SIGN-07**: Agent can download the signed PDF from the dashboard
|
||
|
||
### Legal & Compliance
|
||
|
||
- [x] **LEGAL-01**: System logs a complete audit trail for every signing ceremony — 6 server-side events: document prepared, email sent, link opened (with IP/user-agent), document viewed, signature submitted, final PDF hash computed
|
||
- [x] **LEGAL-02**: System computes and stores a SHA-256 hash of the final signed PDF immediately after signature embedding (tamper-evident record)
|
||
- [x] **LEGAL-03**: Signed PDFs are stored in private storage — never accessible via public or guessable URLs; agent downloads via authenticated presigned URLs only
|
||
- [x] **LEGAL-04**: DNS (SPF/DKIM/DMARC) configured for teressacopelandhomes.com before first signing link is sent to a real client
|
||
|
||
## v1.1 Requirements
|
||
|
||
### Client Profile Enhancement
|
||
|
||
- [x] **CLIENT-04**: Agent can add a property address to a client profile
|
||
- [x] **CLIENT-05**: Client property address is available as a pre-fill data source alongside client name
|
||
|
||
### Field Types
|
||
|
||
- [x] **FIELD-01**: Agent can place text field markers on a PDF (for typed content like names, addresses, prices)
|
||
- [x] **FIELD-02**: Agent can place checkbox field markers on a PDF
|
||
- [x] **FIELD-03**: Agent can place initials field markers on a PDF
|
||
- [x] **FIELD-04**: Agent can place date field markers that auto-fill with the signing date
|
||
|
||
### AI Assistance
|
||
|
||
- [x] **AI-01**: Agent can click one button to have AI auto-place all field types (text, checkbox, initials, date, agent signature, client signature) on a PDF in the correct positions
|
||
- [x] **AI-02**: AI pre-fills text fields with known values from the client profile (name, property address, date)
|
||
|
||
### Agent Signature
|
||
|
||
- [x] **AGENT-01**: Agent can draw and save a signature to their account profile (drawn once, reused)
|
||
- [x] **AGENT-02**: Agent can update their saved signature at any time
|
||
- [x] **AGENT-03**: Agent can place agent signature field markers on a PDF
|
||
- [x] **AGENT-04**: Agent applies their saved signature to agent signature fields during document preparation (before sending to client)
|
||
|
||
### Initials
|
||
|
||
- [x] **INIT-01**: Agent can draw and save initials to their account profile — thumbnail is displayed on the profile page (drawn once, reused)
|
||
- [x] **INIT-02**: Agent can update (replace) their saved initials at any time
|
||
- [x] **INIT-03**: Agent can place agent-initials field markers on a PDF — saved initials PNG is embedded at prepare time, invisible to the client during signing
|
||
- [x] **INIT-04**: Agent can place client-initials (existing 'initials' type) fields on a PDF — client must initial each one during the signing session (the 'initials' field type is already fully wired end-to-end; this requirement is satisfied by confirming FieldPlacer exposes the token and the signing page handles it correctly)
|
||
|
||
### Document Preview
|
||
|
||
- [x] **PREV-01**: Agent sees a live filled preview of the fully-prepared document (text filled, signatures embedded) before sending to client
|
||
|
||
### Per-Field Text Editing
|
||
|
||
- [x] **TXTF-01**: Agent can click a placed text field box on the PDF to select it and type a value for that specific field — each text field holds its own independent value (keyed by field ID)
|
||
- [x] **TXTF-02**: 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
|
||
- [x] **TXTF-03**: Text fill values entered per-field appear correctly embedded in the preview PDF and the final prepared PDF; the staleness token resets on any text field value change
|
||
|
||
## v1.2 Requirements
|
||
|
||
### Multi-Signer
|
||
|
||
- [x] **MSIGN-01**: Agent can add named signers to a document by email address from PreparePanel before sending
|
||
- [x] **MSIGN-02**: Agent can tag each signature, initials, and date field to a specific signer when placing in FieldPlacer
|
||
- [x] **MSIGN-03**: Fields in FieldPlacer are color-coded by assigned signer for visual distinction
|
||
- [ ] **MSIGN-04**: Agent cannot send a document if any client-facing field (signature, initials, date, text) has no signer assigned — send is blocked with a clear error
|
||
- [x] **MSIGN-05**: Document recipients list is built automatically from unique signer emails on placed fields (no separate manual entry)
|
||
- [x] **MSIGN-06**: All signers receive their unique signing links simultaneously when agent sends
|
||
- [x] **MSIGN-07**: Each signer's signing page shows only their own assigned fields — other signers' fields are not visible
|
||
- [x] **MSIGN-08**: Server enforces field ownership — a signer can only submit fields assigned to them
|
||
- [ ] **MSIGN-09**: Dashboard shows per-signer completion status (who has signed, who hasn't)
|
||
- [x] **MSIGN-10**: When all signers complete, agent receives a notification email
|
||
- [x] **MSIGN-11**: When all signers complete, all parties (each signer + agent) receive the final merged PDF via email link
|
||
|
||
### Deployment
|
||
|
||
- [x] **DEPLOY-01**: Application runs in Docker with a production docker-compose.yml (node:20-slim, three-stage build, not Alpine)
|
||
- [x] **DEPLOY-02**: All secrets (SMTP, database URL, API keys) are injected at container runtime via env_file — not baked into image
|
||
- [x] **DEPLOY-03**: Email delivery works correctly from the Docker container (SMTP connects to external SMTP server from container)
|
||
- [x] **DEPLOY-04**: GET /api/health returns 200 OK when the database is reachable
|
||
- [x] **DEPLOY-05**: Uploaded PDF files persist across container restarts (named Docker volume for uploads directory)
|
||
|
||
## v1.3 Requirements
|
||
|
||
### Template Management
|
||
|
||
- [x] **TMPL-01**: Agent can create a new template by selecting a PDF from the forms library
|
||
- [ ] **TMPL-02**: Agent can rename a template
|
||
- [ ] **TMPL-03**: Agent can delete a template (soft-delete — preserved if any documents were created from it)
|
||
- [ ] **TMPL-04**: Agent can view a list of all saved templates with the form name and field count
|
||
|
||
### Template Editor
|
||
|
||
- [ ] **TMPL-05**: Agent can open a template in an editor and drag-drop fields onto the PDF (reuses existing FieldPlacer)
|
||
- [ ] **TMPL-06**: Agent can use AI auto-place to populate fields on a template
|
||
- [ ] **TMPL-07**: Template fields use signer role labels (e.g. "Buyer", "Seller") instead of specific email addresses — roles are resolved to real emails only when the template is applied to a client document
|
||
- [ ] **TMPL-08**: Agent can set text hints on client-text fields in the template (shown as placeholder to signers)
|
||
- [ ] **TMPL-09**: Agent can save the template — fields and role assignments are persisted
|
||
|
||
### Apply Template to Document
|
||
|
||
- [ ] **TMPL-10**: When adding a document to a client, agent can choose "Start from template" and pick a saved template
|
||
- [ ] **TMPL-11**: Applying a template creates a document with all template fields pre-loaded (fresh field IDs, positions, types, and role assignments copied)
|
||
- [ ] **TMPL-12**: Template signer roles are automatically mapped to the client's contacts in order (primary contact → first role, co-buyer → second role); agent can override the mapping before sending
|
||
- [ ] **TMPL-13**: Text hints from the template appear as quick-fill suggestions in the document's PreparePanel
|
||
- [ ] **TMPL-14**: Editing a template after documents have been created from it does NOT retroactively change those documents — each document is an independent snapshot
|
||
|
||
### Portal Navigation
|
||
|
||
- [ ] **TMPL-15**: "Templates" appears as a top-level section in the portal navigation
|
||
- [ ] **TMPL-16**: Templates list page shows all templates with form name, field count, and last-updated date
|
||
|
||
## v2 Requirements
|
||
|
||
### MLS Integration
|
||
|
||
- **MLS-01**: Visitor sees Teressa's active property listings pulled from WFRMLS with full IDX compliance (listing broker attribution, WFRMLS disclaimer text, last-updated timestamp, NAR 2024 buyer-agent compensation disclosure) — requires WFRMLS vendor API enrollment
|
||
- **MLS-02**: Agent portal replication admin page showing sync status per RESO OData resource (Property, Member, Office, Media, OpenHouse)
|
||
- **MLS-03**: Initial full replication + automated delta syncs using `ModificationTimestamp` (hourly for Property, daily for Member/Office)
|
||
- **MLS-04**: Agent can manually trigger a sync for any resource from the admin page
|
||
|
||
### Enhanced Signing
|
||
|
||
- **SIGN-V2-01**: Client receives a reminder email if document is unsigned after 1, 3, and 7 days
|
||
- **SIGN-V2-02**: Client confirmation email with a copy of the signed document
|
||
- ~~**SIGN-V2-03**: Multiple field types~~ — promoted to v1.1 as FIELD-01 through FIELD-04
|
||
|
||
### Forms Library
|
||
|
||
- ~~**FORMS-V2-01**: Heuristic auto-detection of AcroForm signature fields~~ — superseded by v1.1 AI-01 (AI-based field placement)
|
||
- **FORMS-V2-02**: Agent can save a prepared document as a reusable template (pre-filled fields, pre-placed signature zones)
|
||
|
||
### Analytics
|
||
|
||
- **ANALYTICS-V2-01**: Agent can see when a client opened the signing link
|
||
- **ANALYTICS-V2-02**: Agent can see how long it took from send to signature
|
||
|
||
## Out of Scope
|
||
|
||
| Feature | Reason |
|
||
|---------|--------|
|
||
| Native iOS/Android app | Responsive web app handles mobile signing; no separate app needed |
|
||
| Client login portal | Clients sign via anonymous token link only; no accounts in v1 |
|
||
| DocuSign/HelloSign integration | Defeats the purpose of custom-branded, zero-per-month signing |
|
||
| Multi-agent / team support | Solo agent only; role/permissions system not needed |
|
||
| In-app PDF content editing | Real estate contracts have legally mandated language; editing creates liability |
|
||
| AI chatbot | Off-brand for a personal agent site |
|
||
| WebSocket real-time signing session | Signing is one-shot; no live session needed |
|
||
| utahrealestate.com forms scraping (automated credential login) | Likely violates ToS; use vendor API or manual upload instead |
|
||
|
||
## Open Questions
|
||
|
||
- **DOC-01 — Vendor API forms access**: Does vendor.utahrealestate.com/webapi expose the forms library (PDF downloads) in addition to listing data? This determines whether monthly sync can be automated or requires manual upload. Needs investigation in Phase 4.
|
||
- **MKTG-02 — Listings deferred**: Full WFRMLS listings integration moved to v2. v1 shows a placeholder section. When vendor API access is obtained, promote MLS-01–04 from v2 to active.
|
||
|
||
## Traceability
|
||
|
||
Which phases cover which requirements. Updated during roadmap creation.
|
||
|
||
| Requirement | Phase | Status |
|
||
|-------------|-------|--------|
|
||
| AUTH-01 | Phase 1 | Complete |
|
||
| AUTH-02 | Phase 1 | Complete |
|
||
| AUTH-03 | Phase 1 | Complete |
|
||
| AUTH-04 | Phase 1 | Complete |
|
||
| MKTG-01 | Phase 2 | Complete |
|
||
| MKTG-02 | Phase 2 | Complete |
|
||
| MKTG-03 | Phase 2 | Complete |
|
||
| MKTG-04 | Phase 2 | Complete |
|
||
| CLIENT-01 | Phase 3 | Complete |
|
||
| CLIENT-02 | Phase 3 | Complete |
|
||
| CLIENT-03 | Phase 3 | Complete |
|
||
| DASH-01 | Phase 3 | Complete |
|
||
| DASH-02 | Phase 3 | Complete |
|
||
| DOC-01 | Phase 4 | Complete |
|
||
| DOC-02 | Phase 4 | Complete |
|
||
| DOC-03 | Phase 4 | Complete |
|
||
| DOC-04 | Phase 5 | Complete |
|
||
| DOC-05 | Phase 5 | Complete |
|
||
| DOC-06 | Phase 5 | Complete |
|
||
| SIGN-01 | Phase 6 | Complete |
|
||
| SIGN-02 | Phase 6 | Complete |
|
||
| SIGN-03 | Phase 6 | Complete |
|
||
| SIGN-04 | Phase 6 | Complete |
|
||
| SIGN-05 | Phase 6 | Complete |
|
||
| SIGN-06 | Phase 6 | Complete |
|
||
| LEGAL-01 | Phase 6 | Complete |
|
||
| LEGAL-02 | Phase 6 | Complete |
|
||
| LEGAL-04 | Phase 6 | Complete |
|
||
| SIGN-07 | Phase 7 | Complete |
|
||
| LEGAL-03 | Phase 7 | Complete |
|
||
| FIELD-01 | Phase 8 | Complete |
|
||
| CLIENT-04 | Phase 9 | Complete |
|
||
| CLIENT-05 | Phase 9 | Complete |
|
||
| FIELD-01 | Phase 10 | Complete |
|
||
| FIELD-02 | Phase 10 | Complete |
|
||
| FIELD-03 | Phase 10 | Complete |
|
||
| FIELD-04 | Phase 10 | Complete |
|
||
| AGENT-01 | Phase 11 | Complete |
|
||
| AGENT-02 | Phase 11 | Complete |
|
||
| AGENT-03 | Phase 11 | Complete |
|
||
| AGENT-04 | Phase 11 | Complete |
|
||
| INIT-01 | Phase 11.1 | Complete |
|
||
| INIT-02 | Phase 11.1 | Complete |
|
||
| INIT-03 | Phase 11.1 | Complete |
|
||
| INIT-04 | Phase 11.1 | Complete |
|
||
| PREV-01 | Phase 12 | Complete |
|
||
| TXTF-01 | Phase 12.1 | Complete |
|
||
| TXTF-02 | Phase 12.1 | Complete |
|
||
| TXTF-03 | Phase 12.1 | Complete |
|
||
| AI-01 | Phase 13 | In Progress |
|
||
| AI-02 | Phase 13 | In Progress |
|
||
| MSIGN-08 | Phase 14 | Complete |
|
||
| MSIGN-05 | Phase 15 | Complete |
|
||
| MSIGN-06 | Phase 15 | Complete |
|
||
| MSIGN-07 | Phase 15 | Complete |
|
||
| MSIGN-10 | Phase 15 | Complete |
|
||
| MSIGN-11 | Phase 15 | Complete |
|
||
| MSIGN-01 | Phase 16 | Complete |
|
||
| MSIGN-02 | Phase 16 | Complete |
|
||
| MSIGN-03 | Phase 16 | Complete |
|
||
| MSIGN-04 | Phase 16 | Pending |
|
||
| MSIGN-09 | Phase 16 | Pending |
|
||
| DEPLOY-01 | Phase 17 | Complete |
|
||
| DEPLOY-02 | Phase 17 | Complete |
|
||
| DEPLOY-03 | Phase 17 | Complete |
|
||
| DEPLOY-04 | Phase 17 | Complete |
|
||
| DEPLOY-05 | Phase 17 | Complete |
|
||
| TMPL-01 | Phase 18 | Complete |
|
||
| TMPL-02 | Phase 18 | Pending |
|
||
| TMPL-03 | Phase 18 | Pending |
|
||
| TMPL-04 | Phase 18 | Pending |
|
||
| TMPL-05 | Phase 19 | Pending |
|
||
| TMPL-06 | Phase 19 | Pending |
|
||
| TMPL-07 | Phase 19 | Pending |
|
||
| TMPL-08 | Phase 19 | Pending |
|
||
| TMPL-09 | Phase 19 | Pending |
|
||
| TMPL-10 | Phase 20 | Pending |
|
||
| TMPL-11 | Phase 20 | Pending |
|
||
| TMPL-12 | Phase 20 | Pending |
|
||
| TMPL-13 | Phase 20 | Pending |
|
||
| TMPL-14 | Phase 20 | Pending |
|
||
| TMPL-15 | Phase 20 | Pending |
|
||
| TMPL-16 | Phase 20 | Pending |
|
||
|
||
**Coverage:**
|
||
- v1.0 requirements: 28 total — mapped to phases 1-7 — all Complete
|
||
- v1.1 requirements: 17 total — mapped to phases 8-13 — 15 Complete, 2 In Progress (AI-01, AI-02)
|
||
- v1.2 requirements: 16 total — mapped to phases 14-17 — all Pending
|
||
- v1.3 requirements: 16 total — mapped to phases 18-20 — all Pending
|
||
- Total mapped: 77
|
||
- Unmapped: 0
|
||
|
||
---
|
||
*Requirements defined: 2026-03-19*
|
||
*Last updated: 2026-04-06 — v1.3 traceability added (TMPL-01–04 → Phase 18, TMPL-05–09 → Phase 19, TMPL-10–16 → Phase 20)*
|