HOAHelper — Product Requirements Document

Section 01

Executive Summary

Product Vision

HOAHelper is the AI-powered community management platform built specifically for HOAs — not another generic management suite. It solves one high-frequency problem exceptionally well: getting residents accurate answers to bylaw questions instantly, while giving gate guards real-time AI-guided entry decisions. The core differentiator is document grounding: every answer cites the community's actual CC&Rs, not generic HOA advice.

Strategic Alignment

HOAHelper targets a chronic, underserved pain point in a market growing at 10.8% annually. Existing competitors (Buildium, TownSq, HOALife) address accounting and maintenance — not Q&A automation or AI-guided gate security. HOAHelper enters a genuine whitespace with a working product, no meaningful direct competitor, and a distribution channel (Facebook HOA groups, r/HOA) with demonstrated demand signal.

80%

Routine questions handled automatically (no board needed)

<5s

AI response time for resident bylaw questions

20%

Target trial-to-paid conversion rate

<$100

Target customer acquisition cost

Resource Overview

Item	Current State	Remaining	Target Date
Core product (3 portals)	Complete	None	Done ✓
Stripe billing integration	Not started	8–10 days dev	Day 14
Magic link / email auth	Not started	3–4 days dev	Day 10
Favicon, OG, PWA manifest	Not started	1 day dev	Day 5
Production deployment	Partial	4 hrs config	Day 7
Paid customer acquisition	Not started	Ongoing — $90–165/day	Day 31+
500 paying communities	Target	GTM execution	Month 18

Section 02

Problem Statement & Opportunity

The Problem — Quantified

The average HOA board member spends 10+ unpaid hours/month answering repetitive resident questions
43,000 members in r/HOA actively discuss management frustration — "chronic, increasing" pain signal
Residents wait 2–5 days for answers to simple questions (pool hours, parking, pet policy)
Gate guards make inconsistent entry decisions with no documented process — creating legal liability
Willingness to pay score: 9/10 — board members are actively seeking solutions
Current solutions score: 5/10 — HOA software doesn't address Q&A automation

The Opportunity — Sized

370,000 HOAs in the US — all have this problem
Market growing at 10.8% annually — new communities being formed constantly
Addressable revenue at $9/mo: $40M ARR at 1% market penetration
No direct competitor in AI-powered, document-grounded HOA Q&A
Opportunity score: 9/10 — first-mover window is open now
Path to $1M ARR requires just ~9,300 communities (2.5% of market)

Competitive Landscape

Competitor	Primary Focus	AI Q&A	Guard Portal	Price	HOAHelper Advantage
Buildium	Accounting, maintenance	None	None	$$$	Purpose-built Q&A; fraction of the cost
TownSq	Communications, voting	None	None	$$	Document-grounded AI vs. static FAQ
HOALife	Maintenance, violations	None	None	$$	Gate security + AI bundled
Generic chatbots	General customer service	Generic	None	$$$	HOA-specific; cites actual bylaws
HOAHelper	Q&A + gate security	Document-grounded	AI + DL scan	$9/mo	Only platform doing all three

Success Criteria — How We Know It's Working

Primary Metrics

Trial-to-paid conversion ≥ 20%
Monthly churn < 5%
CAC < $100
80%+ auto-resolution rate on resident questions

Milestone Targets

Day 30: 3 paying communities
Day 90: 25 paying communities, $2,250 MRR
Month 18: 500 paying communities
ARR target: $54,000 (subs only) + upsells

Section 03

User Requirements & Stories

Persona 1 — HOA Board Admin (Primary Buyer)

Profile

Age 45–65 · Volunteer · Moderate tech comfort · Uses Gmail/iPhone · Works a day job; HOA is a nights/weekends burden

Goals

Stop receiving weekend texts about rules
Have a documented, defensible audit trail for gate decisions
Know the AI won't embarrass them with wrong answers

Success Signal

Goes from 30 resident texts/week to fewer than 5. Gets through a Sunday without opening the HOA group chat.

Persona 2 — Gate Guard (Daily Operator)

Profile

Age 25–55 · Hourly staff · Low-medium tech comfort · Uses Android or assigned tablet · Under pressure during busy arrival windows

Goals

Make fast, defensible entry decisions
Not get accused of inconsistency or bias
Avoid confrontational situations with uncertain visitors

Success Signal

DL scans in <3 seconds. AI check in <4 seconds. Never has to say "I'm not sure" to a visitor.

Persona 3 — HOA Resident

Profile

