◈ AirEstate

Enterprise AI Property Sales Platform

Automating 500+ hours of manual real estate operations — powered by conversational AI, intelligent lead matching, and one-click multi-channel outreach.

---

Vision

Real estate agencies lose hundreds of hours every month to manual lead qualification, property-client matching, and outreach drafting. AirEstate replaces that workflow with a single, AI-native platform:

Manual Process	AirEstate Automation
Agent spends 20 min qualifying a call	ARIA qualifies in 5 conversational turns
Analyst manually matches clients to listings	Matching engine runs in < 1s on every new ingestion
BDR drafts 30 personalised WhatsApp messages	Batch outreach drafted and dispatched in one click
Property data entry from 10+ listing portals	Paste URL → AI extracts structured JSON in seconds

---

Features

🤖 ARIA — Conversational Lead Qualification

Inspired by Intercom, built with Groq

• Collects Name, Phone, Budget, Location & Urgency through natural dialogue
• Auto-qualifies leads against a $1M threshold (server-side enforced — AI label is advisory only)
• Fires a Telegram alert for High-Value leads (≥ $3M) in real-time
• Beautiful WhatsApp/Intercom-style chat UI with animated typing indicator

---

📊 Live CRM Dashboard

Real-time metrics, lead cards, AI buyer profiles

• 4 live metrics: Total Leads · Qualified · Pipeline Value · Avg. Budget
• SVG donut chart for Lead Source Distribution (no external chart library)
• Clickable lead rows → AI-generated 2-sentence buyer profile (cached, API called once per lead)
• Perfect Match pulse badge highlights leads matched to newly ingested properties
• Follow-up email generator with one click

---

🏠 Property Ingestion

Paste a URL, get structured JSON — powered by LLM scraping simulation

• Bulk URL input (one per line)
• 4-stage animated progress bar: Fetching → Parsing → Matching → Saving
• Toast notification on success: "Property added to inventory"
• Extracted fields: Title · Price · Location · SQFT · Beds/Baths · Amenities · Type

---

📤 Outreach Center — Mass Campaign

The "money shot" of the demo

1. Ingest a property → matching engine automatically identifies qualified buyers
2. Perfect Match badge pulses on matched leads in the CRM
3. Navigate to Outreach Center → collapsible match rows with WhatsApp-style message previews
4. Click Confirm & Send All → animated per-name progress bar → Telegram summary alert
5. Lead statuses update to Followed-up across the entire platform

---

🔌 Service Layer with Demo Mode

Every integration is optional — the app never crashes due to missing credentials

Service	Provider	Fallback
AI Chat	Groq (qwen-qwq-32b / llama-3.1-8b)	Hardcoded demo response
Email	Resend REST API	console.log with full payload
WhatsApp	Twilio / Meta Graph API	Simulated success, logged
Telegram	Bot API	Simulated success, logged

---

Architecture

web/
├── app/
│   ├── layout.tsx          — Root shell + ErrorBoundary
│   ├── page.tsx            — Main orchestrator (all React state)
│   ├── error.tsx           — Segment error boundary (Next.js)
│   ├── global-error.tsx    — Critical error boundary
│   └── api/
│       ├── chat/           — ARIA conversation + lead extraction
│       ├── ingest/         — URL → Groq → Property JSON + matching
│       ├── leads/          — GET / POST / DELETE (seed reset)
│       ├── properties/     — GET
│       ├── profile/        — AI buyer profile generation
│       └── outreach/       — Batch status update + WhatsApp dispatch
├── components/
│   ├── Header.tsx          — Fixed topbar (logo · status · user)
│   ├── Footer.tsx          — Version · status · links
│   ├── ChatWidget.tsx      — ARIA chat interface
│   ├── LeadDashboard.tsx   — CRM panel with metrics + lead table
│   ├── PropertyIngestor.tsx— URL input + progress + property cards
│   ├── TutorialModal.tsx   — 3-step Framer Motion modal
│   ├── OutreachPreview.tsx — Batch outreach UI
│   ├── ErrorBoundary.tsx   — Reusable class-based boundary
│   └── SkeletonLoader.tsx  — Shimmer placeholders (5 variants)
├── services/
│   ├── email.ts            — Resend + demo fallback
│   ├── whatsapp.ts         — Twilio / Meta + demo fallback
│   └── telegram.ts         — Bot API + demo fallback
├── hooks/
│   └── useLeads.ts         — Data fetching hook with optimistic updates
├── utils/
│   └── format.ts           — formatCurrency · parseBudget · cx · etc.
├── lib/
│   ├── types.ts            — All TypeScript interfaces
│   ├── db.ts               — File-backed JSON database
│   ├── groq.ts             — Groq client + stripThink()
│   ├── matching.ts         — matchLeads · draftWhatsApp · buildBatch
│   ├── mockData.ts         — 5 seed leads + 2 seed properties
│   └── prompts.ts          — ARIA_SYSTEM · PROPERTY_PARSE · PROFILE
└── tests/
    ├── __tests__/
    │   ├── matching.test.ts        — Vitest: matching engine
    │   ├── TutorialModal.test.tsx  — Vitest: component rendering
    │   └── demo-mode.test.ts       — Vitest: graceful fallback
    └── python/
        ├── matching.py             — Python mirror of TypeScript logic
        ├── conftest.py             — Shared pytest fixtures
        ├── test_matching.py        — pytest: lead-property matching
        ├── test_extraction.py      — pytest: Groq JSON extraction
        └── test_demo_mode.py       — pytest: demo mode + boundaries

