homeproz/contract/Contracts/WordPress-Website/_scratch/site_analysis/IMPLEMENTATION-PLAN.md

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

// 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

// 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:

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

// 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

{
    "$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

• Git repository initialized
• Database baseline snapshot created
• Theme directory structure created
• Vite + Tailwind build system configured
• theme.json with brand colors configured
• functions.php with includes structure
• Header template with navigation and mobile menu
• Footer template with contact info and social links
• Base page templates (page.php, single.php, 404.php, index.php)
• 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

• Property custom post type registered
• Property taxonomies (type, status, location) with default terms
• ACF free version installed (upgrade to Pro available if needed)
• Property Details field group configured programmatically
• Property card component with price, specs, status badge
• Property archive template with hero and filters
• Property results with pagination
• AJAX property filtering with URL state management
• Single property template with gallery, details, features, agent card
• 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 - COMPLETED

• Homepage template (front-page.php) with hero, featured properties, features, team, testimonials, CTA
• About page template (page-about.php) with story, values, team, broker info
• Contact page template (page-contact.php) with form, contact info, map
• Blog archive template (archive.php, home.php) with posts grid and sidebar
• Single post template (single.php) with featured image, sidebar, related posts
• Search results template (search.php) with mixed content types
• Full-width page template (template-full-width.php)
• Landing page template (template-landing.php) with minimal header/footer
• Contact Form 7 installed and configured
• WordPress pages created (Home, About, Contact, Blog)
• Static front page and blog page configured
• Primary navigation menu created

Reusable Components Created:

• template-parts/components/hero-section.php/.scss
• template-parts/components/cta-section.php/.scss
• template-parts/components/testimonial.php/.scss
• template-parts/components/agent-card.php/.scss
• template-parts/components/feature-block.php/.scss
• template-parts/sidebar/blog-sidebar.php/.scss

Technical Decisions:

• All page templates follow page-scoped CSS pattern (body class wrapping)
• Contact Form 7 for forms (can be styled with theme styles)
• Team data hardcoded (can be replaced with ACF repeater or Team CPT later)
• Testimonials hardcoded (can be replaced with Testimonials CPT later)
• Blog sidebar includes search, categories, recent posts, CTA widget
• Single post shows related posts from same category

Phase 4: Block Patterns - COMPLETED

• Hero with CTA pattern (full-width cover block with heading, text, buttons)
• Feature Grid (3-col) pattern (columns with card backgrounds)
• Team Grid pattern (4-column agent cards with placeholders)
• Testimonial pattern (quote block with attribution)
• Split Content pattern (image + text two-column layout)
• CTA Banner pattern (accent background with heading and button)
• Contact Info pattern (address, phone, email, hours)
• Custom "HomeProz" pattern category registered
• Editor styles created (editor.scss compiled to editor.css)
• Vite config updated for editor entry point

Block Patterns Created:

• patterns/hero-cta.php
• patterns/feature-grid.php
• patterns/team-grid.php
• patterns/testimonial.php
• patterns/split-content.php
• patterns/cta-banner.php
• patterns/contact-info.php

Technical Decisions:

• Using WordPress 6.0+ pattern file format (PHP files with header comments)
• Patterns use inline styles with theme color values for consistency
• No emojis used in patterns (per mandate)
• Editor styles match frontend design tokens
• Placeholder images use via.placeholder.com (to be replaced with real images)

Phase 5: Content & SEO - COMPLETED

• Yoast SEO plugin installed and configured
• SEO titles and meta descriptions configured for all post types
• Schema.org structured data markup implemented:
  • RealEstateAgent/LocalBusiness schema (sitewide)
  • RealEstateListing schema (single property pages)
  • WebSite schema with SearchAction (homepage)
  • BreadcrumbList schema (all pages except homepage)
• Open Graph and Twitter Card meta tags configured via Yoast
• Favicon/site icon support enabled (uses WordPress Customizer)
• Theme color meta tags for mobile browsers
• XML sitemap enabled and accessible at /sitemap_index.xml
• Rewrite rules flushed for proper URL handling

Files Created:

• inc/schema-markup.php (custom Schema.org JSON-LD output)

Technical Decisions:

• Using Yoast SEO free version for SEO management
• Custom Schema.org markup in addition to Yoast's schema (more specific real estate types)
• Site icon/favicon managed via WordPress Customizer (Appearance > Customize > Site Identity)
• Theme color set to #0A0A0A (background dark) for mobile browser chrome

Phase 6: Performance & Security - COMPLETED (Partial)

• WebP image conversion via "Converter for Media" plugin
• Nginx rewrite rules for serving WebP to supported browsers
• Server dependencies documented in DEPENDENCIES.md
• Caching plugin - SKIPPED (not requested)
• Security plugin - SKIPPED (not requested)
• Backups plugin - SKIPPED (not requested)

Technical Details:

• Plugin: Converter for Media v6.3.2
• Conversion method: PHP GD/Imagick (both available, WebP supported)
• WebP files stored in: /wp-content/uploads-webpc/
• Nginx serves WebP when browser sends Accept: image/webp header
• No external APIs or services used (fully local processing)

Files Created:

• /var/www/html/DEPENDENCIES.md (server dependency documentation)

Files Modified:

• /etc/nginx/sites-available/default (WebP rewrite rules added)

Phase 7: Testing & Launch - PENDING

---

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