Age 30–70 · Homeowner · All tech levels · Uses mobile browser · Has a one-off question about what they're allowed to do

Goals

Get an answer right now, not in 3 days
Understand what section of the rules applies
Not have to awkwardly email the board president

Success Signal

Answers question in <60 seconds. Sees the exact document section cited. Doesn't need to contact the board.

Persona 4 — Property Manager (B2B Buyer)

Profile

Age 30–55 · Licensed PM · High tech comfort · Manages 5–50 communities · Evaluated at org level, not community level

Goals

Reduce escalations from client HOAs
Offer AI tools as a competitive differentiator
Standardize gate procedures across all properties

Unlock Condition

Requires multi-community accounts and white-label branding — scoped to v1.2.

Core User Stories

Epic 1 — Bylaw Q&A (Resident Chat)Must-Have

As a HOA resident,

I want to ask a question about community rules in plain language and get an immediate, accurate answer,

so that I don't have to wait days to hear back from the board or dig through a PDF I can't find.

Acceptance Criteria

Givenbylaws are uploaded and the resident is authenticated

Whena question is submitted via the chat interface

Thena response appears within 5 seconds, in plain language, citing the specific document section (e.g., "Pool Rules · Section 2.1")

Givena question whose answer is outside the uploaded bylaws

Whenthe AI processes it

Thenthe AI states it couldn't find the answer in the community documents and recommends contacting the board — no speculation, no generic HOA advice

Givena legally sensitive or emotionally charged question

Whena response is generated

Thenthe message is flagged (needs_review=true) and surfaces in the admin review queue within 60 seconds via Supabase Realtime

Epic 2 — Gate Security (Guard Portal)Must-Have

As a gate guard,

I want to scan a visitor's driver's license and get an AI security check in under 7 seconds,

so that I can make fast, consistent, defensible entry decisions without calling the board.

Acceptance Criteria

Givena US driver's license with a valid PDF417 barcode

When"Scan DL" is tapped and the rear camera captures the barcode

Thenfirst name, middle name, last name, DOB, DL state, and DL number auto-fill within 3 seconds

Givenvisitor form is complete

When"Run AI Security Check" is tapped

ThenAI returns { status: 'allowed'|'flagged'|'denied', notes: string } within 4 seconds. Corresponding button is highlighted. Guard's final decision is what gets logged — not the AI recommendation.

Givenentry is logged

Whenany admin views Daily Reports

Thenfull visitor record is visible with decision, AI notes, timestamp, and guard ID — available for CSV export

Epic 3 — Billing & Subscription (Admin)Must-Have · v1.1

As an HOA admin,

I want to purchase the $49 trial through a secure checkout,

so that I have full access for 3 months and can upgrade to a monthly subscription without contacting support.

Acceptance Criteria

Givennew admin completes community setup

Whenthey select the trial plan and complete Stripe Checkout

Thentrial_ends_at is set 90 days from payment, all portal features activate, and admin receives a confirmation email

Giventrial_ends_at has passed with no active subscription

Whenany user from that neighborhood accesses any portal

Thenthey see a paywall screen with upgrade options. No feature access. Admin can reactivate via Stripe without support contact.

Section 04

Functional Requirements

Must Have

Resident bylaw chat with document citations
Guard portal — DL barcode scan + AI security check
Admin dashboard — stats, visitor reports, review queue
Bylaw upload: PDF text extraction + OCR fallback
Google OAuth authentication
Stripe billing: $49 trial + $9/mo subscription
Paywall enforcement (trial expiry)
RLS-secured multi-tenant database

Should Have

Magic link / email OTP authentication
Admin onboarding tooltip tour (3 steps)
Email notification for flagged review items
Favicon, PWA manifest, OG meta tags
Visitor report PDF export
AI disclaimer ("not legal advice") in chat
Sentry error monitoring
PostHog product analytics

Could Have

Multi-community accounts (Property Manager plan)
Twilio SMS integration (text-to-chat)
Bulk resident import (CSV)
Automated weekly digest email for admins
AI confidence score display on chat responses
Resident satisfaction rating on chat replies

Won't Have (v1.x)

White-label branding (v1.2+)
HOA accounting features
Maintenance request workflow
Native iOS / Android app
Multi-language support
API for third-party integrations

