red/.planning/REQUIREMENTS.md

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

• MKTG-01: Visitor sees a hero section with Teressa's professional photo and warm introductory bio
• MKTG-02: Visitor sees a "listings coming soon" placeholder section (full WFRMLS listings integration deferred to v2 pending vendor API enrollment)
• MKTG-03: Visitor can submit a contact form with name, email, phone, and message
• MKTG-04: Visitor sees a testimonials section with client reviews on the homepage

Authentication

• AUTH-01: Agent (Teressa) can log in to the portal with email and password
• AUTH-02: Agent session persists across browser refresh and tab closes
• AUTH-03: All agent portal routes are protected — unauthenticated users are redirected to login
• AUTH-04: Agent can log out from any portal page

Client Management

• CLIENT-01: Agent can create a client record with name and email address
• CLIENT-02: Agent can view a list of all clients
• CLIENT-03: Agent can view a client's profile and their associated documents

Document Management

• 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
• DOC-02: Forms library syncs automatically on at least a monthly basis to reflect new/updated forms
• DOC-03: Agent can view an imported PDF document in the browser
• DOC-04: Agent can drag-and-drop to place signature fields on any page of a PDF document
• DOC-05: Agent can fill in text fields on a document (property address, client names, dates, prices) before sending
• DOC-06: Agent can assign a document to a specific client and send a signing request

Dashboard

• DASH-01: Agent can see all documents with their current status: Draft / Sent / Viewed / Signed
• DASH-02: Agent can see which client each document was sent to and when

Signing Flow

• SIGN-01: Client receives an email with a unique link to sign the document (no account required)
• SIGN-02: Signing link expires after 72 hours and can only be used once
• SIGN-03: Client opens the link in any browser and sees the prepared PDF with signature fields highlighted
• SIGN-04: Client can draw a freehand signature on a canvas (works on mobile and desktop)
• SIGN-05: Client can save a default signature and click a signature field to apply it without redrawing
• SIGN-06: Client sees a confirmation screen after successfully signing
• SIGN-07: Agent can download the signed PDF from the dashboard

Legal & Compliance

• 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
• LEGAL-02: System computes and stores a SHA-256 hash of the final signed PDF immediately after signature embedding (tamper-evident record)
• LEGAL-03: Signed PDFs are stored in private storage — never accessible via public or guessable URLs; agent downloads via authenticated presigned URLs only
• 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

• CLIENT-04: Agent can add a property address to a client profile
• CLIENT-05: Client property address is available as a pre-fill data source alongside client name

Field Types

• FIELD-01: Agent can place text field markers on a PDF (for typed content like names, addresses, prices)
• FIELD-02: Agent can place checkbox field markers on a PDF
• FIELD-03: Agent can place initials field markers on a PDF
• FIELD-04: Agent can place date field markers that auto-fill with the signing date

AI Assistance

• 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
• AI-02: AI pre-fills text fields with known values from the client profile (name, property address, date)

Agent Signature

• AGENT-01: Agent can draw and save a signature to their account profile (drawn once, reused)
• AGENT-02: Agent can update their saved signature at any time
• AGENT-03: Agent can place agent signature field markers on a PDF
• AGENT-04: Agent applies their saved signature to agent signature fields during document preparation (before sending to client)

Initials

• INIT-01: Agent can draw and save initials to their account profile — thumbnail is displayed on the profile page (drawn once, reused)
• INIT-02: Agent can update (replace) their saved initials at any time
• 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
• 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

• 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

• 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)
• 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
• 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

• MSIGN-01: Agent can add named signers to a document by email address from PreparePanel before sending
• MSIGN-02: Agent can tag each signature, initials, and date field to a specific signer when placing in FieldPlacer
• 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
• MSIGN-05: Document recipients list is built automatically from unique signer emails on placed fields (no separate manual entry)
• MSIGN-06: All signers receive their unique signing links simultaneously when agent sends
• MSIGN-07: Each signer's signing page shows only their own assigned fields — other signers' fields are not visible
• 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)
• MSIGN-10: When all signers complete, agent receives a notification email
• MSIGN-11: When all signers complete, all parties (each signer + agent) receive the final merged PDF via email link

Deployment

• DEPLOY-01: Application runs in Docker with a production docker-compose.yml (node:20-slim, three-stage build, not Alpine)
• DEPLOY-02: All secrets (SMTP, database URL, API keys) are injected at container runtime via env_file — not baked into image
• DEPLOY-03: Email delivery works correctly from the Docker container (SMTP connects to external SMTP server from container)
• DEPLOY-04: GET /api/health returns 200 OK when the database is reachable
• DEPLOY-05: Uploaded PDF files persist across container restarts (named Docker volume for uploads directory)

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	Pending
DEPLOY-02	Phase 17	Pending
DEPLOY-03	Phase 17	Pending
DEPLOY-04	Phase 17	Pending
DEPLOY-05	Phase 17	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
• Total mapped: 61
• Unmapped: 0

---

Requirements defined: 2026-03-19 Last updated: 2026-04-03 — v1.2 traceability added (MSIGN-01–11 → Phases 14–16, DEPLOY-01–05 → Phase 17)