# HomeProz WordPress Website Implementation Plan
## Draft v1.0 - For Review

---

## 1. Executive Summary

This document outlines the implementation approach for building the HomeProz WordPress website. The project will deliver a custom WordPress theme with Advanced Custom Fields (ACF) integration for property management, following modern WordPress development best practices.

**Estimated Development Time:** 40 hours (as per contract)
**Approach:** Custom theme development with ACF Pro for property listings

---

## 2. Technology Stack

### 2.1 Core Platform
| Component | Technology | Version |
|-----------|------------|---------|
| CMS | WordPress | 6.x (latest stable) |
| PHP | PHP | 8.1+ |
| Database | MySQL/MariaDB | 8.0+ / 10.6+ |
| Web Server | Nginx or Apache | Latest |

### 2.2 Theme Development
| Component | Technology | Notes |
|-----------|------------|-------|
| Base Theme | Custom theme from scratch | No parent theme dependency |
| CSS | Modern CSS with CSS Variables | No preprocessor needed |
| JavaScript | Vanilla JS + Alpine.js | Lightweight interactivity |
| Build Tools | None required | Keep it simple |
| Block Editor | Full support | theme.json configuration |

### 2.3 Required Plugins
| Plugin | Purpose | License |
|--------|---------|---------|
| Advanced Custom Fields Pro | Property fields & flexible content | Paid ($49/yr) |
| Contact Form 7 or WPForms Lite | Contact forms | Free |
| Yoast SEO or Rank Math | SEO management | Free |
| WP Super Cache or LiteSpeed Cache | Caching | Free |
| Wordfence or Sucuri | Security | Free tier |
| UpdraftPlus | Backups | Free |

### 2.4 Optional/Recommended Plugins
| Plugin | Purpose | When to Add |
|--------|---------|-------------|
| Imagify or ShortPixel | Image optimization | At launch |
| Redirection | URL redirects | If migrating |
| Google Site Kit | Analytics integration | Post-launch |

---

## 3. Project Structure

### 3.1 Theme File Structure

```
themes/homeproz/
├── assets/
│   ├── css/
│   │   ├── style.css           # Main compiled styles
│   │   ├── editor-style.css    # Block editor styles
│   │   └── components/
│   │       ├── buttons.css
│   │       ├── cards.css
│   │       ├── forms.css
│   │       └── navigation.css
│   ├── js/
│   │   ├── main.js             # Main scripts
│   │   ├── navigation.js       # Mobile menu
│   │   └── property-filter.js  # AJAX filtering
│   ├── images/
│   │   ├── logo.svg
│   │   └── placeholder.jpg
│   └── fonts/                  # If self-hosting
│
├── inc/
│   ├── acf-fields.php          # ACF field group definitions
│   ├── custom-post-types.php   # Property CPT registration
│   ├── enqueue.php             # Script/style enqueuing
│   ├── theme-setup.php         # Theme supports, menus, etc.
│   ├── template-functions.php  # Helper functions
│   ├── block-patterns.php      # Custom block patterns
│   └── customizer.php          # Theme options (if needed)
│
├── template-parts/
│   ├── header/
│   │   ├── site-header.php
│   │   └── navigation.php
│   ├── footer/
│   │   ├── site-footer.php
│   │   └── footer-widgets.php
│   ├── content/
│   │   ├── content-page.php
│   │   ├── content-post.php
│   │   └── content-none.php
│   ├── property/
│   │   ├── property-card.php
│   │   ├── property-gallery.php
│   │   ├── property-details.php
│   │   ├── property-filters.php
│   │   └── property-agent.php
│   ├── components/
│   │   ├── agent-card.php
│   │   ├── testimonial.php
│   │   ├── cta-section.php
│   │   └── hero-section.php
│   └── blocks/                 # Custom block templates
│
├── patterns/                   # Block patterns (WP 6.0+)
│   ├── hero-cta.php
│   ├── feature-grid.php
│   └── team-grid.php
│
├── templates/                  # Full Site Editing templates (optional)
│
├── 404.php
├── archive.php
├── archive-property.php
├── footer.php
├── front-page.php
├── functions.php
├── header.php
├── index.php
├── page.php
├── page-about.php
├── page-contact.php
├── search.php
├── single.php
├── single-property.php
├── sidebar.php
├── template-full-width.php
├── template-landing.php
├── template-blank.php
├── screenshot.png
├── style.css
└── theme.json                  # Block editor config
```

