ZoomProp AI Platform — Progressive Product Requirements Document

---

PRD Metadata

---

v0.1 Spark — Problem & Outcomes

Problem Statement

Real estate investors and operators are drowning in fragmented data. Property listings, market analytics, portfolio financials, cap rate calculations, inspection reports, and offer negotiations live in separate, disconnected tools. A professional investor managing ten or more properties simultaneously must context-switch between Zillow for comps, spreadsheets for cap rates, email for offer negotiations, and generic CRMs for deal pipelines. None of these tools understand real estate investment intent, and none surface AI-driven insight at the moment of decision.

ZoomProp solves the vertical integration problem: it unifies property discovery, AI-powered financial analysis, portfolio management, deal pipeline automation, and intelligent alerting into a single collaborative workspace built specifically for real estate investment professionals.

Desired Outcomes

Constraints

---

v0.2 Market Definition — ICP & Segments

Ideal Customer Profile

ZoomProp targets investment-oriented real estate professionals who evaluate multiple deals per month, manage active portfolios, and operate within structured investment entities (LLCs, funds, syndicates). The platform is not a consumer home-search tool.

Segment Table

"Not For" (Explicit Exclusions)

• First-time homebuyers seeking a primary residence — no mortgage rate comparison, school district lookup, or buyer-agent matching.
• Retail consumers expecting a Zillow-like browse experience without investment intent.
• Property managers focused purely on tenant relations, rent collection, or maintenance ticketing (no tenant portal, no payment processing).
• Wholesale flippers requiring rapid MLS pull-and-push without financial modeling depth.
• International markets — image CDN allowlist, address search, and demographic data are US-centric.

---

v0.3 Commercial Model — Pricing & Positioning

Monetization Architecture

ZoomProp operates a SaaS subscription model with a freemium entry tier, evidenced by:

1. Free monthly query grant — PR #455 (3a74c26) adds a monthly free queries grant API and context integration for unpaid users, establishing a hard consumption gate before upgrade prompts.
2. Embedded Stripe checkout in onboarding — billing-setup-step.tsx and embedded-checkout.tsx present in src/app/(auth)/onboarding/_components/steps/. Legacy archive contains create-subscription/route.ts, create-checkout-session/route.ts, create-portal-session/route.ts, and stripe/webhook/route.ts, confirming Stripe is the billing processor.
3. Subscription verification gate — Legacy check-org-subscription/route.ts confirms org-level subscription checks at request time.
4. Organization-tier upsell — Clerk organizations (sign-up/organization/page.tsx) are gated behind a paid plan enabling multi-member collaboration and shared portfolio visibility.

Pricing Tiers (Inferred)

Moat Thesis

ZoomProp's defensibility rests on three compounding layers:

1. Proprietary AI context — The LangGraph-orchestrated multi-agent system (@langchain/langgraph) builds an investment-context graph per user (portfolio, watchlist, search history, geographic focus). This context is captured at onboarding (platform-goals-step.tsx, investment-interests-step.tsx, geographic-focus-step.tsx) and persisted, making AI responses more accurate the longer a user is on the platform.
2. Elasticsearch property index — @elastic/elasticsearch ^8.18.2 powers sub-second property search with investment-intent query parsing, a capability consumer portals don't optimize for.
3. Network effects within organizations — Shared deal pipelines, alert assignments (/api/alert-filters/assignments), and collaborative AI conversations create switching costs for investment teams as institutional knowledge accumulates on the platform.

---

v0.4 User Journeys

UJ-001: New Investor Onboarding

Actor: First-time registrant (SEG-001 or SEG-002) Entry: src/app/(auth)/sign-up/[[...sign-up]]/page.tsx

