AI-real-estate-lead-orchehestrator

byRishiraj Bhattacharjee

# Product Requirements Document (PRD) # AI Lead Journey Operating System for Real Estate Developers **Version:** 1.0 **Status:** In Development **Author:** Rishiraj Bhattacharjee **Product Type:** SaaS Platform --- # 1. Vision Build an AI-powered operating system that automatically manages, nurtures, tracks, and converts real estate enquiries into booked site visits while providing complete auditability, deterministic workflows, and human oversight. The platform should behave like an intelligent sales coordinator—not just a chatbot. It should understand customer intent, decide the appropriate business action, execute follow-ups automatically, and maintain a complete history explaining every decision. --- # 2. Problem Statement Real estate developers generate hundreds of enquiries every month from multiple channels. Common challenges include: * Slow response times * Manual WhatsApp follow-ups * Sales executives forgetting leads * Leads becoming cold * No visibility into why a lead stopped converting * No structured understanding of customer intent * CRM records becoming inconsistent over time Existing CRMs only store information. They do not actively manage the customer journey. --- # 3. Product Goal Automatically move every lead through a structured customer journey: ```text Lead Captured ↓ Immediate Engagement ↓ Intent Understanding ↓ Automated Follow-up ↓ Human Intervention (when required) ↓ Site Visit ↓ Booking ``` while ensuring every decision is: * explainable * deterministic * replayable * auditable --- # 4. Core Principles ## 4.1 Workflow First Business rules drive decisions. AI provides inputs—not business decisions. --- ## 4.2 AI as an Assistant AI determines: * customer intent * conversation understanding AI never directly updates business state. --- ## 4.3 Deterministic Workflow Given the same inputs: ```text State + Intent + Trigger + Policy ``` the workflow must always produce the same outcome. --- ## 4.4 Immutable History Nothing is overwritten. Every meaningful action becomes an immutable transition. --- ## 4.5 Replayability The system must always answer: > Why is this lead in its current state? using historical transitions alone. --- # 5. High-Level Architecture ```text Lead Sources │ ▼ Lead Intake │ ▼ Conversation Engine │ ▼ Intent Resolution Pipeline │ ▼ Workflow Engine │ ▼ Execution Planner │ ▼ Workflow Coordinator │ ▼ Infrastructure │ ▼ Transition History │ ▼ Replay Engine │ ▼ Analytics & Reporting ``` --- # 6. User Journey ## Stage 1 — Lead Capture Lead sources: * Website * Meta Ads * Google Ads * WhatsApp * Property Portals * API * Manual Entry System actions: * Create Lead * Sync CRM * Create Conversation * Create Journey * Emit Lead Captured Event --- ## Stage 2 — Initial Engagement System automatically: * sends greeting * introduces project * asks qualifying questions Journey becomes: ```text NEW ↓ ACTIVE ``` --- ## Stage 3 — Customer Reply Customer responds. Example: > "Can you send the brochure?" The workflow pauses. Message enters the Intent Resolution Pipeline. --- ## Stage 4 — Intent Resolution Pipeline: ```text Incoming Message ↓ AI Classifier ↓ Intent Validation ↓ Confidence Policy ↓ Rule-based Fallback ↓ Journey Intent ``` Example: Message: > "I'm travelling. Call me next week." Output: ```text FOLLOW_UP_NEXT_WEEK Confidence: 0.94 ``` --- ## Stage 5 — Workflow Decision Workflow receives: ```text Current State Intent Trigger Policy ``` Example: ```text ACTIVE + FOLLOW_UP_NEXT_WEEK + MESSAGE_RECEIVED ↓ PAUSE_JOURNEY ``` --- ## Stage 6 — Execution Execution planner creates operations. Example: * Update Journey * Schedule Timer * Send WhatsApp * Emit Event * Persist Transition Coordinator executes them transactionally. --- ## Stage 7 — Replay At any point the platform can reconstruct the journey. Example: ```text NEW ↓ ACTIVE ↓ PAUSED ↓ ACTIVE ↓ BOOKED ``` If the database differs from replay: Critical Drift is reported. --- # 7. Functional Modules ## Lead Intake Responsibilities: * Accept enquiries * Validate payload * Create Lead * Emit Lead Event --- ## Conversation Engine Responsibilities: * Maintain conversations * Store inbound/outbound messages * Manage communication channels --- ## Intent Resolution Pipeline Responsibilities: * AI classification * JSON validation * Confidence validation * Rule fallback * Intent versioning Output: ```text JourneyIntent ``` --- ## Workflow Engine Responsibilities: * Evaluate business rules * Produce deterministic outcomes * No infrastructure logic --- ## Execution Planner Responsibilities: Convert workflow outcomes into executable operations. Example: ```text Send Message Schedule Evaluation Update Journey Emit Event ``` --- ## Workflow Coordinator Responsibilities: * Execute operations * Database transactions * Event emission * Scheduling --- ## Transition History Responsibilities: Store immutable journey history. Every transition records: * previous state * new state * trigger * timestamp * reason * policy * intent metadata --- ## Replay Engine Responsibilities: * Validate history * Reconstruct snapshot * Detect drift * Generate replay report --- ## Analytics Future module. Responsibilities: * Funnel reports * Policy comparison * Conversion metrics * AI effectiveness --- # 8. Customer Journey States ```text NEW ↓ ACTIVE ↓ PAUSED ↓ BOOKED ``` Possible terminal states: * BOOKED * LOST * COMPLETED --- # 9. Events Business Events * Lead Captured * Engagement Started * Message Received * Site Visit Booked * Site Visit Cancelled Operator Events * Pause Journey * Resume Journey Timer Events * Timer Expired * Follow-up Due --- # 10. Edge Cases ## AI Failure Problem LLM unavailable. Expected Behaviour Use rule-based resolver. Workflow continues. --- ## Invalid JSON Problem Model returns malformed JSON. Expected Behaviour Reject response. Invoke fallback. --- ## Unknown Intent Problem Model invents an unsupported intent. Expected Behaviour Reject. Fallback. --- ## Low Confidence Problem Confidence below policy threshold. Expected Behaviour Fallback or mark for manual review. --- ## Duplicate Events Problem WhatsApp webhook delivered twice. Expected Behaviour Ignore duplicate processing through idempotency checks. --- ## Out-of-Order Events Problem A timer fires after the lead has already reached a terminal state. Expected Behaviour Ignore the timer and preserve the terminal journey state. --- ## Illegal State Transition Problem Someone writes directly to the database: ```text BOOKED ↓ ACTIVE ``` Expected Behaviour TransitionValidator rejects the history. Replay fails with validation errors. --- ## Database Drift Problem Current database state differs from replayed state. Expected Behaviour Generate a Replay Report with severity-based drift information. --- ## Human Intervention Problem Salesperson pauses or resumes automation. Expected Behaviour Record the action as an immutable transition and continue replay support. --- ## Policy Updates Problem Follow-up rules change over time. Expected Behaviour Historical journeys remain reproducible because transition history and policy metadata are preserved. --- ## Multilingual Messages Problem Customer responds in Hindi, Hinglish, or another supported language. Expected Behaviour Intent Resolution Pipeline classifies the intent regardless of language. If confidence remains insufficient, the system falls back to deterministic rules or manual review. --- # 11. Non-Functional Requirements ### Reliability * Deterministic workflow execution * Idempotent event handling * Transactional consistency ### Observability * Structured logs * Replay reports * Drift detection * Audit history ### Scalability * Event-driven architecture * Background workers * Horizontal scaling * Queue-based processing ### Security * Role-based access * Secure API authentication * Audit logging * Data encryption where applicable --- # 12. Success Metrics (KPIs) ### Business * Average first response time * Site visit booking rate * Lead-to-booking conversion rate * Sales executive workload reduction * Lead response SLA compliance ### AI * Intent classification accuracy * Fallback usage rate * Low-confidence rate * Manual correction rate ### Platform * Workflow success rate * Replay consistency rate * Drift detection incidents * Event processing latency * Failed execution rate --- # 13. Product Roadmap ### Phase 1 — Foundation ✅ * Lead Intake * Conversation Engine * Workflow Engine * Execution Planner * Workflow Coordinator * Transition History * Replay Engine ### Phase 2 — Intelligence * Intent Resolution Pipeline * AI Prompt Versioning * Human Review Queue * Policy Engine Enhancements ### Phase 3 — Optimisation * Journey Analytics * Policy Simulator * A/B Testing * Campaign Engine * Advanced Reporting ### Phase 4 — Enterprise * Voice AI Integration * Multi-project Support * Multi-tenant Architecture * CRM Integrations * Developer SDK & APIs --- # Product Summary The platform is an **AI Lead Journey Operating System** purpose-built for real estate developers. Rather than functioning as a simple CRM or chatbot, it orchestrates the entire lifecycle of a lead—from capture to booking—using deterministic workflows, AI-assisted intent understanding, immutable event history, and replayable state reconstruction. This architecture ensures that every automated decision is explainable, every customer interaction is traceable, and every journey can be audited, replayed, and continuously improved over time.