### 3.2 ACF Field Structure

#### Property Fields Group
```
Property Details
├── Basic Information
│   ├── property_status (select: Active, Pending, Sold)
│   ├── property_type (select: Residential, Commercial, Land, Multi-Family)
│   ├── price (number)
│   ├── price_display (text) - for "Call for Price" etc.
│   └── mls_number (text)
│
├── Address
│   ├── street_address (text)
│   ├── city (text)
│   ├── state (text, default: MN)
│   ├── zip_code (text)
│   └── google_maps_embed (textarea) - or use lat/lng
│
├── Property Specs
│   ├── bedrooms (number)
│   ├── bathrooms (number)
│   ├── square_feet (number)
│   ├── lot_size (text)
│   ├── year_built (number)
│   └── garage (select: None, 1-car, 2-car, 3+car)
│
├── Media
│   ├── featured_image (uses WP featured image)
│   ├── gallery (gallery field)
│   └── virtual_tour_url (url) - optional
│
├── Description
│   ├── short_description (textarea) - for cards
│   └── full_description (wysiwyg)
│
├── Features & Amenities
│   └── features (checkbox or repeater)
│
└── Agent Assignment
    └── listing_agent (post object -> Agent CPT or user select)
```

#### Agent/Team Member Fields
```
Agent Details
├── agent_title (text) - "REALTOR®"
├── agent_phone (text)
├── agent_email (email)
├── agent_bio (wysiwyg)
├── agent_photo (image)
└── agent_social (repeater: platform, url)
```

#### Testimonials Fields
```
Testimonial Details
├── testimonial_text (textarea)
├── client_name (text)
├── client_location (text)
├── transaction_type (select: Buyer, Seller, Both)
└── rating (number 1-5) - optional
```

---

## 4. Implementation Phases

### Phase 1: Foundation (Day 1-2)
**Estimated: 8 hours**

- [ ] Set up local development environment
- [ ] Create theme folder structure
- [ ] Set up `functions.php` with includes
- [ ] Configure `theme.json` for block editor
- [ ] Create `style.css` with CSS variables (colors, typography)
- [ ] Build `header.php` with navigation
- [ ] Build `footer.php` with widgets areas
- [ ] Create basic `index.php`, `page.php`
- [ ] Register menus (Primary, Footer)
- [ ] Set up theme supports (thumbnails, title-tag, etc.)

**Deliverable:** Basic theme framework with header/footer

### Phase 2: Property System (Day 3-4)
**Estimated: 10 hours**

- [ ] Register Property custom post type
- [ ] Install and configure ACF Pro
- [ ] Create Property field groups
- [ ] Build `archive-property.php` (listings page)
- [ ] Build `single-property.php` (detail page)
- [ ] Create `property-card.php` template part
- [ ] Create `property-gallery.php` template part
- [ ] Create `property-filters.php` template part
- [ ] Implement AJAX filtering (property-filter.js)
- [ ] Add property status badges
- [ ] Test property CRUD in admin

**Deliverable:** Fully functional property listing system

### Phase 3: Page Templates (Day 4-5)
**Estimated: 8 hours**

- [ ] Build `front-page.php` (homepage sections)
- [ ] Build `page-about.php` (about/team page)
- [ ] Build `page-contact.php` (contact page)
- [ ] Build `archive.php` (blog listing)
- [ ] Build `single.php` (blog post)
- [ ] Create `template-full-width.php`
- [ ] Create `template-landing.php`
- [ ] Build `404.php`
- [ ] Build `search.php`
- [ ] Create reusable template parts:
  - [ ] Hero section
  - [ ] CTA section
  - [ ] Testimonial component
  - [ ] Agent card component
  - [ ] Post card component
  - [ ] Sidebar widgets
- [ ] Set up Contact Form 7 / form plugin

**Deliverable:** All page templates functional (including blog)

### Phase 4: Block Patterns & Polish (Day 5-6)
**Estimated: 6 hours**

- [ ] Create block patterns:
  - [ ] Hero with CTA
  - [ ] Feature grid (3-col)
  - [ ] Team grid
  - [ ] Testimonial
  - [ ] Split content
  - [ ] CTA banner
- [ ] Add editor styles (`editor-style.css`)
- [ ] Ensure block editor matches frontend
- [ ] Add responsive styles (mobile, tablet)
- [ ] Implement animations/transitions
- [ ] Cross-browser testing

