California Property Finder - Project Documentation

Developed by: Akbar Aman — SD6 Team Lead, IDX Exchange Pro-bono Initiative
Status: ✅ Complete & Production Ready
Live Site: https://akbar.califorsale.org
Completion Date: December 18, 2025

🎯 Project Overview

The California Property Finder is a production-ready real estate search platform featuring live MLS data, AI-powered search, natural language processing, and intelligent property recommendations. Built with PHP, MySQL, and modern JavaScript, it delivers a seamless property discovery experience.

🏆 Key Achievements

✅ Advanced NLP Search: Parse queries like "Los Angeles homes under 1 million" into precise filters
✅ Hero Section: Fixed background with smart search and gradient overlays
✅ Schema.org Markup: Full structured data for AI/RAG systems (ElevenLabs integration)
✅ localStorage Save System: Client-side property bookmarking without server calls
✅ Google Maps Integration: Interactive property location visualization
✅ Smart Recommendations: "You Might Also Like" feature based on search criteria
✅ Sticky Header: Context-aware navigation that appears on scroll
✅ CSV Export: Property data export for analysis
✅ API Endpoints: RESTful API for external integrations (Calibot AI)

🚀 Major Features

1. Natural Language Search

Smart Query Parser - Extracts filters from complete sentences:

"Los Angeles homes under 4 million" → city=Los Angeles, price_max=4000000
"3 bedroom houses in San Diego" → city=San Diego, beds=3
"Beverly Hills between 2 and 5 million" → city=Beverly Hills, price_min=2000000, price_max=5000000

Supported Patterns:

Price: "under", "less than", "below", "over", "more than", "between X and Y"
Units: "million", "thousand", "m", "k" (e.g., "1.5m", "800k")
Beds/Baths: "3 beds", "2.5 baths"
Square Feet: "2000 sqft", "1500+ square feet"

2. Hero Section & Search Interface

Fixed Background: title_image.jpg with smooth parallax effect
Gradient Overlays: Multi-layer gradients for text readability
Smart Search Bar: Real-time city autocomplete with property counts
Dynamic Padding: Adjusts for dropdown visibility

3. Property Save System

Client-Side with localStorage:

No server calls for saves (instant response)
"View Saved" link shows only saved properties
Real-time counter updates
Persists across sessions
Works on main listings and recommendations

4. AI Integration (Calibot)

ElevenLabs Conversational AI:

Custom knowledge base at /api/calibot_knowledge_base.txt
Schema.org JSON-LD on every property card
RESTful API endpoint: /api/calibot_query.php
Structured data attributes for RAG parsing
Accurate listing ID lookups and property details

5. Google Maps

Multiple map types: Roadmap, Satellite, Hybrid
Geocoding for property addresses
Interactive markers and modals

Features & Functionality

1. Advanced Search & Filtering

Smart Search Bar

Real-time search suggestions for cities, beds, baths, and combinations
Examples: "Los Angeles", "4 beds Los angeles", "Los Angeles 4 beds 8 baths"
General search across all database fields (address, city, zip, price, beds, baths, sqft)
All filters automatically cleared on new search

Filter Options

City: Text input with autocomplete suggestions
ZIP Code: Exact match filtering
Price Range: Min/Max price filters
Bedrooms: Minimum bedroom count
Bathrooms: Minimum bathroom count
Square Footage: Min/Max square footage range

Search Behavior

Filters are cleared when performing a new general search
City-only filtering via autocomplete suggestions
General search searches across all fields simultaneously
Smart number detection (prices, beds, baths, sqft)

2. Interactive Maps

Google Maps Integration

Property location visualization with markers
Multiple map types: Roadmap, Satellite, Hybrid
Automatic geocoding for property addresses
Interactive map controls and zoom
Map view in property detail modals

Map Features

Click property cards to view on map
Modal maps show exact property location
Responsive map sizing for all screen sizes

3. AI Assistant (Calibot)

ElevenLabs Conversational AI

Embedded widget for property search assistance
Configured with concise, data-driven responses
Can query property database via API endpoints
Positioned via ElevenLabs dashboard settings
Natural language understanding for property queries

Calibot Capabilities

Answer questions about property data
Provide statistics and market insights
Assist with search queries
Database-driven responses

4. Favorites Management

Complete Favorites System

Heart icon toggle on all property cards
AJAX-based add/remove without page reload
Session-based persistence
"View Favorites" filter button
"Clear All Favorites" functionality
Real-time favorites count display
Works in both grid and list views

