homeproz/README.md

# HomeProz Real Estate WordPress Site

Custom WordPress site for HomeProz Real Estate (Albert Lea, MN) with MLS Grid integration.

**Production URL:** https://homeprozrealestate.com

## Quick Reference for Sysadmins

### Required Cron Job

Add to system crontab (`crontab -e`):

```bash
# MLS property sync - runs every 15 minutes
*/15 * * * * cd /var/www/html && wp mls run --silent --allow-root >> /var/log/mls-sync.log 2>&1
```

This single cron job handles everything:
- Initial full sync on first run (~30K properties, takes 30-45 min)
- Incremental updates on subsequent runs
- Automatic recovery from failures
- Safe concurrent execution (aborts if already running)

### Manual Sync Commands

```bash
# Check sync status
wp --allow-root mls status

# Run sync manually
wp --allow-root mls run

# View database statistics
wp --allow-root mls stats

# Test API connection
wp --allow-root mls test connection
```

### Log Files

| Log | Location | Purpose |
|-----|----------|---------|
| MLS Sync | `/var/log/mls-sync.log` | Cron sync output |
| WordPress | `/var/www/html/wp-content/debug.log` | PHP errors (if WP_DEBUG) |
| Missing Media | `/var/www/html/wp-content/uploads/mls-missing-media.log` | Failed image downloads |

### API Credentials

MLS Grid credentials are in `wp-config.php`:

```php
define('MLSGRID_ACCESS_TOKEN', '...');
```

Contact MLS Grid support (support@mlsgrid.com) for token issues.

## Project Structure

```
/var/www/html/
├── wp-config.php              # WordPress + MLS Grid config
├── wp-content/
│   ├── themes/homeproz/       # Custom theme
│   ├── plugins/
│   │   └── mls-by-hansonxyz/  # MLS sync plugin
│   └── uploads/
│       └── mls-listings/      # Cached property images
├── db-snapshots/              # Database snapshots
├── contract/                  # Project documentation
├── CLAUDE.md                  # AI development context
└── DEPENDENCIES.md            # System dependencies
```

## Key Components

### Custom Theme: HomeProz

Location: `/wp-content/themes/homeproz/`

Dark/rust brand aesthetic with ACF-powered property listings.

```bash
# Build theme assets
cd wp-content/themes/homeproz
npm run build
```

### MLS Plugin: mls-by-hansonxyz

Location: `/wp-content/plugins/mls-by-hansonxyz/`

Syncs property data from NorthStar MLS via MLS Grid API.

See `/wp-content/plugins/mls-by-hansonxyz/README.md` for full documentation.

### Custom Post Types

| Post Type | URL | Description |
|-----------|-----|-------------|
| Property | `/properties/` | MLS listings (ACF fields) |
| Agent | `/agents/` | Team member profiles |

## Technology Stack

- WordPress 6.x
- PHP 8.1+
- MySQL 8.0
- Tailwind CSS + SCSS (via Vite)
- jQuery
- ACF Pro
- WP-CLI

## Development Commands

```bash
# Theme development
cd wp-content/themes/homeproz
npm install
npm run dev      # Dev server with hot reload
npm run build    # Production build

# Database snapshot (includes timestamp)
./dev_commit.sh "commit message"

# WP-CLI
wp --allow-root <command>
```

## MLS Data Flow

```
MLS Grid API (NorthStar MLS)
         |
         v
    wp mls run (cron every 15 min)
         |
         v
    wp_mls_properties table (~30K Active/Pending listings)
         |
         v
    Theme displays via mls_get_properties() API
         |
         v
    Images fetched on-demand from MLS Grid
         |
         v
    Cached in wp-content/uploads/mls-listings/
```

## Maintenance Tasks

### Daily

- Cron job runs automatically every 15 minutes
- Monitor `/var/log/mls-sync.log` for errors

### Weekly

- Check `wp --allow-root mls stats` for data health
- Review disk space for cached images

### Monthly

- Review MLS Grid rate limit usage: `wp --allow-root mls status rate-limits`
- Clear orphaned media: `wp --allow-root mls cache cleanup`

### After Server Migration

1. Verify `wp-config.php` has MLS Grid credentials
2. Set up cron job (see above)
3. Run initial sync: `wp --allow-root mls run`
4. Verify: `wp --allow-root mls stats`

## Troubleshooting

### No Properties Showing

```bash
# Check if data exists
wp --allow-root mls stats

# Check sync status
wp --allow-root mls status

# Run manual sync
wp --allow-root mls run --verbose
```

### Sync Failing

```bash
# Test API connection
wp --allow-root mls test connection
wp --allow-root mls test auth

# Check rate limits
wp --allow-root mls status rate-limits

# View resumable syncs
wp --allow-root mls recovery list
```

### Images Not Loading

```bash
# Check cache stats
wp --allow-root mls media status

# Check directory permissions
ls -la wp-content/uploads/mls-listings/

# Pre-cache a listing manually
wp --allow-root mls media fetch --listing=<key> --limit=10
```

### Clear Everything and Start Fresh

```bash
wp --allow-root mls cache clear --confirm
wp --allow-root mls run
```

## Contacts

- **Client:** HomeProz Real Estate, LLC - 111 E Clark St, Albert Lea, MN 56007
- **MLS Grid Support:** support@mlsgrid.com
- **Developer:** HansonXyz - https://hanson.xyz