**Deliverable:** Polished theme with reusable patterns

### Phase 5: Content & SEO (Day 6-7)
**Estimated: 4 hours**

- [ ] Install and configure Yoast/Rank Math
- [ ] Add Schema.org markup:
  - [ ] RealEstateAgent
  - [ ] RealEstateListing
  - [ ] LocalBusiness
- [ ] Set up XML sitemap
- [ ] Configure Open Graph meta tags
- [ ] Add favicon and touch icons
- [ ] Enter initial content:
  - [ ] Homepage content
  - [ ] About page content
  - [ ] Contact info
  - [ ] Sample properties (for testing)
- [ ] Add team member data

**Deliverable:** SEO-ready site with initial content

### Phase 6: Performance & Security (Day 7)
**Estimated: 2 hours**

- [ ] Install caching plugin
- [ ] Configure image optimization
- [ ] Enable GZIP compression
- [ ] Set up lazy loading
- [ ] Install security plugin
- [ ] Configure SSL/HTTPS
- [ ] Set up automated backups
- [ ] Run Lighthouse audit
- [ ] Address any performance issues

**Deliverable:** Optimized, secure site

### Phase 7: Testing & Training (Day 7-8)
**Estimated: 2 hours**

- [ ] Full QA testing:
  - [ ] All pages render correctly
  - [ ] Forms submit properly
  - [ ] Properties filter/search works
  - [ ] Mobile responsiveness
  - [ ] Cross-browser (Chrome, Firefox, Safari, Edge)
- [ ] Create documentation
- [ ] Conduct training session (1-2 hours)
- [ ] Client review on staging

**Deliverable:** Tested site ready for launch

---

## 5. Custom Post Types & Taxonomies

### 5.1 Property CPT

```php
// Registration in custom-post-types.php
register_post_type('property', [
    'labels' => [
        'name' => 'Properties',
        'singular_name' => 'Property',
        'add_new' => 'Add New Property',
        'add_new_item' => 'Add New Property',
        'edit_item' => 'Edit Property',
        'view_item' => 'View Property',
        'search_items' => 'Search Properties',
        'not_found' => 'No properties found',
    ],
    'public' => true,
    'has_archive' => true,
    'rewrite' => ['slug' => 'properties'],
    'menu_icon' => 'dashicons-building',
    'supports' => ['title', 'editor', 'thumbnail', 'excerpt'],
    'show_in_rest' => true, // Enable block editor
]);
```

### 5.2 Property Taxonomies

```php
// Property Type
register_taxonomy('property_type', 'property', [
    'labels' => ['name' => 'Property Types'],
    'hierarchical' => true,
    'rewrite' => ['slug' => 'property-type'],
    'show_in_rest' => true,
]);

// Property Status (or use ACF field)
register_taxonomy('property_status', 'property', [
    'labels' => ['name' => 'Status'],
    'hierarchical' => true,
    'rewrite' => ['slug' => 'status'],
    'show_in_rest' => true,
]);

// Location/City
register_taxonomy('property_location', 'property', [
    'labels' => ['name' => 'Locations'],
    'hierarchical' => true,
    'rewrite' => ['slug' => 'location'],
    'show_in_rest' => true,
]);
```

### 5.3 Agent CPT (Optional)

If managing agents as posts rather than ACF options:

```php
register_post_type('agent', [
    'labels' => ['name' => 'Agents', 'singular_name' => 'Agent'],
    'public' => true,
    'has_archive' => true,
    'rewrite' => ['slug' => 'agents'],
    'menu_icon' => 'dashicons-id-alt',
    'supports' => ['title', 'thumbnail'],
    'show_in_rest' => true,
]);
```

---

## 6. Key Features Implementation

### 6.1 Property Search & Filter

**Approach:** AJAX-based filtering without page reload

```javascript
// property-filter.js (simplified)
document.addEventListener('DOMContentLoaded', function() {
    const filterForm = document.querySelector('.property-filters');

    filterForm.addEventListener('change', function() {
        const formData = new FormData(filterForm);
        formData.append('action', 'filter_properties');

        fetch(ajaxurl, {
            method: 'POST',
            body: formData
        })
        .then(response => response.json())
        .then(data => {
            document.querySelector('.property-grid').innerHTML = data.html;
            document.querySelector('.results-count').textContent = data.count;
        });
    });
});
```