Feature	Input	Processing	Output	Business Rule
F-01 Bylaw upload	PDF / TXT / MD ≤ 10MB	pdfjs-dist text layer → if <50 chars → Tesseract OCR. TXT/MD: File.text()	Appended to neighborhoods.bylaws. File listed in UI.	Only admin role. File must not be empty after trim().
F-02 Resident chat	User message string + chat history	Edge fn validates JWT → builds system prompt with bylaws → calls AI provider → writes chat_messages	AI message with citation. Flagged if sensitive.	AI must only reference uploaded documents. No generic advice.
F-03 DL scan	PDF417 barcode (rear camera)	html5-qrcode → AAMVA parser (lib/aamva.ts) → normalize MMDDYYYY and YYYYMMDD dates	Auto-filled visitor form fields. All fields remain editable.	Fail gracefully on non-US / unreadable DL. Manual entry always available.
F-04 AI security check	Visitor object + entry_rules text	Edge fn → structured output { status, notes }	Pre-selected decision button. AI notes visible.	Guard override always permitted. AI recommendation ≠ logged decision.
F-05 Visitor logging	Visitor form + decision + AI notes	Zod validation → INSERT visitor_logs. guard_id = auth.uid()	Row in visitor_logs. Realtime feed update.	RLS: guards can only INSERT for their neighborhood. Not editable post-save.
F-06 Stripe billing	Admin selects plan → Stripe Checkout	create_checkout_session → webhook → update neighborhoods (trial_ends_at, subscription_status)	Trial activated. Paywall bypassed for 90 days.	No feature access without active trial or subscription.

Section 05

Technical Requirements

Architecture Overview

// HOAHelper System Architecture

Frontend SPA → React 19 + TypeScript + Vite 6 + Tailwind v4
Hosting → Vercel / Netlify / Cloudflare Pages (static, no SSR)
Auth → Supabase Auth (Google OAuth + magic link v1.1)
Database → Supabase Postgres 15, Row Level Security on all tables
Realtime → Supabase Realtime (visitor_logs → Recent Activity feed)
Storage → Supabase Storage (hoa-documents/{neighborhood_id}/...)
AI → Supabase Edge Function (Deno) → Anthropic | OpenAI | Gemini
Billing → Stripe Checkout + Webhooks → Edge Function
Scanning → html5-qrcode (PDF417) + lib/aamva.ts (AAMVA parser)
PDF parsing → pdfjs-dist (text layer) + Tesseract.js (OCR fallback)
Validation → Zod schemas at every form boundary
Testing → Vitest + Testing Library + jsdom
Monitoring → Sentry (errors) + PostHog (analytics)

Key API Endpoints — Edge Function /ai

Task	Input	Output	Auth
chat	messages[], neighborhoodId	{ content, flagged }	JWT required
analyze_visitor	visitor{}, entryRules	{ status, notes }	JWT required

AI provider keys must never reach the browser bundle. All AI calls route exclusively through the Edge Function. Provider switchable via AI_PROVIDER env var (anthropic | openai | gemini).

Database Schema — Key Tables

Table	Key Columns	RLS
neighborhoods	id, name, bylaws, entry_rules, created_by, trial_ends_at, stripe_customer_id	Own neighborhood only
staff	id, neighborhood_id, user_id, role (admin\|guard)	Same neighborhood
residents	id, neighborhood_id, name, address, phone, email	Admin only (write)
visitor_logs	id, neighborhood_id, guard_id, first/middle/last_name, dob, dl_state, dl_number, vehicle_type, license_plate, destination, decision, ai_notes, created_at	Guard INSERT; Admin SELECT
chat_messages	id, neighborhood_id, user_id, role, content, needs_review, created_at	Own messages only; Admin sees flagged

* Added in v1.1 migration

Section 06

User Experience Requirements

Design Principles

Calm authority — the product handles stressful situations (gate disputes, bylaw conflicts). The UI should never add to the tension.
One action per screen — guards need speed. Residents need simplicity. Admins need clarity.
Generous affordances — tap targets ≥ 44px on mobile. Font size ≥ 16px in guard UI.
Error recovery always possible — no action should be irreversible without a clear confirmation step.

Brand System (implemented)

Primary: Emerald #047857 — CTA buttons, logo, success states, active elements
Neutrals: Stone grays (s50–s900) — warmer than slate, less corporate than pure gray
Status: Emerald (Allowed), Amber (Flagged), Red (Denied)
Typography: Inter/system-ui (UI), generous tracking-tight for headlines
Shape: rounded-2xl cards, rounded-3xl hero panels, no sharp corners

Accessibility & Compatibility

