Groundwork
Shared Reality Platform for Home Renovation Transparency
1. Executive Summary
Home renovation projects in the United States fail at an alarming rate — not because of skill deficits, but because of information asymmetry. Homeowners and contractors operate from fundamentally different realities: one tracks promises and dollars, the other tracks labor and logistics. This gap produces disputes, payment delays, project abandonment, and litigation. It disproportionately harms first-time homeowners and lower-income households who lack the experience or professional networks to navigate contractor relationships effectively.
Groundwork is a shared-reality platform that gives homeowners and contractors a single, authoritative view of project state. It does not replace professional construction software. It is a communication and accountability layer — plain enough for a first-time homeowner, respectful enough for a 22-year contractor veteran, and rigorous enough to produce documentation that holds up in a dispute.
Avg. Renovation Overrun
38%
above original budget estimate
Timeline Overrun
52%
of projects exceed original end date
Communication Cited
#1
cause of homeowner-contractor disputes
Target NPS at 6 months
50+
for both homeowner and contractor roles
Core Value Proposition
Groundwork makes project state undeniable and unambiguous. Every stakeholder — regardless of technical background — sees the same facts, updated in near-real time, with plain-language explanations of what those facts mean for their project.
2. Problem Statement
2.1 The Information Asymmetry Crisis
Home renovation is a high-stakes, low-trust industry. The average American renovation project costs $47,000 and takes 4.5 months. Yet the industry operates largely on handshakes, PDF contracts, and text messages. Key failure modes include:
- Invisible progress: Homeowners cannot distinguish "on track" from "quietly delayed" until a deadline passes.
- Verbal change orders: Scope changes agreed in conversation become disputed when the final bill arrives.
- Payment-timeline decoupling: Payments are made on calendar date rather than milestone achievement, removing accountability incentives.
- Vocabulary gap: First-time homeowners cannot advocate for themselves because they do not know what questions to ask or what answers mean.
- Contractor information overload: General contractors managing 8–12 concurrent jobs cannot respond to every homeowner inquiry promptly — and silence reads as negligence.
2.2 Equity Dimension
Experienced homeowners like Diane Kowalski self-protect through meticulous personal record-keeping. First-generation homeowners and those from communities historically excluded from homeownership — like many of Dr. Obi's research subjects — lack these reference frameworks. The information gap is not just inconvenient; it is a mechanism of economic harm.
2.3 Regulatory Fragmentation
Contractor licensing, bonding requirements, lien laws, and consumer protection statutes vary materially by state. There is no federal unified standard. This creates a compliance surface that must be addressed at the state level for any features touching legal rights, dispute processes, or contractor credential verification.
2.4 Why Existing Tools Fail
- BuilderTrend / CoConstruct: Contractor-facing tools with homeowner portals as afterthoughts. Steep learning curve. UI designed for construction professionals.
- Generic project management (Asana, Monday): No construction domain model. No compliance awareness. Burden of setup falls on non-expert user.
- Text/email: Universally used, produces discoverable record, but zero structure — impossible to query, aggregate, or present as timeline evidence.
- HomeAdvisor / Angi reviews: Post-project only. No in-project accountability layer.
3. User Personas
Experienced Homeowner
Diane Kowalski
68 years old — Retired Operations Manager
7 renovations — $840K lifetime spend
Context
- Maintains a personal tracking spreadsheet across all projects
- Has experienced two contractor abandonment incidents
- Accustomed to process discipline and audit trails from ops career
- Comfortable with technology but skeptical of tools that obscure detail
Core Needs
- Full data visibility — never summarized away from her
- Export-quality audit trail she controls independently
- Early warning signals before problems become crises
- Contract document versioning and change history
Fears
- Platform becomes vendor-controlled black box
- Data unavailable if contractor stops using the app
- Missing a red flag she would have caught in her spreadsheet
General Contractor
Marcus Webb
22 years experience — Independent GC
8–12 concurrent active jobs
Context
- Uses BuilderTrend reluctantly — finds it admin-heavy
- Prefers voice calls and on-site walkthroughs
- Manages subcontractors who are not digitally fluent
- Reputation-driven business; reviews and referrals are his pipeline
Core Needs
- Low-friction update mechanism (bulk updates, quick check-ins)
- Communication record that protects him from false claims
- Tool clients will actually use, reducing inbound calls
- Professional presentation that enhances his brand
Non-Negotiables
- Must not feel like surveillance or gotcha mechanics
- Subcontractors cannot be forced to create accounts
- Mobile-first — he is never at a desk
First-Time Homeowner
Jonas Reyes
34 years old — Works two jobs, fixer-upper purchase
First renovation — Limited construction vocabulary
Context
- Purchased fixer-upper as wealth-building strategy
- Limited time — works evening shifts, checks phone sporadically
- Does not know what "punch list," "substantial completion," or "draw" mean
- No prior professional relationship network in construction
Core Needs
- Plain language explanations of every status and term
- Proactive alerts when action is required — no polling
- Guidance on what is normal vs. what warrants concern
- Confidence to ask informed questions without embarrassment
Failure Modes to Prevent
- Overwhelm from information he cannot contextualize
- Paying for work before it is complete due to pressure
- Signing change orders without understanding implications
Housing Economist / Researcher
Dr. Adaeze Obi
Housing economist — Contractor dispute researcher
Equity advocate — Studies systemic patterns
Context
- Studies patterns of contractor disputes across demographic groups
- Documents how information asymmetry tracks with race and income
- Interested in platform data as research signal (anonymized)
- Potential advisory / legitimacy stakeholder for Groundwork
Platform Interest
- Aggregate data on dispute frequency and resolution patterns
- Whether plain-language features reduce disputes for first-time owners
- Contractor compliance transparency across geographic markets
- Ensure design choices do not introduce new equity harms
4. MVP Scope & Feature Prioritization
Scope Principle
MVP scope is defined as the minimum feature set that creates a verifiable shared reality between one homeowner and one contractor on a single active project. Everything else is post-MVP.
| Priority | Feature Area | MVP | Rationale |
|---|---|---|---|
| P0 | Shared Reality Dashboard | MVP | Core product identity. Without this, no differentiation. |
| P0 | Expected Date Engine | MVP | The most painful homeowner problem is "when will this be done?" |
| P0 | Daily Digest (plain language) | MVP | Jonas persona cannot engage with raw data. Digest is his interface. |
| P1 | Change Order Audit Trail | MVP | Dispute prevention. High frequency pain point with clear solution. |
| P1 | Contract Health Score | MVP | Single headline metric satisfies Diane without requiring deep exploration. |
| P1 | Dependency Chain Visualization | Post-MVP | High value but complex build. Defer to v1.1. |
| P2 | Contractor Transparency Profile | Post-MVP | Requires licensing API integrations by state — significant compliance work. |
| P2 | Milestone-Linked Payment Schedule | MVP | Structurally simple; high trust impact. Prevents payment disputes. |
| P2 | Passive Project Heartbeat | Post-MVP | Requires inactivity detection model — defer to v1.1. |
| P3 | Dispute Documentation Mode | Post-MVP | Legal complexity. Requires state-by-state rights research before building. |
| P3 | Situation Guide / Rights Navigator | Post-MVP | Content operation — requires legal review in each target state. |
| P3 | Plain-Language Glossary | MVP | Low effort, high Jonas-persona impact. Static content in MVP. |
4.1 MVP Definition
The Groundwork MVP will support a single project type: residential renovation with a single general contractor and one homeowner. It will ship with the following capabilities:
- Project creation, invitation, and onboarding flow
- Shared Reality Dashboard (milestone progress, budget burn, timeline)
- Expected Date Engine with confidence intervals
- Daily Digest — plain-language project summary
- Change Order creation, review, and digital acceptance
- Contract Health Score (composite index)
- Milestone-Linked Payment Schedule
- Photo documentation with milestone tagging
- Push and email notifications
- In-app plain-language glossary
- Full data export (PDF + CSV)
5. Functional Requirements — Project Setup & Onboarding
Feature Goal
Enable a homeowner or contractor to create a project, define its parameters, invite the other party, and enter a shared view within 10 minutes — without any training.
| ID | Requirement | Priority | MVP |
|---|---|---|---|
| FR-001 | The system shall allow any user to initiate project creation by providing a project name, property address, and estimated start date without requiring the other party to be present or registered. | P0 | MVP |
| FR-002 | The system shall support two distinct role types: Homeowner and Contractor. Role assignment determines which actions and views are available within a project. |
P0 | MVP |
| FR-003 | The system shall generate a unique, time-limited (72-hour) invitation link that the project creator can share via SMS, email, or copy-to-clipboard to invite the other party. The link shall be role-specific (Homeowner or Contractor). | P0 | MVP |
| FR-004 | The system shall allow the project creator to upload an existing contract document (PDF, DOCX, JPG) during onboarding. The uploaded document shall be stored with version history and be accessible to all project participants. | P0 | MVP |
| FR-005 | The system shall prompt the user to define at least three project milestones during onboarding, with an option to import a standard milestone template based on project type (kitchen, bath, addition, whole-home). Milestone templates shall include estimated duration ranges derived from industry data. | P0 | MVP |
| FR-006 | The system shall capture the contracted total cost, payment schedule type (fixed, draw-based, milestone-linked), and any retainage terms during project setup. These values shall be immutable without a formal change order after both parties accept. | P0 | MVP |
| FR-007 | The system shall present a plain-language onboarding checklist to the Homeowner role, explaining what each setup step is for and why it matters, without requiring the homeowner to possess prior construction knowledge. | P0 | MVP |
| FR-008 | The system shall allow the Contractor role to import existing project data from BuilderTrend via CSV export during onboarding to reduce re-entry burden. Imported data shall be mapped to Groundwork's data model with a review step before confirmation. | P2 | Post-MVP |
| FR-009 | The system shall require the Contractor role to acknowledge the project's contracted scope statement before gaining write access to milestone progress. This acknowledgment shall be timestamped and stored immutably. | P1 | MVP |
| FR-010 | The system shall allow the project creator to add up to three additional observers (e.g., a co-owner spouse, an independent inspector) with read-only access. Observers shall receive the Daily Digest but shall not be able to approve change orders or make payments. | P1 | Post-MVP |
6. Functional Requirements — Shared Reality Dashboard
Design Constraint
The Dashboard is the only screen both personas will view simultaneously in a conversation. It must resolve ambiguity, not create it. Every data point displayed must have a clear, traceable source.
| ID | Requirement | Priority | MVP |
|---|---|---|---|
| FR-011 | The Dashboard shall display a single, role-identical view of project state accessible to both Homeowner and Contractor. The data displayed shall be identical for both roles; only action capabilities shall differ. | P0 | MVP |
| FR-012 | The Dashboard shall display five headline metrics in persistent prominence: (1) Days Remaining to Contracted Completion, (2) Expected Completion Date with confidence interval, (3) Budget Consumed vs. Contracted Total, (4) Current Milestone and percentage complete, (5) Contract Health Score. | P0 | MVP |
| FR-013 | The Dashboard shall display a timeline view showing all milestones as a horizontal bar chart with planned vs. actual start/end dates color-coded. Milestones that are behind plan shall display in amber; milestones that are at risk of cascading delay shall display a dependency warning indicator. | P0 | MVP |
| FR-014 | The Dashboard shall display a budget burn chart showing cumulative payments made against the contracted schedule, with a projected final cost line derived from approved change orders and current burn rate. | P0 | MVP |
| FR-015 | The Dashboard shall display the count of pending, approved, and rejected change orders. Each change order shall be accessible in one tap/click from the Dashboard summary card. | P1 | MVP |
| FR-016 | The Dashboard shall display the most recent photo update uploaded by the Contractor, with its milestone tag, timestamp, and uploader identity. A photo gallery accessible from the Dashboard shall show all project photos in reverse chronological order. | P1 | MVP |
| FR-017 | All Dashboard data shall reflect the last known state as of the most recent system update. The Dashboard shall display a "Last Updated" timestamp and the identity of the user whose action triggered the last update. Data shall never appear stale without explicit indication. | P0 | MVP |
| FR-018 | The Dashboard shall render meaningfully on a mobile viewport (320px minimum width) without horizontal scrolling of primary content. The contractor's primary workflow shall be completable on mobile. | P0 | MVP |
7. Functional Requirements — Timeline & Milestones
| ID | Requirement | Priority | MVP |
|---|---|---|---|
| FR-019 | The system shall calculate an Expected Completion Date (ECD) using the following inputs: contracted end date, milestone completion velocity (actual vs. planned), count and estimated duration of approved pending change orders, and a configurable buffer factor (default: 1.0). The ECD shall be recalculated after every milestone status update. | P0 | MVP |
| FR-020 | The Expected Completion Date shall be displayed with an explicit confidence interval (e.g., "August 14 ± 9 days"). The confidence interval shall widen when: fewer than 30% of milestones are complete, two or more milestones are overdue, or unresolved change orders affect the critical path. | P0 | MVP |
| FR-021 | The Contractor role shall be able to mark a milestone as: Not Started, In Progress, Blocked (with required reason), Completed (with required photo evidence), or Awaiting Inspection. Status transitions shall be timestamped and attributed. | P0 | MVP |
| FR-022 | The Homeowner role shall be able to verify milestone completion by marking it Accepted or Disputed within a 72-hour review window after the Contractor marks it Completed. If no action is taken within 72 hours, the milestone shall auto-accept with an audit log entry noting the timeout. | P1 | MVP |
| FR-023 | The system shall support milestone dependency chains: a milestone may be marked as dependent on the completion of one or more predecessor milestones. The system shall display a warning if a dependent milestone's planned start date is within 5 days of an incomplete predecessor's planned completion date. | P1 | Post-MVP |
| FR-024 | The system shall visualize dependency chains as a directed graph (Gantt-style or network diagram, configurable). Blocked paths shall be visually distinct from clear paths. The visualization shall be interactive — tapping a milestone node shall reveal its detail card. | P1 | Post-MVP |
| FR-025 | The Contractor role shall be able to submit a formal Timeline Extension Request, specifying affected milestones, reason category (weather, material delay, labor, permit hold, homeowner request, other), estimated extension in days, and supporting documentation. The Homeowner must explicitly accept or reject the request. | P1 | MVP |
| FR-026 | The system shall maintain an immutable activity log for each milestone: every status change, photo upload, comment, and dispute action shall be recorded with actor identity, timestamp, and the previous state value. | P0 | MVP |
| FR-027 | The Contractor role shall be able to attach a "weather day" or "permit hold" marker to any calendar day, reducing the expected schedule by that day's count in ECD calculations. Weather day claims shall require a zip code and shall be cross-referenced against a public weather API for basic validation. | P2 | Post-MVP |
8. Functional Requirements — Change Order Management
Feature Goal
Every scope change — regardless of origin — shall be documented, priced, and accepted by both parties before work begins. No verbal change orders. No surprise line items.
| ID | Requirement | Priority | MVP |
|---|---|---|---|
| FR-028 | Either party shall be able to initiate a Change Order, specifying: scope description, cost delta (positive or negative), affected milestones, timeline impact in days, and whether work can begin before approval (emergency flag with explicit acknowledgment of risk). | P1 | MVP |
| FR-029 | The system shall calculate and display the cumulative effect of all approved change orders on: total contract value, expected completion date, and Contract Health Score. This cumulative view shall be visible from the change order list at all times. | P1 | MVP |
| FR-030 | A Change Order shall require explicit digital acceptance from the non-initiating party before any cost or timeline impact is applied to the project record. Acceptance shall require an active tap/click on an explicit confirmation element (no passive consent). | P1 | MVP |
| FR-031 | Each Change Order shall display a plain-language summary of its financial impact to the Homeowner role: "This change adds $X to your total project cost, bringing the new total to $Y. Your next payment of $Z is now scheduled for [date]." | P0 | MVP |
| FR-032 | The system shall maintain a full Change Order audit trail: each change order's complete history (created, revised, accepted, rejected, voided) shall be permanently accessible, exportable, and attributable. No change order record shall be deletable by any user role. | P1 | MVP |
| FR-033 | If a Change Order is rejected, the rejecting party shall be required to provide a reason from a structured category list (scope unclear, price too high, not agreed upon, timing conflict, other) plus an optional free-text note. The structured reason shall be stored for analytics. | P2 | Post-MVP |
| FR-034 | The system shall alert the Homeowner role if the cumulative approved change orders exceed 10% of the original contract value, with a plain-language explanation of what this threshold typically means in renovation projects. | P1 | MVP |
| FR-035 | Pending change orders shall be visually prominent on the Dashboard with a time-since-creation indicator. A change order pending for more than 5 business days without action shall trigger an escalation notification to both parties. | P1 | MVP |
9. Functional Requirements — Budget & Payments
| ID | Requirement | Priority | MVP |
|---|---|---|---|
| FR-036 | The system shall support three payment schedule models: (1) fixed calendar dates, (2) percentage-of-completion draws, and (3) milestone-linked releases. For milestone-linked payments, a payment shall not be releasable until the linked milestone is in Accepted status. | P2 | MVP |
| FR-037 | The system shall display a payment schedule table showing: payment number, amount, trigger condition, status (Upcoming / Due / Released / Overdue), and linked milestone (if applicable). This table shall be visible to both roles at all times. | P1 | MVP |
| FR-038 | The system shall record each payment as a manual log entry (Groundwork does not process payments in MVP). A payment log entry shall capture: amount, date paid, method (check, wire, ACH, cash, other), payer-noted memo, and a receipt upload field. Both parties shall see the payment log. | P0 | MVP |
| FR-039 | The Homeowner role shall be alerted 72 hours and 24 hours before a scheduled payment due date. The alert shall include the payment amount, the milestone or trigger condition it is linked to, and the current status of that condition. | P1 | MVP |
| FR-040 | The system shall display a Budget Summary block showing: original contracted amount, total approved change orders (positive and negative), total paid to date, remaining balance, and projected final cost (incorporating open change orders at 50% probability weighting). | P0 | MVP |
| FR-041 | The system shall support retainage tracking: if retainage terms are defined at project setup, the system shall calculate the retainage holdback amount for each payment, track the cumulative retainage held, and calculate the retainage release trigger based on substantial completion status. | P2 | Post-MVP |
| FR-042 | The system shall flag any payment log entry where the amount paid differs from the scheduled payment amount by more than 5%, prompting both parties to acknowledge the discrepancy and note its reason. Undocumented payment variances shall be visible in the audit trail. | P2 | Post-MVP |
10. Functional Requirements — Daily Digest
Jonas Persona Critical Path
The Daily Digest is the primary interface for time-constrained, low-context users. It must deliver a complete picture in under 90 seconds of reading time, in plain language, with zero assumed construction knowledge.
| ID | Requirement | Priority | MVP |
|---|---|---|---|
| FR-043 | The system shall generate a Daily Digest for each active project and deliver it to all project participants (Homeowner, Contractor, Observers) each morning at a user-configured time (default: 7:00 AM local time). The digest shall only be sent on days when there has been a project state change in the prior 24 hours, or when a time-sensitive item (payment due, milestone review pending) requires attention. | P0 | MVP |
| FR-044 | The Daily Digest shall be written in plain language at or below a Grade 8 reading level (Flesch-Kincaid). Technical terms shall not appear without an inline plain-language parenthetical. The tone shall be informative and neutral — not alarmist, not dismissive. | P0 | MVP |
| FR-045 | The Daily Digest shall contain four sections: (1) What happened yesterday, (2) What is expected today or this week, (3) What requires your attention (action items with deadlines), (4) Overall project health in one sentence. Each section shall have a clear visual header. | P0 | MVP |
| FR-046 | Each action item in the Daily Digest shall include a direct deep link to the relevant screen or item within the app. The homeowner shall be able to take any required action directly from the digest without needing to navigate the full app. | P0 | MVP |
| FR-047 | The Daily Digest shall be available in both push notification summary (140 character headline) and full-length email / in-app formats. The full format shall render correctly on email clients (Gmail, Apple Mail, Outlook) without external image loading dependencies for core content. | P1 | MVP |
| FR-048 | The Contractor's version of the Daily Digest shall include a cross-project summary block if they have multiple active Groundwork projects, showing any projects requiring action that day. This summary shall appear at the top of the digest and shall not displace the single-project content. | P2 | Post-MVP |
| FR-049 | The system shall allow users to configure digest frequency (daily, every 2 days, weekly) and delivery channel preferences (push only, email only, both) per project. Changes to these preferences shall take effect within 24 hours. | P1 | MVP |
11. Functional Requirements — Contract Health Score
| ID | Requirement | Priority | MVP |
|---|---|---|---|
| FR-050 | The system shall compute a Contract Health Score (CHS) as a composite index from 0–100. The score shall be calculated from at least five sub-dimensions: Timeline Adherence, Budget Variance, Change Order Frequency, Communication Responsiveness, and Documentation Completeness. | P1 | MVP |
| FR-051 | The CHS methodology shall be fully transparent and inspectable: users shall be able to view the exact inputs, weights, and calculation formula for the current score at any time. The methodology shall not change during an active project without notification. | P1 | MVP |
| FR-052 | The CHS shall be displayed with a trend indicator (improving / stable / declining) based on score movement over the trailing 7-day period. The trend shall require a minimum of 3 score calculations to display. | P1 | MVP |
| FR-053 | When the CHS drops below 60, the system shall generate an automatic plain-language explanation of the primary contributing factors and surface at least one suggested corrective action for each factor. Suggested actions shall link to the relevant section of the app. | P1 | MVP |
| FR-054 | The CHS shall be recalculated after every project state change event (milestone update, change order action, payment log entry, document upload). The recalculation shall complete within 5 seconds of the triggering event and update the Dashboard without a manual refresh. | P1 | MVP |
| FR-055 | The CHS history shall be stored as a time series, enabling a sparkline chart of score over the project lifetime. The chart shall be viewable from the Dashboard and exportable as part of the project data export. | P2 | Post-MVP |
11.1 Contract Health Score — Sub-dimension Specifications
| Dimension | Weight (MVP) | Inputs | Decay Condition |
|---|---|---|---|
| Timeline Adherence | 30% | Days behind plan per milestone, milestone count | Each day behind plan on any milestone: -2 pts |
| Budget Variance | 25% | Approved change orders vs. original contract value | Each 1% budget increase above 5%: -3 pts |
| Change Order Frequency | 20% | Count of change orders per milestone | More than 1 CO per milestone on average: -5 pts |
| Communication Responsiveness | 15% | Avg. response time on pending items (COs, milestone reviews) | Average response time > 48 hours: -4 pts |
| Documentation Completeness | 10% | Photo evidence per milestone, contract uploaded, payment receipts logged | Missing photo on completed milestone: -3 pts |
12. Functional Requirements — Contractor Transparency Profile
Scope Note
Contractor Profile is P2 and Post-MVP due to state licensing API complexity. The requirements below define the full-scope vision for v1.1+. MVP includes only self-reported basic info.
| ID | Requirement | Priority | MVP |
|---|---|---|---|
| FR-056 | The Contractor role shall maintain a platform profile containing: business name, years in operation, license numbers and issuing states (self-reported, with verification flag), insurance certificate (uploaded), primary trade specializations, and service areas by zip code. This profile shall be visible to any Homeowner who is in a shared project with the contractor. | P2 | MVP (self-reported) |
| FR-057 | For states where a public-facing contractor license lookup API is available, the system shall programmatically verify the license number and display a verification timestamp. For states without API access, the system shall display the self-reported data with a clear "Unverified — Self-Reported" indicator. | P2 | Post-MVP |
| FR-058 | The Contractor Profile shall display aggregate anonymized project statistics from completed Groundwork projects: average CHS on completed projects, average timeline adherence percentage, average budget variance. Statistics shall only display after a minimum of 3 completed projects to prevent profiling from single data points. | P2 | Post-MVP |
| FR-059 | The Contractor shall be able to opt out of aggregate statistics display on their public profile while retaining in-project data availability. Opt-out shall not affect their ability to use the platform or be shared in projects. | P2 | Post-MVP |
| FR-060 | If a contractor's license is found to have expired or been revoked in a supported state, the system shall surface a visible warning on any active project where that contractor is a participant. The warning shall not prevent project continuation but shall require the Homeowner to acknowledge the status. | P2 | Post-MVP |
13. Functional Requirements — Notifications & Alerts
| ID | Requirement | Priority | MVP |
|---|---|---|---|
| FR-061 | The system shall support three notification channels: in-app (persistent notification center), push notification (iOS and Android), and email. Users shall be able to configure channel preferences per notification type. At least one channel must remain active per notification type for project-critical alerts. | P0 | MVP |
| FR-062 | The system shall define at minimum the following notification event types, each configurable independently: (1) Milestone status change, (2) Change order created/updated/accepted/rejected, (3) Payment due reminder, (4) Payment logged, (5) Timeline extension request, (6) CHS threshold breach, (7) Daily Digest delivery, (8) Passive project inactivity alert, (9) Document uploaded, (10) Dispute mode activated. | P0 | MVP |
| FR-063 | Project-critical notifications (payment due, change order pending beyond 5 days, CHS below 60, dispute activated) shall be non-dismissable from push without an in-app acknowledgment. The notification shall resurface every 24 hours until acknowledged. | P1 | MVP |
| FR-064 | The Passive Project Heartbeat feature shall monitor contractor update frequency and alert the Homeowner if no milestone status update, photo upload, or project interaction has occurred in more than 7 consecutive calendar days. The alert shall use neutral language and shall not imply contractor wrongdoing. | P2 | Post-MVP |
| FR-065 | All delivered notifications shall be stored in a persistent in-app notification center with read/unread state, a link to the originating event, and a retention period of at least 365 days from project start. Notifications shall not be deletable by users but shall support "mark all read." | P1 | MVP |
14. Functional Requirements — Dispute & Documentation
Legal Sensitivity
Requirements in this section must be reviewed by legal counsel before implementation. Dispute Documentation Mode creates records that may be used in litigation or regulatory proceedings. Platform language must not constitute legal advice.
| ID | Requirement | Priority | MVP |
|---|---|---|---|
| FR-066 | Either party shall be able to activate Dispute Documentation Mode on any project. Activation shall require acknowledgment that the feature records data for potential legal use, and shall notify both parties immediately. Dispute Mode shall not prevent normal project operations from continuing. | P3 | Post-MVP |
| FR-067 | When Dispute Mode is active, the system shall lock all project records as of the activation timestamp. Subsequent updates shall be recorded as new entries with a dispute-period flag; no backdating shall be permitted. The locked baseline shall be exportable as a signed PDF. | P3 | Post-MVP |
| FR-068 | The Situation Guide shall provide state-specific informational content on homeowner rights, contractor obligations, small claims filing thresholds, state licensing board contacts, and recommended first steps in a dispute. Content shall be clearly labeled as informational, not legal advice, and shall cite the source and effective date of each statute or regulation referenced. | P3 | Post-MVP |
| FR-069 | The system shall enable full project export at any time, in any project state, by either party. Export format shall be a ZIP archive containing: a PDF timeline report, CSV data of all milestones and change orders, all uploaded photos (original resolution), all uploaded documents, and a JSON data file of the complete project record. Export shall be available within 30 seconds of request for projects up to 500MB. | P0 | MVP |
| FR-070 | The Plain-Language Glossary shall be accessible from any screen in the app via a persistent help icon. The glossary shall contain at minimum 60 terms covering: contract types, payment terms, construction phases, permit types, lien rights, and industry standards. Each term entry shall be written at or below Grade 8 reading level and shall include a "why this matters" sentence. | P3 | MVP (40 terms) |
| FR-071 | Any in-app term that appears in the glossary shall be underlined with a dotted indicator, enabling tap/click to reveal its definition inline without navigation. This inline glossary shall function in the Daily Digest email format as a tooltip/expandable element. | P2 | Post-MVP |
| FR-072 | The system shall generate a Project Completion Certificate upon all milestones reaching Accepted status and all payments logged. The certificate shall be a signed PDF including project summary, all parties, contracted vs. actual timeline, contracted vs. actual cost, and CHS trajectory. Either party shall be able to download this certificate at any time after project close. | P2 | Post-MVP |
15. Non-Functional Requirements
15.1 Performance
| ID | Requirement | Metric |
|---|---|---|
| NFR-001 | Dashboard initial load time | P95 < 2.0 seconds on LTE connection |
| NFR-002 | Dashboard data refresh (subsequent loads) | P95 < 800ms |
| NFR-003 | Contract Health Score recalculation | < 5 seconds post-event trigger |
| NFR-004 | Photo upload (single photo, up to 10MB) | Upload confirmation < 8 seconds on LTE |
| NFR-005 | Project export generation | < 30 seconds for projects up to 500MB total |
| NFR-006 | Daily Digest delivery | 100% of digests delivered within 15 minutes of configured time |
| NFR-007 | System availability (uptime) | 99.5% monthly uptime SLA; planned maintenance windows < 2 hours/month between 2–5 AM local |
| NFR-008 | Concurrent active projects per contractor | System shall support up to 50 concurrent projects per contractor account without degradation |
15.2 Security
| ID | Requirement | Standard / Target |
|---|---|---|
| NFR-009 | Authentication shall use industry-standard OAuth 2.0 / OIDC. Passwordless (magic link or passkey) shall be available as primary login method to reduce friction for low-frequency users (Jonas persona). | OAuth 2.0, FIDO2/WebAuthn |
| NFR-010 | All data in transit shall be encrypted. All data at rest (database, file storage) shall be encrypted with AES-256 or equivalent. | TLS 1.3 in transit; AES-256 at rest |
| NFR-011 | Financial data (payment amounts, schedules, contract values) shall be stored in a logically isolated data tier with access restricted to authenticated project participants. Financial data shall never appear in analytics pipeline without explicit aggregation and anonymization. | OWASP Top 10 compliance |
| NFR-012 | The audit trail and immutable records shall be stored in an append-only data store. No user, admin, or system process shall be capable of modifying or deleting audit records without a full database restore (forensic-quality log integrity). | WORM-equivalent storage |
| NFR-013 | All user-uploaded documents and photos shall be stored with access controls tied to project membership. A departing project participant (e.g., contractor removed from project) shall lose access to project documents within 15 minutes of removal. | Least-privilege access model |
| NFR-014 | The system shall support multi-factor authentication (MFA) as an optional but strongly encouraged setting for all accounts. MFA shall be mandatory for any account accessing three or more active projects simultaneously. | TOTP / SMS OTP |
| NFR-015 | Penetration testing shall be conducted prior to public launch and annually thereafter. Critical and high findings shall be remediated within 30 days of report delivery. | OWASP ASVS Level 2 |
15.3 Accessibility
| ID | Requirement | Standard |
|---|---|---|
| NFR-016 | All web and mobile application interfaces shall conform to WCAG 2.1 Level AA. This includes sufficient color contrast (minimum 4.5:1 for normal text), keyboard navigability, and screen reader compatibility. | WCAG 2.1 AA |
| NFR-017 | Priority and status information shall never be conveyed by color alone. Each color-coded element (milestones, health scores, budget indicators) shall also carry a text label or icon with semantic meaning accessible to screen readers. | WCAG 1.4.1 (Color) |
| NFR-018 | All form inputs, interactive elements, and navigation shall be operable via keyboard alone on web. Mobile interfaces shall support OS-native accessibility features (VoiceOver, TalkBack) for all primary user flows. | WCAG 2.1 / iOS/Android Accessibility APIs |
| NFR-019 | The Daily Digest email format shall be tested for screen reader compatibility and shall not rely on visual layout alone to convey the sequence of information. | Email accessibility best practices |
| NFR-020 | All photos uploaded to the platform shall support alt-text entry by the uploader. The system shall prompt for alt-text during upload and shall include uploaded alt-text in the accessible label for the image. | WCAG 1.1.1 (Non-text Content) |
15.4 Regulatory Compliance
| ID | Requirement | Jurisdiction |
|---|---|---|
| NFR-021 | The platform shall not serve as a licensed contractor referral service in any state where such referral activity requires a license. The platform is a project management and communication tool; all contractor-homeowner relationships are established outside the platform. | All states |
| NFR-022 | Contractor license information displayed on the platform shall be clearly labeled with source, date of last verification, and a disclaimer that Groundwork does not guarantee the accuracy or completeness of licensing information. Users shall be directed to state licensing boards for authoritative status. | All states |
| NFR-023 | The platform shall not process, hold, or transmit payment funds between parties. All payment recording is informational. The platform shall display a disclosure on the payment screen stating this limitation. | Federal (MSB regulations) |
| NFR-024 | User data, including project financial records and communications, shall be stored in the United States. The platform shall publish and adhere to a Privacy Policy meeting the requirements of the California Consumer Privacy Act (CCPA) and shall provide data deletion on request within 30 days. | CCPA (CA); applicable state privacy laws |
| NFR-025 | The Situation Guide and Rights Navigator content shall carry a legal review stamp (date reviewed, reviewing counsel) for each state-specific section. Content shall be reviewed and updated annually or when a material regulatory change occurs in a target state. | State consumer protection statutes |
16. Conceptual Data Model
Project
project_idUUID PK
namestring
property_addressAddress
statusenum
contracted_startdate
contracted_enddate
expected_completiondate
ecd_confidence_daysinteger
original_contract_valuedecimal
current_contract_valuedecimal
health_scoreinteger 0–100
project_typeenum
created_byUser FK
created_attimestamp
Milestone
milestone_idUUID PK
project_idProject FK
namestring
descriptiontext
statusenum
planned_startdate
planned_enddate
actual_startdate nullable
actual_enddate nullable
sort_orderinteger
depends_on[]Milestone FK[]
payment_triggerPayment FK nullable
accepted_attimestamp nullable
accepted_byUser FK nullable
ChangeOrder
co_idUUID PK
project_idProject FK
co_numberinteger auto-inc
initiated_byUser FK
statusenum
scope_descriptiontext
cost_deltadecimal
timeline_delta_daysinteger
affected_milestones[]Milestone FK[]
is_emergencyboolean
accepted_byUser FK nullable
accepted_attimestamp nullable
rejection_reasonenum nullable
Payment
payment_idUUID PK
project_idProject FK
scheduled_amountdecimal
actual_amountdecimal nullable
trigger_typeenum
trigger_datedate nullable
trigger_milestoneMilestone FK nullable
statusenum
paid_attimestamp nullable
methodenum nullable
receipt_urlstring nullable
logged_byUser FK nullable
retainage_helddecimal
ProjectMembership
membership_idUUID PK
project_idProject FK
user_idUser FK
roleenum
invited_attimestamp
accepted_attimestamp nullable
is_activeboolean
notification_prefsJSONB
AuditEvent
event_idUUID PK
project_idProject FK
actor_idUser FK
event_typeenum
entity_typestring
entity_idUUID
previous_stateJSONB nullable
new_stateJSONB nullable
occurred_attimestamp
ip_addressstring
Document
document_idUUID PK
project_idProject FK
uploader_idUser FK
document_typeenum
filenamestring
storage_urlstring
versioninteger
supersedesDocument FK nullable
uploaded_attimestamp
milestone_tagMilestone FK nullable
alt_textstring nullable
HealthScoreSnapshot
snapshot_idUUID PK
project_idProject FK
composite_scoreinteger 0–100
timeline_scoreinteger 0–100
budget_scoreinteger 0–100
co_frequency_scoreinteger 0–100
responsiveness_scoreinteger 0–100
documentation_scoreinteger 0–100
trigger_event_idAuditEvent FK
calculated_attimestamp
17. Integration Requirements
| Integration | Purpose | MVP | API / Provider | Notes |
|---|---|---|---|---|
| Push Notifications | iOS and Android push delivery | MVP | FCM (Android), APNs (iOS) | Required for Jonas persona's primary workflow. |
| Transactional Email | Daily Digest, invitations, alerts | MVP | SendGrid / Postmark | Must support HTML templating and deliverability monitoring. |
| File Storage | Photos, documents, exports | MVP | AWS S3 or equivalent | US-region storage required for compliance (NFR-024). |
| Weather Data API | Validate contractor weather-day claims | Post-MVP | NOAA / Open-Meteo | Lookup by zip code, historical data for prior day validation. |
| Permit Status API | Verify permit status for milestone gating | Post-MVP | City/county open data portals (varies) | Coverage highly fragmented — only largest metros have APIs. Manual input fallback required. |
| State Contractor License APIs | Verify contractor license status | Post-MVP | State licensing board APIs (varies by state) | Approximately 30 states have some form of public API or lookup. Requires state-by-state integration work. No unified federal API exists. |
| Material Delivery Tracking | Track delivery ETA for milestone dependency | Post-MVP | FedEx / UPS / project-specific supplier APIs | Future feature: contractor enters tracking number, system alerts when delivery window changes. V2 consideration. |
| Calendar Integration | Export milestone dates to user's calendar | Post-MVP | Google Calendar API / iCal export | iCal export (no auth required) is simpler and higher-value for MVP. Google Calendar API for v1.1. |
| Analytics | Product usage metrics, funnel analysis | MVP | PostHog (self-hosted) / Mixpanel | Must not collect financial data in analytics pipeline. Privacy policy must disclose analytics use. |
| Error Monitoring | Crash reporting, backend error tracking | MVP | Sentry | PII scrubbing rules required before Sentry integration is activated. |
18. Success Criteria & KPIs
18.1 MVP Launch Criteria (Go/No-Go)
- All FR-001 through FR-009, FR-011 through FR-017, FR-019 through FR-021, FR-026, FR-028 through FR-032, FR-034 through FR-040, FR-043 through FR-047, FR-049 through FR-054, FR-061 through FR-063, FR-065, FR-069, FR-070 implemented and passing automated tests.
- WCAG 2.1 AA audit completed with no critical or serious findings outstanding.
- Security penetration test completed with no Critical or High open findings.
- Daily Digest delivery rate > 99% in load testing with 1,000 concurrent active projects.
- Dashboard load time P95 < 2.0s validated in production-equivalent environment.
- Pilot with 10 homeowner-contractor pairs (minimum 5 active projects) completed with no data integrity incidents.
18.2 Product Success Metrics (6 Months Post-Launch)
| Metric | Target | Rationale |
|---|---|---|
| Net Promoter Score — Homeowner | ≥ 50 | Benchmark for product-market fit in consumer SaaS |
| Net Promoter Score — Contractor | ≥ 40 | Contractor adoption is supply-side critical; lower bar given behavioral change required |
| Daily Digest open rate | ≥ 55% | Industry average email open is 21%; 55% indicates genuine utility |
| Change order acceptance latency | Median < 18 hours | Validates that the CO flow reduces friction vs. email/text |
| Projects completing with all milestones documented | ≥ 80% | Documentation completeness is proxy for dispute risk reduction |
| Contractor update frequency | Median ≥ 3 updates/week on active projects | Signals contractor habit formation and platform adoption |
| Project export utilization | ≥ 60% of completed projects | Diane persona proxy: users who export value the record, reducing churn |
| Dispute Mode activation rate | < 5% of projects | Low rate means the platform is preventing disputes, not just documenting them |
| Month-3 retention (projects still active) | ≥ 70% | Renovation projects are multi-month; churn before completion means platform failed |
18.3 Equity Indicators (Dr. Obi Research Lens)
The following indicators will be tracked in anonymized aggregate as part of a planned research partnership:
- Change order acceptance rate variance across first-time vs. experienced homeowners (target: < 10% gap)
- Daily Digest open rate in zipcodes with median household income < $60K (target: parity within 5% of overall rate)
- Glossary usage rate correlated with project outcome (hypothesis: higher glossary usage correlates with lower dispute rates)
19. Assumptions & Risks
19.1 Assumptions
- Both parties in a project have access to a smartphone (iOS or Android) capable of running a modern mobile web app or native app.
- Contractors will accept platform-assisted communication tools if the friction cost is lower than current inbound call volume.
- The regulatory environment for contractor licensing databases will not materially restrict read access to public license data for verification purposes.
- MVP projects are single-family residential with a single general contractor. Multi-trade, multi-contractor, or commercial projects are out of scope for v1.0.
- Groundwork does not process payments and therefore does not meet the definition of a money services business (MSB) under FinCEN guidance. This assumption requires legal review before launch.
19.2 Risks
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Contractor adoption failure — Marcus persona never opens the app | High | Critical | Contractor-first mobile UX; bulk update flow; white-label branding option; direct homeowner pressure as adoption lever |
| State licensing API coverage gaps render Contractor Profile feature inadequate | High | Medium | Defer to post-MVP; design unverified self-reported state as permanent fallback, not placeholder |
| Dispute Documentation Mode creates perceived legal liability for Groundwork | Medium | High | Legal review required before build; clearly disclaim legal advice; consider removing from roadmap pending counsel |
| CHS algorithm perceived as biased against contractors (surveillance risk) | Medium | High | Full transparency on CHS methodology; contractor contribution to score explained; consider contractor appeal mechanism for disputed inputs |
| Photo evidence requirement for milestone completion creates friction for subcontractors not on platform | Medium | Medium | GC (not subcontractor) is the platform participant; GC takes photos on behalf of their crew |
| Financial data breach of payment schedules and contract values | Low | Critical | Isolated financial data tier (NFR-011); annual pen test (NFR-015); no payment processing reduces attack surface |
20. Glossary
This glossary defines terms as used within this BRD. For the in-product homeowner glossary (FR-070), see the separate Glossary Content Specification.
Change Order (CO)
A formal, documented modification to the agreed project scope, cost, or timeline, requiring acceptance by both parties.
Contract Health Score (CHS)
Groundwork's composite index (0–100) representing the overall health of a project's contractual obligations across five dimensions.
Daily Digest
An automated plain-language summary of project activity delivered to all participants each morning.
Dependency Chain
A sequence of milestones where each item cannot begin until its predecessor is complete.
Draw
A scheduled disbursement of funds tied to percentage-of-completion rather than calendar date.
Expected Completion Date (ECD)
Groundwork's calculated estimate of project completion, incorporating actual velocity, approved change orders, and buffer factor.
Milestone
A discrete, verifiable stage of project work with a defined start date, end date, completion criteria, and acceptance requirement.
MVP (Minimum Viable Product)
The minimum feature set delivering verifiable shared reality between one homeowner and one contractor on a single project.
Observer
A read-only project participant (e.g., co-owner, inspector) who receives the Daily Digest but cannot approve actions.
Passive Project Heartbeat
An automated alert triggered when no contractor project interaction occurs within a defined inactivity window (default: 7 days).
Punch List
A list of minor remaining tasks or corrections required before a project is considered substantially complete.
Retainage
A percentage of each progress payment withheld by the homeowner until substantial completion to ensure contractor fulfills all obligations.
Shared Reality
Groundwork's core design principle: both homeowner and contractor see the same facts from the same source at the same time.
Substantial Completion
The point at which a project is sufficiently complete that it can be used for its intended purpose, even if minor items remain.
Timeline Extension Request
A formal contractor-initiated request to extend one or more milestone dates, requiring homeowner acceptance.
Transparency Profile
A contractor's platform-facing record including license status, insurance, specializations, and aggregate project performance data.
Groundwork BRD v0.1 — Confidential Draft — April 3, 2026
For internal review only. Not for distribution. Requirements subject to change.