Favorites Features

Persistent across page navigation
Instant UI updates
Favorites-only view mode
Bulk clear option

5. Property Display

View Modes

Grid View: Card-based layout with images
List View: Compact list with key details
Seamless toggle between views
View preference persists in session

Property Cards

High-quality property images
Key details: Price, Beds, Baths, SqFt, Address
Heart icon for favorites
Click to view full details
Responsive card sizing

Property Detail Modals

Full-screen image galleries
Image navigation with arrows and dots
Interactive Google Maps
Complete property information
Price per square foot calculation
Close button and keyboard shortcuts (ESC)

6. Sorting & Pagination

Sorting Options

Price (Ascending/Descending)
Bedrooms (Ascending/Descending)
Square Footage (Ascending/Descending)
Sort preference persists

Pagination

12 properties per page
Page navigation controls
Current page indicator
Total results count
Efficient database queries with LIMIT/OFFSET

7. Statistics Dashboard

Real-time Market Analytics

Total properties matching search
Average price
Minimum price
Maximum price
Average square footage
Updates dynamically with filters

8. Data Export

CSV Export

Export search results to CSV
Includes all property details
Date-stamped filenames
Compatible with Excel and Google Sheets

6. Smart Recommendations

"You Might Also Like" Section:

Analyzes current search filters (city, price, beds, baths)
Suggests similar properties in the same city
Price range: ±20% of search criteria
Bedroom/bathroom flexibility
Displays top 6 recommendations
Save button on each recommendation

🛠️ Technology Stack

Backend:

PHP 7.2+ (Server-side rendering and API)
MySQL/MariaDB (Property database)
PDO (Database abstraction layer)

Frontend:

Vanilla JavaScript (ES6+)
CSS3 (Custom properties, Grid, Flexbox)
HTML5 Semantic markup
Schema.org JSON-LD (Structured data)

APIs & Services:

Google Maps JavaScript API
ElevenLabs Conversational AI
RESTful API endpoints

Features:

Natural Language Processing (NLP)
localStorage API
Fetch API (AJAX)
URLSearchParams (Query string management)

📊 Database Schema

Table: rets_property
Database: boxgra6_cali

Field	Type	Description
`L_ListingID`	VARCHAR	Unique listing ID (PK)
`L_Address`	VARCHAR	Street address
`L_City`	VARCHAR	City name
`L_Zip`	VARCHAR	ZIP code
`L_SystemPrice`	DECIMAL	Price in USD
`L_Keyword2`	VARCHAR	Number of bedrooms
`LM_Dec_3`	DECIMAL	Number of bathrooms
`LM_Int2_3`	INT	Square footage
`L_Photos`	TEXT	Photo URLs (JSON/comma-separated)
`L_UpdateDate`	DATETIME	Last updated timestamp

🔧 Key Files

/home/neo/IDX/
├── index.php                          # Main application (3,255 lines)
├── config.php                         # Database configuration
├── title_image.jpg                    # Hero background image
├── api/
│   ├── calibot_query.php             # API endpoint for Calibot
│   ├── calibot_knowledge_base.txt    # AI knowledge base
│   ├── api_docs.html                 # API documentation
│   ├── city_autocomplete.php         # City search API
│   └── listing_ids.php               # Static listing reference
└── README.md                         # This file

🎨 Design Features

Hero Section:

Fixed background image (title_image.jpg)
Multi-layer gradient overlays
Centered smart search with autocomplete
Dynamic padding based on dropdown visibility

Color Scheme:

Primary: #4f7cff (Accent blue)
Background: #080d1a (Dark navy)
Text: #e2e8f0 (Light gray)
Muted: #7e8bbd (Mid blue-gray)

Typography:

System font stack: -apple-system, BlinkMacSystemFont, 'Segoe UI'
Responsive sizing with rem units

🤖 AI Integration Details

Calibot Configuration:

Knowledge Base URL: https://akbar.califorsale.org/api/calibot_knowledge_base.txt
Website Context: https://akbar.califorsale.org/
API Endpoint: https://akbar.califorsale.org/api/calibot_query.php

API Actions:

search - Find properties with filters
stats - Market statistics
city_stats - City-specific data
property_details - Lookup by listing ID

Structured Data:

Every property has Schema.org JSON-LD
data-property-* attributes on all cards
Machine-readable formats for RAG systems

🚦 Setup Instructions

Database Configuration (config.php or top of index.php):

