sequenceDiagram
    participant User as User<br/>(Browser)
    participant Backend as Express<br/>Backend
    participant Firecrawl as Firecrawl API
    participant Sources as 99acres<br/>MagicBricks<br/>Housing.com
    participant AI as GitHub Models<br/>(GPT-4.1)
    
    User->>Backend: POST /api/ai/search<br/>(city, locality, bhk, budget, possession)
    Backend->>Backend: Build 3 search queries
    
    par Multi-Source Search
        Backend->>Firecrawl: Search: "2BHK flat for sale in Powai<br/>Mumbai under ₹2Cr site:99acres.com"
        Backend->>Firecrawl: Search: "...site:magicbricks.com"
        Backend->>Firecrawl: Search: "...site:housing.com"
    end
    
    Firecrawl->>Sources: Google API returns listing URLs
    Sources->>Firecrawl: Returns 8-10 URLs per source
    
    par Parallel Scraping
        Firecrawl->>Sources: Full browser render of each URL
        Firecrawl->>Sources: LLM extracts structured JSON
    end
    
    Backend->>Backend: Deduplicate by address + building name<br/>Code-side filter: reject rentals/PG
    
    Backend->>AI: Send clean properties for ranking
    AI->>Backend: Return ranked with insights
    
    Backend->>User: { properties, analysis, source_badges }

graph TD
    A["React Frontend<br/>(TypeScript + Vite)"] -->|POST /api/ai/search| B["Express Backend<br/>(Node.js + Helmet + CORS)"]
    
    B -->|Build 3 parallel queries| C["Firecrawl API"]
    
    C -->|Query 1:<br/>site:99acres.com| D1["99acres"]  
    C -->|Query 2:<br/>site:magicbricks.com| D2["MagicBricks"]
    C -->|Query 3:<br/>site:housing.com| D3["Housing.com"]
    
    D1 -->|8-10 URLs| E["Parallel<br/>Scraping"]
    D2 -->|8-10 URLs| E
    D3 -->|8-10 URLs| E
    
    E -->|Full browser render<br/>per property| F["Firecrawl<br/>scrapeUrl"] 
    F -->|Structured JSON| G["Backend<br/>Processing"]
    
    G -->|Deduplicate<br/>by address| H["Code-side Filter<br/>Reject rentals/PG"]
    H -->|Clean properties| I["GitHub Models<br/>GPT-4.1"]
    
    I -->|Ranked + Insights| J["Response<br/>to Frontend"]
    
    J -->|Display with<br/>source badges| K["Rich Property<br/>Cards"]
    
    B --> L[("MongoDB<br/>Atlas")]
    C --> M["User API Keys<br/>(localStorage)"]
    F --> N["ImageKit CDN<br/>(Images)"]
    
    style B fill:#4A90E2
    style E fill:#FF6B6B
    style I fill:#7C3AED
    style K fill:#10B981

flowchart LR
    subgraph Client["CLIENT LAYER"]
        FE["Frontend<br/>React 18 + TS<br/>Vercel"]
      AD["Admin Panel<br/>React + JS<br/>Vercel"]
    end
    
    subgraph API["API LAYER (Render)"]
        BE["Express.js<br/>Helmet + CORS<br/>Rate Limiter"]
    end
    
    subgraph Data["DATA & SERVICES"]
        DB[("MongoDB Atlas<br/>Database")]
        IK["ImageKit CDN<br/>Images"]
        FC["Firecrawl API<br/>Web Scraping<br/>Multi-source"]
        AI["GitHub Models<br/>GPT-4.1<br/>AI Ranking"]
        EMAIL["Brevo SMTP<br/>Email Service"]
    end
    
    FE -->|Axios| BE
    AD -->|Axios| BE
    BE -->|JWT Auth| DB
    BE -->|Upload| IK
    BE -->|Scrape| FC
    BE -->|Rank Props| AI
    BE -->|Send Mail| EMAIL
    
    style Client fill:#E8F4F8
    style API fill:#F0E8FF
    style Data fill:#FFF4E8