Target: WCAG 2.1 AA compliance
Mobile: iOS 16+ (Safari), Android 12+ (Chrome)
Desktop: Chrome 110+, Safari 16+, Firefox 110+
Screen sizes: 320px → 1440px
DL scan: rear camera required. Works without BarcodeDetector (Safari fallback via zxing)
Error messages: plain language, actionable, non-technical

Loading & Error State Standards

Context	Loading State	Error State	Empty State
AI chat response	Animated 3-dot typing indicator in message bubble	Toast: "Couldn't get a response — please try again." Retry button visible.	"Upload bylaws to enable the chat assistant."
DL barcode scan	"Scanning… point at barcode on back of license"	"Could not read barcode — enter details manually"	N/A (camera always active)
OCR upload	"Processing scanned document… up to 60 seconds"	Toast: "OCR failed — try pasting text directly"	N/A
Dashboard stats	Skeleton cards (stone-100, no numbers)	Toast: "Couldn't load stats — refresh to try again"	Zeroed stats with "Get started" CTA
AI security check	Button disabled + spinner: "Checking…"	"AI check unavailable — decide manually." Buttons remain active.	N/A

Section 07

Non-Functional Requirements

Performance Targets

Metric	Target
Chat AI response	< 5s p95
Guard AI security check	< 4s p95
DL scan → form fill	< 3s
PDF text extraction	< 10s
Tesseract OCR	< 60s
Page FCP	< 2.5s
Dashboard data	< 1.5s
Uptime target	99.5%

Security Requirements

All AI provider keys: Edge Function only — never in browser bundle
RLS enforced on all 5 database tables — neighborhood isolation
Strict Content Security Policy: no inline scripts, no wildcard origins
Auth: Google OAuth (current) + magic link (v1.1) via Supabase
JWT validation inside Edge Function via supabase.auth.getUser()
All DB access gated by current_neighborhood_id() and current_role() helper functions
No sensitive data (DL numbers, DOB) returned in API responses beyond the current session
Full audit trail: every visitor_logs entry includes guard_id, timestamp, decision, AI notes

Scalability & Reliability

Supabase scales horizontally — no infrastructure changes needed to 10,000 communities
AI provider is switchable via env var — no code changes for provider migration
Edge Functions are stateless — auto-scale with demand
Tesseract OCR is client-side — zero server cost regardless of upload volume
Realtime subscriptions: Supabase handles WebSocket scaling
No multi-tenancy risk: neighborhood_id FK on every row prevents data bleed
Database backups: enable Supabase daily backups before first paying customer

Legal / Compliance note: HOAHelper is not a legal service. The AI disclaimer ("responses should not be considered legal advice") must be visible in the chat interface before launch. Terms of Service must explicitly disclaim legal liability for AI-generated answers. Consult a lawyer before approaching property management firms with white-label offerings.

Section 08

Success Metrics & Analytics

Primary KPI Dashboard

KPI	Baseline	Day 90 Target	Month 18 Target	Alert Threshold
Paying communities	0	25	500	Alert if < 5 by Day 90
MRR	$0	$2,250	$54,000+	Alert if growth < 10% MoM
Trial-to-paid conversion	—	≥ 20%	≥ 20%	Alert if < 10%
Monthly churn	—	< 5%	< 3%	Alert if > 8%
CAC	—	< $100	< $75	Alert if > $150
Auto-resolution rate	0%	≥ 80%	≥ 85%	Alert if < 70%
Bylaws upload rate (of signups)	—	≥ 80%	≥ 85%	Alert if < 70% — activation problem
Guard portal daily entries	—	≥ 5/community	≥ 8/community	Alert if < 2 — adoption problem

Analytics Implementation — PostHog Events to Track

Activation Events

community_created
bylaws_uploaded (+ file type)
bylaws_upload_failed
first_chat_message_sent
guard_portal_first_entry
stripe_checkout_started
stripe_checkout_completed

Engagement Events

chat_message_sent (daily)
dl_scan_attempted
dl_scan_succeeded / failed
ai_security_check_run
visitor_entry_logged (+ decision)
review_queue_item_reviewed
visitor_report_csv_exported

Section 09

Implementation Plan

Phase 0

Core product

Phase 1

Make sellable

Phase 2

Acquire customers

Phase 3

Learn & grow

v1.2

Multi-community