$DB_HOST = 'localhost';
$DB_NAME = 'boxgra6_cali';
$DB_USER = 'your_username';
$DB_PASS = 'your_password';

Google Maps API Key (line ~3228):

<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_KEY&callback=initGoogleMaps" async defer></script>

ElevenLabs Agent ID (line ~3227):

<elevenlabs-convai agent-id="YOUR_AGENT_ID"></elevenlabs-convai>

Upload Files to web server
Test URL: Navigate to https://your-domain.com/

✅ Completed Features Checklist

📝 Known Issues & Limitations

ModSecurity: Some API endpoints may be blocked by server firewall (406 errors)
CLI PHP: PDO MySQL driver not available in command-line PHP
Photo Parsing: Some MLS photo formats may not display correctly
Geocoding Limits: Google Maps API has rate limits

Workarounds:

Static knowledge base files for AI agent
Schema.org markup for property data access
Client-side localStorage for saves (no server calls)
Based on viewing history
Based on favorites
Based on current search criteria
Price range matching (±20%)
City and filter matching

Technology Stack

Backend

PHP 7.2+: Server-side logic and database interaction
PDO (PHP Data Objects): Secure database access
MySQL 8.0+: Relational database management
Session Management: PHP sessions for user state

Frontend

HTML5: Semantic markup
CSS3: Modern styling with animations
Vanilla JavaScript (ES6+): No framework dependencies
AJAX: Asynchronous data fetching
Responsive Design: Mobile-first approach

External APIs

Google Maps JavaScript API: Mapping and geocoding
Google Maps Geocoding API: Address to coordinates
ElevenLabs Conversational AI: AI assistant widget

Architecture

Single-Page Application: AJAX-based navigation
RESTful API Endpoints: Clean API design
MVC-like Structure: Separation of concerns
Session-based State: User preferences and favorites

System Architecture Diagram

graph TB
    A[User Browser] -->|HTTP Requests| B[index.php]
    B -->|PDO Queries| C[(MySQL Database<br/>rets_property)]
    B -->|Session Storage| D[PHP Sessions<br/>Favorites/State]
    
    A -->|AJAX Calls| E[API Endpoints]
    E -->|city_autocomplete.php| C
    E -->|parse_nlp.php| C
    E -->|search_suggestions.php| C
    E -->|calibot_query.php| C
    
    A -->|JavaScript API| F[Google Maps API]
    A -->|Widget Embed| G[ElevenLabs AI<br/>Calibot]
    G -->|API Calls| E
    
    B -->|Geocoding| F
    B -->|CSV Export| A
    
    style A fill:#4a90e2,color:#fff
    style B fill:#50c878,color:#fff
    style C fill:#ff6b6b,color:#fff
    style E fill:#ffa500,color:#fff
    style F fill:#4285f4,color:#fff
    style G fill:#00d4ff,color:#fff

Database Schema

Primary Table: `rets_property`

Database: boxgra6_cali
Character Set: utf8mb4
Collation: utf8mb4_unicode_ci

Table Structure

CREATE TABLE rets_property (
  -- Primary Key
  L_ListingID VARCHAR(50) PRIMARY KEY COMMENT 'Unique MLS listing ID',
  
  -- Address Information
  L_Address VARCHAR(255) NOT NULL COMMENT 'Street address',
  L_City VARCHAR(100) NOT NULL COMMENT 'City name',
  L_Zip VARCHAR(10) NOT NULL COMMENT 'ZIP code',
  
  -- Pricing
  L_SystemPrice DECIMAL(12,2) NOT NULL COMMENT 'Current listing price (USD)',
  
  -- Property Details
  L_Keyword2 VARCHAR(10) DEFAULT NULL COMMENT 'Number of bedrooms',
  LM_Int2_3 INT DEFAULT NULL COMMENT 'Number of bathrooms',
  LM_Dec_3 DECIMAL(10,2) DEFAULT NULL COMMENT 'Square footage',
  
  -- Media
  L_Photos JSON DEFAULT NULL COMMENT 'Array of image URLs',
  
  -- Status & Dates
  L_UpdateDate TIMESTAMP NULL DEFAULT NULL COMMENT 'Last updated by MLS',
  
  -- Indexes for Performance
  INDEX idx_city (L_City),
  INDEX idx_zip (L_Zip),
  INDEX idx_price (L_SystemPrice),
  INDEX idx_beds (L_Keyword2),
  INDEX idx_sqft (LM_Dec_3),
  INDEX idx_city_price (L_City, L_SystemPrice)
);