1. User completes Clerk sign-up (email + password or OAuth).
2. Redirected to src/app/(auth)/onboarding/page.tsx — onboarding wizard initiates.
3. onboarding-wizard.tsx steps through: property-ownership-step → portfolio-count-step → platform-goals-step → investment-interests-step → geographic-focus-step → co-investment-step → portfolio-setup-step → identity-verification-step → billing-setup-step → onboarding-summary-step.
4. billing-setup-step.tsx triggers Stripe embedded checkout (embedded-checkout.tsx) for Pro/Org upgrade; free users pass through.
5. Progress tracked via progress-indicator.tsx and top-progress-indicator.tsx.
6. Completion lands on src/app/(auth)/onboarding/complete/page.tsx then success/page.tsx.
7. Auth redirect handled at src/app/(auth)/auth/redirect/page.tsx.

Success Metric: Onboarding funnel completion rate to success/page.tsx.

---

UJ-002: Property Discovery via AI-Powered Search

Actor: Authenticated investor (any segment) Entry: Dashboard → Discover page

1. User opens the Discover map view powered by Mapbox GL Draw (@mapbox/mapbox-gl-draw).
2. User draws a polygon or selects a region; Elasticsearch address/region search (archive/legacy-api-backup/elastic-search/) returns matching properties.
3. User applies sophisticated filters (price range, property type, min cap rate) — documented in context/SOPHISTICATED_PROPERTY_FILTERS_USAGE.md.
4. AI intent detection fires via /api/ai/intent to classify the user's search goal and pre-populate relevant filters.
5. AI suggestion prompts appear via /api/ai/suggestions; user selects a saved AI search template via /api/ai-search-templates.
6. Properties render on map with cap rate overlays; user pins a property to collections or watchlist.

Success Metric: Search-to-property-detail click-through rate.

---

UJ-003: AI Chat — Deal Analysis Session

Actor: Pro or Org subscriber (SEG-001 through SEG-004) Entry: Chat interface (AI chat sidebar or full-screen shell)