### 6.2 Property Gallery

**Approach:** Lightbox gallery using Fancybox or similar

- Thumbnail grid below main image
- Click to open lightbox
- Swipe support on mobile
- Lazy loading for performance

### 6.3 Agent Assignment

Properties link to agents for "Listed By" section:
- ACF relationship field connecting Property -> Agent
- Display agent card on single property page
- Click to contact or view agent profile

### 6.4 Contact Form

Using Contact Form 7 or WPForms:
- Standard contact form (Name, Email, Phone, Message)
- Property inquiry form (includes property reference)
- Email notifications to appropriate agent

### 6.5 Map Integration

Options:
1. **Google Maps Embed** (simple, free) - paste embed code per property
2. **Google Maps API** (interactive) - requires API key, more setup
3. **Leaflet/OpenStreetMap** (free, no API key) - good alternative

Recommendation: Start with embed codes, upgrade to API if needed.

---

## 7. Theme Customization Options

### 7.1 theme.json Configuration

```json
{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 2,
    "settings": {
        "color": {
            "palette": [
                { "slug": "primary", "color": "#9F3730", "name": "Primary" },
                { "slug": "primary-dark", "color": "#0A0A0A", "name": "Background" },
                { "slug": "text", "color": "#F5F5F5", "name": "Text" },
                { "slug": "text-muted", "color": "#B0B0B0", "name": "Text Muted" }
            ]
        },
        "typography": {
            "fontFamilies": [
                {
                    "fontFamily": "'Abril Fatface', Georgia, serif",
                    "slug": "display",
                    "name": "Display"
                },
                {
                    "fontFamily": "'Inter', 'Droid Sans', Arial, sans-serif",
                    "slug": "body",
                    "name": "Body"
                }
            ]
        },
        "spacing": {
            "units": ["px", "rem", "%"]
        },
        "layout": {
            "contentSize": "800px",
            "wideSize": "1200px"
        }
    }
}
```

### 7.2 Customizer Options (if needed)

- Logo upload
- Contact information (phone, email, address)
- Social media links
- Footer text
- Google Analytics ID

---

## 8. Content Migration

### 8.1 From Existing Site

Content to migrate from homeprozrealestate.com:
- [ ] Logo image
- [ ] Team member photos and bios
- [ ] Property photos (if available)
- [ ] Testimonial text
- [ ] Company description/mission
- [ ] Contact information

### 8.2 Content Client Must Provide

- [ ] High-resolution logo (vector preferred)
- [ ] Team headshots (professional quality)
- [ ] Property listings data
- [ ] Property photos
- [ ] Written content for About page
- [ ] Testimonials with permissions

---

## 9. Testing Checklist

### 9.1 Functionality
- [ ] All pages load without errors
- [ ] Navigation works (desktop and mobile)
- [ ] Property archive displays correctly
- [ ] Property filters work
- [ ] Single property page displays all fields
- [ ] Contact forms submit and send emails
- [ ] Search returns relevant results
- [ ] 404 page displays for invalid URLs
- [ ] Links to external sites work (new tab)

### 9.2 Responsiveness
- [ ] Mobile (320px - 767px)
- [ ] Tablet (768px - 1023px)
- [ ] Desktop (1024px+)
- [ ] Large screens (1440px+)

### 9.3 Browser Compatibility
- [ ] Chrome (latest)
- [ ] Firefox (latest)
- [ ] Safari (latest)
- [ ] Edge (latest)
- [ ] iOS Safari
- [ ] Android Chrome

### 9.4 Performance
- [ ] Lighthouse Performance score > 90
- [ ] Images optimized
- [ ] Caching enabled
- [ ] No render-blocking resources
- [ ] Core Web Vitals pass

### 9.5 SEO
- [ ] All pages have unique titles
- [ ] Meta descriptions set
- [ ] Schema markup validates
- [ ] XML sitemap generated
- [ ] robots.txt configured
- [ ] Canonical URLs set

---

## 10. Documentation Deliverables

### 10.1 User Documentation
- Adding/editing properties guide
- Managing property photos
- Updating team information
- Using the contact form
- Basic WordPress admin guide

### 10.2 Developer Documentation
- Theme structure overview
- ACF field reference
- Custom functions reference
- Deployment notes

---

## 11. Post-Launch Support

### 11.1 Included in Warranty (60 days)
- Bug fixes for custom code
- Functionality not working as designed
- Critical issues