Column Usage

Column	Type	Usage	Example
`L_ListingID`	VARCHAR(50)	Primary key, unique identifier	"12345678"
`L_Address`	VARCHAR(255)	Street address	"123 Main St"
`L_City`	VARCHAR(100)	City name, searchable	"Los Angeles"
`L_Zip`	VARCHAR(10)	ZIP code, exact match	"90210"
`L_SystemPrice`	DECIMAL(12,2)	Listing price, range filtering	750000.00
`L_Keyword2`	VARCHAR(10)	Bedrooms count	"3"
`LM_Int2_3`	INT	Bathrooms count	2
`LM_Dec_3`	DECIMAL(10,2)	Square footage	2500.00
`L_Photos`	JSON	Array of image URLs	`["url1", "url2"]`
`L_UpdateDate`	TIMESTAMP	Last update time	2024-01-15 10:30:00

Key Relationships

Primary Key: L_ListingID - Used for favorites, viewed properties, and detail views
Search Indexes: City, ZIP, Price, Beds, SqFt for fast filtering
Composite Index: City + Price for optimized city searches with price filters

Database Schema Diagram

erDiagram
    rets_property {
        VARCHAR L_ListingID PK "Primary Key"
        VARCHAR L_Address "Street Address"
        VARCHAR L_City "City Name"
        VARCHAR L_Zip "ZIP Code"
        DECIMAL L_SystemPrice "Listing Price"
        VARCHAR L_Keyword2 "Bedrooms"
        INT LM_Int2_3 "Bathrooms"
        DECIMAL LM_Dec_3 "Square Footage"
        JSON L_Photos "Image URLs Array"
        TIMESTAMP L_UpdateDate "Last Updated"
    }
    
    rets_property ||--o{ favorites : "has"
    rets_property ||--o{ search_results : "returns"
    rets_property ||--o{ recommendations : "generates"

Installation & Setup

Prerequisites

PHP 7.2 or higher with PDO MySQL extension
MySQL 8.0 or higher
Web server (Apache/Nginx)
Google Maps API key
ElevenLabs account (optional, for Calibot)

Step 1: Database Setup

Create the database:

CREATE DATABASE boxgra6_cali CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Import or create the rets_property table with the schema above
Populate with property data (from MLS feed or import)

Step 2: Configuration

Edit index.php (lines 41-44) with your database credentials:

$DB_HOST = 'localhost';
$DB_NAME = 'boxgra6_cali';
$DB_USER = 'your_username';
$DB_PASS = 'your_password';

Step 3: Google Maps API

Get API key from Google Cloud Console
Enable "Maps JavaScript API" and "Geocoding API"
Replace API key in index.php (around line 475):

<script async defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initGoogleMaps"></script>

Step 4: Calibot AI (Optional)

Create account at ElevenLabs
Create a Conversational AI agent
Configure using calibot-persona.md content
Update agent ID in index.php (around line 2770):

<elevenlabs-convai agent-id="YOUR_AGENT_ID"></elevenlabs-convai>

Step 5: File Permissions

chmod 755 index.php
chmod 755 api/*.php

Step 6: Deploy

Upload all files to web server
Ensure PHP sessions directory is writable
Test database connection
Access via web browser

API Documentation

API Request Flow Diagram

graph TB
    A[Frontend JavaScript] -->|AJAX Request| B{API Endpoint}
    
    B -->|GET /api/city_autocomplete.php| C[City Autocomplete]
    B -->|GET /api/search_suggestions.php| D[Search Suggestions]
    B -->|GET /api/parse_nlp.php| E[NLP Parser]
    B -->|GET /api/calibot_query.php| F[Calibot Query]
    
    C -->|Fuzzy Match| G[(Database Query)]
    D -->|Parse Query| G
    E -->|Extract Filters| G
    F -->|Property Stats| G
    
    G -->|PDO Prepared Statement| H[(MySQL Database)]
    H -->|Results| I[JSON Response]
    I -->|Return Data| A
    
    style A fill:#4a90e2,color:#fff
    style B fill:#ffa500,color:#fff
    style G fill:#50c878,color:#fff
    style H fill:#ff6b6b,color:#fff
    style I fill:#9b59b6,color:#fff

Public Endpoints

1. Search Suggestions API

Endpoint: GET /api/search_suggestions.php?q=query

Description: Returns search suggestions for cities, beds, baths, and combinations

Parameters:

q (required): Search query string (min 2 characters)

Response Format:

{
  "success": true,
  "query": "los angeles 4",
  "suggestions": [
    {
      "type": "city_beds",
      "text": "Los Angeles 4 beds",
      "display": "Los Angeles - 4 beds (1,234 properties)",
      "city": "Los Angeles",
      "beds": 4,
      "count": 1234
    }
  ]
}

Example:

GET /api/search_suggestions.php?q=los%20angeles%204

2. City Autocomplete API

Endpoint: GET /api/city_autocomplete.php?q=query

Description: Returns city suggestions with property counts and fuzzy matching

Parameters:

q (required): City name query (min 2 characters)

Response Format:

{
  "suggestions": [
    {
      "city": "Los Angeles",
      "display": "Los Angeles, CA",
      "count": 5432
    }
  ]
}

3. NLP Parser API

Endpoint: GET /api/parse_nlp.php?query=text

Description: Parses natural language queries into structured filters

Parameters:

query (required): Natural language search query

Response Format:

{
  "city": "Los Angeles",
  "beds": 3,
  "baths": 2,
  "price_max": 800000,
  "keywords": ["ocean view"]
}

Internal Endpoints

4. Toggle Favorite

Endpoint: GET /?toggle_fav=listing_id

Description: Toggle favorite status for a property (AJAX)

Response: JSON with success status and favorites count

5. Clear All Favorites

Endpoint: GET /?clear_all_favorites=1

Description: Clear all favorites from session

Response: JSON with success status

6. View Favorites

Endpoint: GET /?show_favorites=1

Description: Filter to show only favorited properties

7. CSV Export

Endpoint: GET /?export=csv&[filters]

Description: Export current search results as CSV

Response: CSV file download

Frontend Architecture

JavaScript Structure

Main Components:

Search Handler: Smart search input with autocomplete
Favorites Manager: AJAX toggle and state management
Modal System: Property detail modals with galleries
Map Integration: Google Maps initialization and markers
View Toggle: Grid/List view switching
Pagination: Page navigation and URL management

Key JavaScript Functions

fetchSearchSuggestions(query): Fetch search suggestions from API
selectSuggestion(suggestion): Apply suggestion filters
performGeneralSearch(query): Execute general search
toggleFavorite(listingId): Toggle favorite status
clearAllFavorites(): Clear all favorites
showPropertyModal(listingId): Display property details
initGoogleMaps(): Initialize Google Maps

Frontend Component Flow

graph LR
    A[User Input] -->|Type Query| B[Smart Search Input]
    B -->|Debounce| C[fetchCitySuggestions]
    C -->|API Call| D[city_autocomplete.php]
    D -->|JSON Response| E[showCitySuggestions]
    E -->|Display| F[Autocomplete Dropdown]
    F -->|Select| G[selectCity/performGeneralSearch]
    G -->|Form Submit| H[PHP Backend]
    H -->|Query DB| I[(MySQL)]
    I -->|Results| J[Property Cards]
    J -->|Click| K[Property Modal]
    K -->|Show| L[Image Gallery + Map]
    
    J -->|Heart Click| M[toggleFavorite]
    M -->|AJAX| N[PHP Session]
    N -->|Update| J
    
    style B fill:#4a90e2,color:#fff
    style D fill:#ffa500,color:#fff
    style H fill:#50c878,color:#fff
    style I fill:#ff6b6b,color:#fff

CSS Architecture

Responsive Design: Mobile-first with breakpoints
Component-based: Modular CSS for components
Animations: Smooth transitions and hover effects
Grid System: Flexible grid for property cards
Modal Styling: Full-screen modals with overlays

Backend Architecture

PHP Structure

Main Components:

Database Connection: PDO with error handling
Session Management: Favorites and viewed properties
Query Builder: Dynamic SQL construction
Filter Processing: Input validation and sanitization
Pagination Logic: Page calculation and offset
Statistics Calculation: Aggregate queries
CSV Export: Data formatting and download

Backend Request Flow

sequenceDiagram
    participant U as User Browser
    participant I as index.php
    participant S as PHP Session
    participant D as MySQL Database
    participant A as API Endpoints
    
    U->>I: HTTP Request (GET/POST)
    I->>S: Read/Write Session Data
    I->>I: Process Filters & Search
    I->>D: Execute PDO Query
    D-->>I: Return Results
    I->>I: Calculate Statistics
    I->>I: Generate HTML
    I-->>U: Render Page
    
    U->>A: AJAX Request (Autocomplete)
    A->>D: Query Database
    D-->>A: Return Suggestions
    A-->>U: JSON Response
    
    U->>I: Toggle Favorite (AJAX)
    I->>S: Update Session
    S-->>I: Confirm Update
    I-->>U: JSON Response

Key PHP Functions

Filter processing: City, ZIP, price, beds, baths, sqft
General search: Multi-field search with OR logic
Favorites handling: Session-based storage
Statistics: Aggregate calculations
Recommendations: Smart property suggestions

Security Features

PDO Prepared Statements: SQL injection prevention
Input Sanitization: XSS prevention
Session Security: Secure session handling
Error Handling: Graceful error messages

User Experience Features

Responsive Design

Mobile: Optimized for phones (320px+)
Tablet: Optimized for tablets (768px+)
Desktop: Full-featured desktop experience (1024px+)

Accessibility

Keyboard navigation support
ARIA labels where appropriate
Semantic HTML structure
Focus indicators

Performance

Efficient database queries with indexes
AJAX for dynamic updates
Image lazy loading
Optimized CSS and JavaScript

User Feedback

Loading states
Error messages
Success confirmations
Real-time updates

Demo Walkthrough

User Journey Flow

flowchart TD
    Start([User Visits Site]) --> Home[Homepage with Hero Section]
    Home --> Search[Type in Search Bar]
    Search -->|City Query| Autocomplete[City Suggestions Appear]
    Search -->|General Query| General[General Search Results]
    Autocomplete --> Select[Select City Suggestion]
    Select --> Results[Property Results Displayed]
    General --> Results
    
    Results --> View[View Property Details]
    View --> Modal[Property Modal Opens]
    Modal --> Gallery[Browse Image Gallery]
    Modal --> Map[View on Google Maps]
    Modal --> Favorite[Add to Favorites]
    
    Results --> Filter[Apply Advanced Filters]
    Filter --> Filtered[Filtered Results]
    Filtered --> Sort[Sort Results]
    Sort --> Paginate[Navigate Pages]
    
    Results --> Export[Export to CSV]
    Results --> Calibot[Ask Calibot AI]
    
    Favorite --> FavoritesView[View Favorites Only]
    FavoritesView --> Clear[Clear All Favorites]
    
    style Start fill:#4a90e2,color:#fff
    style Results fill:#50c878,color:#fff
    style Modal fill:#ffa500,color:#fff
    style Favorite fill:#ff6b6b,color:#fff

1. Homepage & Search

Landing Page: Beautiful hero section with search bar
Smart Search: Type "Los Angeles" to see city suggestions
Complex Queries: Try "4 beds Los angeles" or "Los Angeles 4 beds 8 baths"
General Search: Type any property detail and press Enter

2. Filtering & Results

Advanced Filters: Click "Advanced Search" to show filters
Apply Filters: Set city, price range, beds, baths, sqft
View Results: Properties displayed in grid or list view
Statistics: View market statistics above results

3. Property Interaction

View Details: Click any property card
Image Gallery: Navigate through property photos
Map View: See property location on Google Maps
Add to Favorites: Click heart icon to favorite

4. Favorites Management

View Favorites: Click "View Favorites" button
Remove Favorites: Click heart again to unfavorite
Clear All: Use "Clear All" button to remove all
Favorites Count: See count in header

5. Sorting & Pagination

Sort Options: Use dropdown to sort by price, beds, sqft
Pagination: Navigate through pages
View Toggle: Switch between grid and list views

6. Export & Analysis

CSV Export: Click "Export CSV" button
Download: File downloads with all property data
Analysis: Open in Excel or Google Sheets

7. AI Assistant (Calibot)

Open Widget: Click Calibot widget (if configured)
Ask Questions: "How many properties in Los Angeles?"
Get Insights: Receive data-driven responses
Search Help: Get assistance with search queries

File Structure

Project Directory Tree

IDX/
├── index.php                      # Main application file (~2800 lines)
│   ├── Database connection
│   ├── Session management
│   ├── Filter processing
│   ├── Query building
│   ├── HTML structure
│   ├── CSS styling
│   └── JavaScript functionality
│
├── api/
│   ├── search_suggestions.php     # General search suggestions API
│   ├── city_autocomplete.php      # City autocomplete with fuzzy matching
│   ├── parse_nlp.php             # Natural language query parser
│   ├── calibot_query.php         # Calibot database query API
│   └── fetch_property.php        # Property data fetcher
│
├── config.php                     # Database configuration loader
├── calibot-persona.md            # Calibot AI agent configuration
├── favicon_IDX.ico               # Site favicon
├── title_image.jpg               # Hero section background
└── README.md                     # This file

Component Interaction Diagram

graph TB
    subgraph "Frontend Layer"
        A[index.php<br/>Main Application]
        B[HTML/CSS/JS<br/>Client-Side Logic]
    end
    
    subgraph "API Layer"
        C[city_autocomplete.php]
        D[search_suggestions.php]
        E[parse_nlp.php]
        F[calibot_query.php]
    end
    
    subgraph "Backend Layer"
        G[PHP Session<br/>State Management]
        H[PDO Database<br/>Connection]
    end
    
    subgraph "Data Layer"
        I[(MySQL Database<br/>rets_property)]
    end
    
    subgraph "External Services"
        J[Google Maps API]
        K[ElevenLabs AI]
    end
    
    A --> B
    B -->|AJAX| C
    B -->|AJAX| D
    B -->|AJAX| E
    B -->|AJAX| F
    B -->|Embed| K
    B -->|JavaScript API| J
    
    A --> G
    A --> H
    C --> H
    D --> H
    E --> H
    F --> H
    H --> I
    
    A -->|Geocoding| J
    
    style A fill:#4a90e2,color:#fff
    style C fill:#ffa500,color:#fff
    style D fill:#ffa500,color:#fff
    style E fill:#ffa500,color:#fff
    style F fill:#ffa500,color:#fff
    style H fill:#50c878,color:#fff
    style I fill:#ff6b6b,color:#fff
    style J fill:#4285f4,color:#fff
    style K fill:#00d4ff,color:#fff

🎓 Learning Outcomes

This project demonstrates:

Full-Stack Development: PHP backend + JavaScript frontend
Database Design: Complex queries with joins and aggregations
API Development: RESTful endpoints with JSON responses
AI Integration: Working with conversational AI and RAG systems
Modern Web Standards: Schema.org, semantic HTML, accessibility
Natural Language Processing: Query parsing and intent extraction
Real-time Features: AJAX, localStorage, dynamic UI updates
Map Integration: Google Maps API with geocoding
Responsive Design: Mobile-first CSS with modern layout techniques

👤 Developer

Akbar Aman
SD6 Team Lead, IDX Exchange Pro-bono Initiative

Project Status: ✅ Complete and Production Ready
Completion Date: December 18, 2025
Live Site: https://akbar.califorsale.org

🙏 Acknowledgments

Dylan's reference implementation for hero section design
Google Maps Platform for geocoding services
ElevenLabs for conversational AI technology
California MLS for property data

End of Documentation

Database Configuration

Location: index.php (lines 41-44)

$DB_HOST = 'localhost';
$DB_NAME = 'boxgra6_cali';
$DB_USER = 'your_username';
$DB_PASS = 'your_password';

Google Maps Configuration

Location: index.php (around line 475)

<script async defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initGoogleMaps"></script>

Required APIs:

Maps JavaScript API
Geocoding API

Calibot Configuration

Location: index.php (around line 2770)

<elevenlabs-convai agent-id="YOUR_AGENT_ID"></elevenlabs-convai>

Setup:

Create agent on ElevenLabs
Use calibot-persona.md for configuration
Update agent ID in HTML

Session Configuration

Location: index.php (line 36)

session_start();

Session Variables:

$_SESSION['favorites']: Array of favorite listing IDs
$_SESSION['viewed_properties']: Array of recently viewed listing IDs

Troubleshooting

Common Issues

1. Database Connection Error

Check database credentials
Verify MySQL service is running
Ensure PDO MySQL extension is installed

2. No Search Suggestions

Check API endpoint accessibility
Verify database connection in API files
Check browser console for JavaScript errors

3. Maps Not Loading

Verify Google Maps API key is valid
Check API key restrictions
Ensure required APIs are enabled

4. Favorites Not Persisting

Check PHP session configuration
Verify session directory is writable
Check browser cookie settings

5. Images Not Displaying

Verify image URLs in database
Check CORS settings if using external images
Verify JSON format of L_Photos column

Debug Mode

Add ?debug=1 to URL to see detailed error messages (development only).

Performance Optimization

Database Optimization

Indexes on frequently searched columns
Composite indexes for common filter combinations
LIMIT/OFFSET for pagination
Prepared statements for query efficiency

Frontend Optimization

Debounced search input
Lazy loading for images
AJAX for dynamic updates
Minimal DOM manipulation

Caching Strategy

Session-based caching for favorites
Database query optimization
Browser caching for static assets

Security Considerations

Input Validation

All user input sanitized
SQL injection prevention via PDO
XSS prevention with htmlspecialchars
Type casting for numeric inputs

Session Security

Secure session configuration
Session data validation
CSRF protection considerations

API Security

Input validation on all endpoints
Error message sanitization
Rate limiting considerations

Future Enhancements

Potential Additions

User authentication system
Saved searches
Email alerts for new properties
Advanced analytics dashboard
Property comparison tool
Virtual tour integration
Mortgage calculator
Neighborhood information

Acknowledgments

IDX Exchange for project sponsorship and mentorship
SD6 Team for collaboration and dedication
Google Maps for mapping services
ElevenLabs for conversational AI technology

License

MIT License - See LICENSE file for details

Contact & Support

Developer: Akbar Aman
Team: SD6, IDX Exchange Initiative
Project Status: Complete & Production Ready

Built with ❤️ by SD6 Team @ IDX Exchange

Recent Updates & Improvements

Search & Autocomplete Enhancements

Improved City Autocomplete: Enhanced fuzzy matching with Levenshtein distance for misspelled city names
General Search Suggestions API: New endpoint (api/search_suggestions.php) for comprehensive search suggestions
Smart Query Parsing: Improved NLP parser for better extraction of city, beds, baths from natural language queries
Dropdown Positioning: Fixed autocomplete dropdown to properly push content down instead of overlapping

UI/UX Improvements

Dynamic Hero Padding: Autocomplete dropdown now dynamically adjusts hero section padding to prevent content overlap
Better Error Handling: Enhanced error handling in API endpoints with consistent JSON responses
Improved Search Flow: All filters automatically cleared on new general search for cleaner user experience

API Enhancements

City Autocomplete API: Added fuzzy matching for better suggestion accuracy
Search Suggestions API: New comprehensive endpoint for multi-criteria search suggestions
NLP Parser: Improved keyword extraction and city matching with database-driven fuzzy matching

Technical Improvements

Code Organization: Better separation of concerns in API endpoints
Error Handling: Consistent error response formats across all APIs
Performance: Optimized database queries for autocomplete suggestions

Last Updated: December 2024

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
api		api
docs		docs
.env.example		.env.example
.gitignore		.gitignore
.idx_secrets.php.example		.idx_secrets.php.example
LICENSE		LICENSE
README.md		README.md
calibot-persona.md		calibot-persona.md
favicon_IDX.ico		favicon_IDX.ico
htaccess		htaccess
index.php		index.php
title_image.jpg		title_image.jpg

Folders and files

Latest commit

History

Repository files navigation

California Property Finder - Project Documentation

🎯 Project Overview

🏆 Key Achievements

🚀 Major Features

1. Natural Language Search

2. Hero Section & Search Interface

3. Property Save System

4. AI Integration (Calibot)

5. Google Maps

Features & Functionality

1. Advanced Search & Filtering

2. Interactive Maps

3. AI Assistant (Calibot)

4. Favorites Management

5. Property Display

6. Sorting & Pagination

7. Statistics Dashboard

8. Data Export

6. Smart Recommendations

🛠️ Technology Stack

📊 Database Schema

🔧 Key Files

🎨 Design Features

🤖 AI Integration Details

🚦 Setup Instructions

✅ Completed Features Checklist

📝 Known Issues & Limitations

Technology Stack

Backend

Frontend

External APIs

Architecture

System Architecture Diagram

Database Schema

Primary Table: rets_property

Table Structure

Column Usage

Key Relationships

Database Schema Diagram

Installation & Setup

Prerequisites

Step 1: Database Setup

Step 2: Configuration

Step 3: Google Maps API

Step 4: Calibot AI (Optional)

Step 5: File Permissions

Step 6: Deploy

API Documentation

API Request Flow Diagram

Public Endpoints

1. Search Suggestions API

2. City Autocomplete API

3. NLP Parser API

Internal Endpoints

4. Toggle Favorite

5. Clear All Favorites

6. View Favorites

7. CSV Export

Frontend Architecture

JavaScript Structure

Key JavaScript Functions

Frontend Component Flow

CSS Architecture

Backend Architecture

PHP Structure

Backend Request Flow

Key PHP Functions

Security Features

User Experience Features

Responsive Design

Accessibility

Performance

User Feedback

Demo Walkthrough

User Journey Flow

1. Homepage & Search

Primary Table: `rets_property`

Packages