1. User opens a new conversation; system loads portfolio context via /api/ai/analysis pre-populating the LangGraph context window.
2. User types or selects a quick-action prompt (e.g., "Analyze this property's cap rate against my portfolio average").
3. /api/ai/chat streams a response using @ai-sdk/react streaming hooks with real-time token display.
4. Multi-persona support (/api/ai/personas) allows switching between "Investment Analyst," "Market Scout," and "Due Diligence" personas depending on task.
5. Conversation title auto-generated via /api/ai/generate-title; full history persisted to /api/ai/conversations.
6. User can trigger a property investigation from chat via /api/actions/analyze-property-investigation.
7. Free-tier users hitting monthly query limit receive an inline upgrade prompt (PR #455).

Success Metric: Messages per session, conversation-to-action conversion (watchlist add, alert create).

---

UJ-004: Cap Rate Calculation & Financial Analysis

Actor: Any authenticated investor Entry: Property detail page → Financial Analysis tab

1. User views a property; system pre-fills constMonthlyRent from AI rent estimate (via /api/ai/commercial-estimates).
2. CapRateBaseSchema (Zod) validates inputs: constVacancy (default 5%), constOperExpenses (default 30%), constResEstimate (default 5%), constClosingCosts (default 2%).
3. User adjusts assumptions; cap rate recalculates client-side in real time against listPrice.
4. User requests AI-enhanced offer analysis via /api/ai/offer-analysis, which factors in market comps and portfolio context.
5. Maintenance cost projection generated via /api/ai/maintenance-analysis.
6. Property inspection analysis available via /api/ai/property-inspection-analysis for properties with uploaded inspection documents.
7. User saves analysis to a collection; alert can be set for price-drop events.

Success Metric: Cap rate calculation completion rate; downstream offer analysis API call rate.

---

UJ-005: Alert Configuration & Market Monitoring

Actor: Pro or Org subscriber Entry: Dashboard → Alerts section (src/app/(dashboard)/alerts/)

1. User opens alert-center-dashboard.tsx showing active alerts, history, and delivery settings.
2. User creates a new alert via alert-config-form.tsx, selecting scope (alert-scope-selector.tsx) — property-level, collection-level, or market-level.
3. Filter criteria set via alert-filters.tsx; criteria assigned to properties via /api/alert-filters/assignments.
4. Delivery preferences configured via alert-delivery-settings.tsx and persisted to /api/alerts/preferences.
5. Alert triggers evaluated server-side via /api/alerts/trigger; delivery routed through Knock (@knocklabs/node) for in-app, email, and push notification.
6. Alert history displayed in alert-history-timeline.tsx; bulk actions (archive/unarchive) available via /api/alerts/messages/archive and /api/alerts/messages/unarchive.
7. Org-level alert user management via /api/alerts/users.

Success Metric: Alerts configured per active user; alert click-through rate to property action.

---

UJ-006: Portfolio Analytics & Performance Monitoring

Actor: SEG-002 syndicators, SEG-003 firms Entry: Dashboard → Analytics

1. User views portfolio-level KPIs via /api/analytics/portfolio.
2. Appreciation distribution chart rendered from /api/analytics/appreciation-distribution.
3. Market comparison data loaded from /api/analytics/markets.
4. Individual property performance tracked via /api/analytics/properties and /api/analytics/performance.
5. AI performance monitoring report generated via /api/ai/performance-monitoring.
6. Automation analytics reviewed via /api/automation/analytics; deal pipeline board configured via /api/automation/board-config.
7. Dashboard summary aggregated via /api/analytics-dashboard.

Success Metric: Dashboard weekly active users; analytics API call volume per org.

---

UJ-007: Organization Setup & Team Collaboration

Actor: Deal principal (SEG-002, SEG-003) Entry: src/app/(auth)/sign-up/organization/page.tsx

1. Principal creates a Clerk organization; subscription upgraded to Team/Org tier via /api/auth/active-org.
2. Team members invited (legacy clerk/organization/invite route in archive).
3. Business verification initiated via business-verification-form.tsx (Middesk integration in legacy archive).
4. Shared portfolio, collections, and alert filters become visible across org members.
5. AI persona assignments differentiated by role (analyst vs. principal) via /api/ai/personas.
6. Active org session managed via /api/auth/active-org; session state via /api/auth/session.

Success Metric: Org-level multi-user activation rate; shared resource (alert, collection, portfolio) usage per org.

---

v0.5 Red Team Review

Risk Register

---

v0.6 Architecture

System Architecture Overview

ZoomProp is a Next.js 15 full-stack application using the App Router, with AI capabilities delivered through a multi-layer LLM stack and property data served from a zp-fetch-service microservice.

Browser (Next.js App Router)
    │
    ├── Clerk Auth (TECH-011)
    ├── Radix UI + Tailwind CSS components
    ├── Mapbox GL Draw / Google Maps (TECH-007)
    ├── @ai-sdk/react streaming chat (TECH-009)
    └── Knock in-app notifications (TECH-013)
         │
         ▼
Next.js API Routes (src/app/api/)
    │
    ├── /api/ai/* ──────────────► LangChain / LangGraph (TECH-009)
    │                               └─► OpenAI GPT-4o (TECH-010)
    ├── /api/alerts/* ──────────► Knock Node SDK (TECH-013)
    ├── /api/analytics/* ───────► ZoomProp Backend API (TECH-014)
    ├── /api/auth/* ────────────► Clerk Backend (TECH-011)
    └── /api/automation/* ──────► ZoomProp Backend API (TECH-014)
         │
         ▼
External Services
    ├── Elasticsearch (TECH-008) — property search index
    ├── Stripe (TECH-015) — billing and subscriptions
    ├── Clerk (TECH-011) — identity, organizations, sessions
    ├── ZoomProp Backend API (NEXT_PUBLIC_ZOOMPROP_API_URL_V1)
    └── zp-fetch-service (Dockerfile) — data fetching microservice

Technical Reference

API Surface Reference