Phase	Days	Key Deliverables	Milestone
Phase 0 — Core Complete	—	Admin, Guard, Resident portals. AI edge function. RLS. Google OAuth. Realtime feed.	Working product. No billing.
Phase 1 — Sellable	1–30	Stripe billing + paywall. Magic link auth. Production domain. Favicon/OG/PWA. Tesseract self-hosted. 5 beta communities. 3 paying.	First $49 in Stripe.
Phase 2 — Acquire	31–60	Facebook + Google ads live. Reddit AMA. Admin onboarding tour. Email notifications for flagged items. LinkedIn outreach to PMs.	15 paying communities · $1,350 MRR
Phase 3 — Learn	61–90	Health check calls. Premium Support upsell. Case study published. PDF export. v1.2 scope locked from data.	25 communities · $2,250 MRR
v1.2 — Multi-community	Day 91+	Property Manager plan. Multi-community accounts. Twilio SMS integration. White-label (optional).	First PM firm on contract.

⚡

Day 30 Outcome

Billing works. Product is live on hoahelper.app. 3 real communities paying. Real testimonials on landing page.

📈

Day 90 Outcome

25 paying communities. $2,250 MRR. CAC < $100 validated. First PM conversation started. v1.2 roadmap locked.

🏆

Month 18 Outcome

500 paying communities. $54K+ ARR (subs alone). First PM licensing deal. Seed funding or profitable.

Section 10

Risk Assessment & Mitigation

Risk

Likelihood

Impact

Mitigation

Admin doesn't upload bylaws after signing up — buys trial, gets no value, churns at 90 days

Medium

High

Trigger Day 1 email if bylaws field is empty. Onboarding tour step 1 = "Upload bylaws first." Track bylaws_uploaded as activation metric. Alert if <70% of signups upload within 48hrs.

Stripe billing breaks at launch — webhook misconfiguration, price ID mismatch between test/live modes

Medium

High

Test every webhook event in Stripe test mode before go-live. Use Stripe CLI for local testing. Log all webhook payloads to a stripe_events table. Manual override capability for founder.

AI generates an inaccurate answer — cites wrong rule or invents something not in the bylaws

Low

Medium

System prompt explicitly instructs: only cite uploaded documents. Legal disclaimer in chat UI. Weekly manual QA of 10 random responses. Flagging system catches sensitive questions before they become issues.

Ad CAC exceeds $100 — Facebook CPMs higher than projected, landing page conversion below target

Medium

A/B test headline and creative before scaling. Pause campaigns <0.5% CTR after 500 impressions. Reddit organic is free — prioritize it if paid is expensive early. Set hard spend cap of $150/day.

Board member resists AI adoption — "What if it gives the wrong answer to a resident?"

High

Medium

This objection is the #1 sales barrier. Handle in landing page FAQ, ad copy, and sales calls. Emphasize: every answer cites the exact section; complex questions go to human review; 3-month trial with no commitment. The question isn't "will it be perfect?" — it's "is it better than waiting 3 days?"

Competitor copies the product — Buildium or TownSq adds AI Q&A feature

Low

Medium

Incumbent inertia is real — large companies take 12–24 months to ship meaningful features. HOAHelper's moat is distribution (community trust, testimonials) and the guard portal (no competitor has this). Move fast to establish brand recognition in target communities before incumbents react.

Tesseract CDN outage (unpkg.com) — OCR breaks for all scanned PDF uploads

Low

Self-host Tesseract assets in public/tesseract/ — 1-day effort that eliminates this risk entirely. Prioritized in Day 1–3 of roadmap.

Appendix A

PRD Quality Checklist

Content Completeness

Problem clearly defined with quantified evidence

Solution aligned with user needs and business goals

All four user personas documented with success criteria

MoSCoW prioritization complete

Technical stack documented with rationale

Risks identified with mitigation strategies

Launch Readiness Gates

Core portals (Admin, Guard, Resident) functional

RLS confirmed on all 5 database tables

Stripe live mode active (not test mode)

Privacy Policy and Terms of Service live

AI legal disclaimer visible in chat UI

Sentry + PostHog installed and verified

3 paying communities before paid ad spend begins

Appendix B

Approval & Sign-off

Product Owner / Founder

_________________________

Date: ___________________

Lead Engineer

_________________________

Date: ___________________

Marketing Lead

_________________________

Date: ___________________

Legal Review (optional)

_________________________

Date: ___________________

This PRD represents the complete product definition for HOAHelper v1.0–v1.1. It supersedes any previous planning documents. Changes to Must-Have requirements require Product Owner approval. Should/Could-Have scope changes may be approved by the Lead Engineer with PM awareness. This document should be reviewed at the Day 30 and Day 90 milestones and updated with learnings from real customer data.