---

Quick Start

Prerequisites

• Node.js 20+
• Python 3.11+ (for pytest suite)
• A free Groq API key (optional — app runs in Demo Mode without it)

1. Clone & install

git clone https://github.com/your-username/airestate.git
cd airestate/web
npm install

2. Configure environment

cp .env.local.example .env.local
# Edit .env.local — only GROQ_API_KEY is needed for full AI functionality

3. Start development server

npm run dev
# → http://localhost:3000

4. Run the test suite

# TypeScript / Vitest
npm run test

# Python / pytest (from repo root)
cd tests/python && pip install pytest pytest-cov && pytest -v

---

Environment Variables

Variable	Required	Description
GROQ_API_KEY	Recommended	Powers ARIA chat + property parsing
GROQ_MODEL	Optional	Model ID (default: llama-3.1-8b-instant)
RESEND_API_KEY	Optional	Real email dispatch via Resend
RESEND_FROM_ADDRESS	Optional	Sender address (default: aria@airestate.com)
TWILIO_ACCOUNT_SID	Optional	WhatsApp via Twilio
TWILIO_AUTH_TOKEN	Optional	Twilio authentication
TWILIO_WHATSAPP_FROM	Optional	Twilio sandbox number
WHATSAPP_PROVIDER	Optional	twilio (default) or meta
META_WHATSAPP_TOKEN	Optional	Meta Business API token
META_WHATSAPP_PHONE_ID	Optional	Meta phone number ID
TELEGRAM_BOT_TOKEN	Optional	Telegram bot for HV lead alerts
TELEGRAM_CHAT_ID	Optional	Chat/channel for notifications

All variables are optional. When unset, the relevant service logs to console and returns { ok: true, mode: 'demo' } — the UI remains fully functional.

---

CI/CD

GitHub Actions runs on every push to main and every pull request:

┌─────────────────────────────────────────┐
│  frontend                               │
│  ├── npm ci                             │
│  ├── ESLint                             │
│  ├── TypeScript typecheck (tsc --noEmit)│
│  ├── Vitest (demo mode — no API keys)   │
│  └── next build                         │
│                                         │
│  python                                 │
│  ├── pip install pytest pytest-cov      │
│  └── pytest -v (matching + extraction)  │
│                                         │
│  ci-pass (gate — requires both above)   │
└─────────────────────────────────────────┘

---

Tech Stack

Layer	Technology
Framework	Next.js 15 (App Router)
Language	TypeScript 5.5
Styling	Tailwind CSS 3.4 — custom design tokens
Animations	Framer Motion 11
Icons	Lucide React
Toasts	react-hot-toast
AI	Groq SDK (qwen-qwq-32b / llama-3.1-8b-instant)
Email	Resend REST API
WhatsApp	Twilio Business API / Meta Graph API
Telegram	Bot API (webhooks)
Database	File-backed JSON (zero-dependency, swap-ready)
TS Tests	Vitest + Testing Library + jsdom
Python Tests	pytest + pytest-cov
CI/CD	GitHub Actions

---

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/your-feature
3. Run tests before committing: npm run test && cd tests/python && pytest
4. Open a pull request — the CI gate must pass

---

License

MIT © AirEstate. Built as a portfolio demonstration of AI-native SaaS architecture.