### 11.2 Not Included (quoted separately)
- New features
- Design changes
- Third-party plugin issues
- Content updates
- Training beyond initial session

### 11.3 Ongoing Hosting Support (2 hrs/month)
- WordPress core updates
- Plugin updates
- Security monitoring
- Backup verification
- Minor content assistance

---

## 12. Risk Mitigation

| Risk | Mitigation |
|------|------------|
| ACF Pro license expiration | Included in hosting; developer manages renewal |
| Plugin conflicts | Minimal plugin approach; test thoroughly |
| Performance issues | Build lightweight; optimize images; use caching |
| Content delays | Clear client responsibilities; content deadline |
| Scope creep | Defined deliverables; change order process |
| Browser compatibility | Test on all major browsers before launch |

---

## 13. Timeline Summary

| Phase | Duration | Deliverable |
|-------|----------|-------------|
| 1. Foundation | 2 days | Theme framework |
| 2. Property System | 2 days | Property CPT + templates |
| 3. Page Templates | 2 days | All page templates |
| 4. Block Patterns | 1 day | Reusable patterns |
| 5. Content & SEO | 0.5 day | SEO setup + content |
| 6. Performance | 0.5 day | Optimized site |
| 7. Testing & Training | 1 day | Launch-ready |
| **Total** | **~8-9 days** | **Complete website** |

*Note: Actual calendar time may vary based on client feedback cycles.*

---

## 14. Open Questions / Decisions Needed

1. **Agent Management:** Use ACF options page or separate Agent CPT?
2. **Testimonials:** Static content or Testimonial CPT for easy management?
3. **Maps:** Google Maps embed or full API integration?
4. **Property Images:** Max file size / dimensions requirements?
5. **Email Notifications:** Which email(s) receive form submissions?

---

## 15. Approval

This implementation plan is a draft for review. Please confirm:
- Technology stack is acceptable
- Phase breakdown makes sense
- All required features are covered
- Any adjustments needed

---

## 16. Development Progress Log

### Phase 1: Foundation - COMPLETED
- [x] Git repository initialized
- [x] Database baseline snapshot created
- [x] Theme directory structure created
- [x] Vite + Tailwind build system configured
- [x] theme.json with brand colors configured
- [x] functions.php with includes structure
- [x] Header template with navigation and mobile menu
- [x] Footer template with contact info and social links
- [x] Base page templates (page.php, single.php, 404.php, index.php)
- [x] Content template parts created

**Technical Decisions:**
- Using Vite instead of Webpack (faster builds, simpler config)
- SCSS with co-located component styles (each component has PHP + SCSS + JS in same folder)
- Tailwind CSS for utilities, custom SCSS for components
- jQuery for JavaScript (per client mandate)
- CSS custom properties for design tokens

### Phase 2: Property System - COMPLETED
- [x] Property custom post type registered
- [x] Property taxonomies (type, status, location) with default terms
- [x] ACF free version installed (upgrade to Pro available if needed)
- [x] Property Details field group configured programmatically
- [x] Property card component with price, specs, status badge
- [x] Property archive template with hero and filters
- [x] Property results with pagination
- [x] AJAX property filtering with URL state management
- [x] Single property template with gallery, details, features, agent card
- [x] Lightbox gallery with thumbnail navigation

**Technical Decisions:**
- Using ACF free version (gallery uses relationship field to attachments)
- AJAX filtering updates URL for shareable/bookmarkable filter states
- Loading spinner only on first AJAX load (per mandate)
- Server-side filtering query built from GET/POST parameters
- Agent card falls back to company contact info if no agent assigned

**Files Created (Phase 2):**
- inc/custom-post-types.php
- inc/acf-fields.php
- inc/ajax-handlers.php
- archive-property.php
- single-property.php
- template-parts/property/property-card.php/.scss
- template-parts/property/property-filters.php/.scss/.js
- template-parts/property/property-results.php
- template-parts/property/property-gallery.php/.scss/.js
- template-parts/property/property-agent.php
- template-parts/property/single-property.scss

### Phase 3: Page Templates - PENDING
### Phase 4: Block Patterns - PENDING
### Phase 5: Content & SEO - PENDING
### Phase 6: Performance & Security - PENDING
### Phase 7: Testing & Launch - PENDING

---

*Document Version: 1.1*
*Last Updated: November 28, 2025*
*Prepared by: Hanson.xyz Development Team*
