# HomeProz WordPress - Step-by-Step Implementation Guide

This document provides atomic, testable steps for implementing the HomeProz WordPress site. Each step should be completed, tested, and committed before moving to the next.

**Reference:** See `CLAUDE.md` in webroot for coding mandates and technical specifications.

---

## Pre-Development Setup

### Step 0.1: Initialize Git Repository

**Task:** Create git repo in the WordPress installation directory.

```bash
cd /var/www/html
git init
echo "# HomeProz WordPress Site" > README.md
```

**Test:** Run `git status` - should show untracked files.

**Commit:**
```bash
git add README.md CLAUDE.md
git commit -m "Initial commit: project documentation"
```

---

### Step 0.2: Database Snapshot - Baseline

**Task:** Create initial database snapshot before any theme work.

```bash
mysqldump -u [user] -p homeproz > /var/www/html/db-snapshots/db-baseline.sql
mkdir -p /var/www/html/db-snapshots
```

**Test:** File exists and has reasonable size (should be small, just WP defaults).

**Commit:**
```bash
git add db-snapshots/
git commit -m "Baseline database snapshot"
```

---

## Phase 1: Foundation

### Step 1.1: Create Theme Directory Structure

**Task:** Create the homeproz theme folder with required files.

Create:
```
wp-content/themes/homeproz/
├── style.css          (with theme header comment)
├── functions.php      (empty, will populate)
├── index.php          (minimal template)
├── screenshot.png     (placeholder or actual)
└── src/
    ├── main.js
    ├── main.scss
    └── tailwind.css
```

**Test:**
1. Go to WordPress Admin → Appearance → Themes
2. "HomeProz" theme should appear (may show broken thumbnail)
3. Theme can be activated without fatal errors

**Commit:**
```bash
git add wp-content/themes/homeproz/
git commit -m "Phase 1.1: Theme directory structure"
```

---

### Step 1.2: Initialize Vite + Tailwind

**Task:** Set up build tooling in theme directory.

Create in `themes/homeproz/`:
- `package.json`
- `vite.config.js`
- `tailwind.config.js`
- `postcss.config.js`

Install dependencies:
```bash
cd wp-content/themes/homeproz
npm install
```

**Test:**
1. Run `npm run dev` - Vite dev server starts without errors
2. Run `npm run build` - Creates `dist/` folder with compiled assets

**Commit:**
```bash
git add wp-content/themes/homeproz/package*.json
git add wp-content/themes/homeproz/*.config.js
git add wp-content/themes/homeproz/dist/
git commit -m "Phase 1.2: Vite and Tailwind configuration"
```

---

### Step 1.3: Configure theme.json

**Task:** Create WordPress block editor configuration with HomeProz brand colors.

Create `theme.json` with:
- Color palette (dark theme colors)
- Typography settings (Abril Fatface, Inter)
- Spacing scale
- Layout widths

**Test:**
1. Activate theme
2. Create new page in WordPress
3. Block editor should show HomeProz colors in color picker
4. Font options should be available

**Commit:**
```bash
git add wp-content/themes/homeproz/theme.json
git commit -m "Phase 1.3: Block editor theme.json configuration"
```

---

### Step 1.4: Create functions.php with Includes Structure

**Task:** Set up functions.php to load modular includes.

Create:
- `functions.php` (loads includes)
- `inc/theme-setup.php` (theme supports, menus)
- `inc/enqueue.php` (scripts and styles)

**Test:**
1. Theme activates without errors
2. Check browser dev tools - Vite assets load
3. jQuery is available: open console, type `jQuery.fn.jquery` - shows version

**Commit:**
```bash
git add wp-content/themes/homeproz/functions.php
git add wp-content/themes/homeproz/inc/
git commit -m "Phase 1.4: functions.php and includes structure"
```

---

### Step 1.5: Build Header Template

**Task:** Create header.php with navigation.

Create:
- `header.php`
- `template-parts/header/site-header.php`
- `template-parts/header/site-header.scss`
- `template-parts/header/navigation.js`

Requirements:
- Logo area (left)
- Primary navigation menu (center/right)
- Mobile hamburger menu
- Body class must include page-specific class (e.g., `Home_Page`)

**Test:**
1. View any page on frontend
2. Header displays with logo area and nav
3. Inspect `<body>` tag - has appropriate class
4. Mobile view shows hamburger menu
5. Menu opens/closes on click

**Commit:**
```bash
git add wp-content/themes/homeproz/header.php
git add wp-content/themes/homeproz/template-parts/header/
git commit -m "Phase 1.5: Header template with navigation"
```

---

### Step 1.6: Build Footer Template

**Task:** Create footer.php with widget areas.

Create:
- `footer.php`
- `template-parts/footer/site-footer.php`
- `template-parts/footer/site-footer.scss`

Requirements:
- Logo
- Quick links
- Contact info
- Social media icons
- Copyright/legal text
- Widget areas registered in theme-setup.php

**Test:**
1. View any page on frontend
2. Footer displays at bottom
3. WordPress Admin → Appearance → Widgets shows footer widget areas
4. Footer content is styled correctly (dark theme)

**Commit:**
```bash
git add wp-content/themes/homeproz/footer.php
git add wp-content/themes/homeproz/template-parts/footer/
git commit -m "Phase 1.6: Footer template"
```

---

### Step 1.7: Create Base Page Template

**Task:** Build page.php as the default page template.

Create:
- `page.php`
- Add `Default_Page` body class logic

Requirements:
- Includes header and footer
- Content area with appropriate width constraints
- Supports WordPress block editor content

**Test:**
1. Create a new Page in WordPress admin
2. Add some content (headings, paragraphs, images)
3. View page on frontend
4. Content displays correctly with proper styling
5. Body has class `Default_Page`

**Commit:**
```bash
git add wp-content/themes/homeproz/page.php
git commit -m "Phase 1.7: Default page template"
```

---

### Step 1.8: Phase 1 Database Snapshot

**Task:** Snapshot database after foundation phase.

```bash
mysqldump -u [user] -p homeproz > db-snapshots/db-phase-1-foundation.sql
```

**Commit:**
```bash
git add -A
git commit -m "Phase 1 Complete: Foundation - theme scaffold, Vite, Tailwind, header, footer, base page"
```

---

## Phase 2: Property System

### Step 2.1: Register Property Custom Post Type

**Task:** Create the Property CPT.

Create:
- `inc/custom-post-types.php`
- Register `property` post type with labels, supports, archive

**Test:**
1. WordPress Admin shows "Properties" in sidebar
2. Can create a new Property
3. Property has title, editor, featured image
4. Visit `/properties/` - archive page exists (may be unstyled)

**Commit:**
```bash
git add wp-content/themes/homeproz/inc/custom-post-types.php
git commit -m "Phase 2.1: Property custom post type"
```

---

### Step 2.2: Register Property Taxonomies

**Task:** Create taxonomies for filtering.

Add to `custom-post-types.php`:
- `property_type` (Residential, Commercial, Land, Multi-Family)
- `property_status` (Active, Pending, Sold)
- `property_location` (Cities)

**Test:**
1. Edit a Property - taxonomy meta boxes appear
2. Can add terms to each taxonomy
3. Terms save correctly

**Commit:**
```bash
git add wp-content/themes/homeproz/inc/custom-post-types.php
git commit -m "Phase 2.2: Property taxonomies"
```

---

### Step 2.3: Install and Configure ACF Pro

**Task:** Install ACF Pro and create Property field group.

1. Install ACF Pro plugin
2. Create field group "Property Details"

Create:
- `inc/acf-fields.php` (programmatic field registration or export JSON)

Fields needed:
- property_status (if not using taxonomy)
- price (number)
- mls_number (text)
- street_address, city, state, zip (text fields)
- bedrooms, bathrooms, square_feet (numbers)
- lot_size, year_built, garage (text/number/select)
- gallery (gallery field)
- short_description (textarea)
- features (checkbox or repeater)
- listing_agent (post object or user)

**Test:**
1. Edit a Property
2. All ACF fields appear below editor
3. Can enter data in all fields
4. Data saves and persists on reload

**Commit:**
```bash
git add wp-content/themes/homeproz/inc/acf-fields.php
git add wp-content/plugins/advanced-custom-fields-pro/  # if committing plugin
git commit -m "Phase 2.3: ACF Pro with Property fields"
```

---

### Step 2.4: Build Property Card Component

**Task:** Create reusable property card template part.

Create:
- `template-parts/property/property-card.php`
- `template-parts/property/property-card.scss`

Requirements:
- Featured image (16:10 aspect ratio)
- Status badge (colored by status)
- Price
- Address
- Bed/bath/sqft icons
- "View Details" link

**Test:**
1. Create a test property with all fields filled
2. Include property-card.php in index.php temporarily
3. Card displays correctly with all data
4. Status badge shows correct color
5. Responsive on mobile

**Commit:**
```bash
git add wp-content/themes/homeproz/template-parts/property/
git commit -m "Phase 2.4: Property card component"
```

---

### Step 2.5: Build Property Archive Template

**Task:** Create the properties listing page.

Create:
- `archive-property.php`
- `template-parts/property/property-filters.php`
- `template-parts/property/property-filters.scss`
- `template-parts/property/property-filters.js`

Requirements:
- Hero section with title
- Filter bar (Type, Price, Beds, Status dropdowns)
- Results count
- Property cards in grid (3 col desktop, 2 tablet, 1 mobile)
- Pagination
- Body class: `Properties_Archive`

**Test:**
1. Create 6+ test properties with varying data
2. Visit `/properties/`
3. All properties display in grid
4. Filters appear (functionality in next step)
5. Pagination works if enough posts
6. Responsive layout works

**Commit:**
```bash
git add wp-content/themes/homeproz/archive-property.php
git commit -m "Phase 2.5: Property archive template"
```

---

### Step 2.6: Implement AJAX Property Filtering

**Task:** Make filters functional with AJAX.

Update:
- `property-filters.js` - jQuery AJAX on filter change
- `inc/ajax-handlers.php` - WordPress AJAX endpoint
- `functions.php` - register AJAX actions

Requirements:
- Filters update results without page reload
- Show spinner on FIRST load only
- Subsequent filter changes show old results until new arrive
- Results count updates
- URL updates with filter state (for shareability)

**Test:**
1. Visit `/properties/`
2. Change a filter dropdown
3. Results update without page reload
4. Spinner shows briefly on first interaction
5. Changing filters again does NOT show spinner (old data visible)
6. URL reflects filter state
7. Direct link to filtered URL works

**Commit:**
```bash
git add wp-content/themes/homeproz/inc/ajax-handlers.php
git add wp-content/themes/homeproz/template-parts/property/property-filters.js
git commit -m "Phase 2.6: AJAX property filtering"
```

---

### Step 2.7: Build Single Property Template

**Task:** Create the property detail page.

Create:
- `single-property.php`
- `template-parts/property/property-gallery.php`
- `template-parts/property/property-gallery.scss`
- `template-parts/property/property-gallery.js`
- `template-parts/property/property-details.php`
- `template-parts/property/property-agent.php`

Requirements:
- Breadcrumb navigation
- Photo gallery with lightbox
- Property details sidebar (sticky on desktop)
- Full description
- Features list
- Location/map section
- Agent contact card
- Body class: `Single_Property`

**Test:**
1. View a property with all fields filled
2. Gallery displays and lightbox works
3. All property data displays correctly
4. Agent card shows with contact info
5. Sidebar sticks on scroll (desktop)
6. Mobile layout is single column

**Commit:**
```bash
git add wp-content/themes/homeproz/single-property.php
git add wp-content/themes/homeproz/template-parts/property/
git commit -m "Phase 2.7: Single property template"
```

---

### Step 2.8: Phase 2 Database Snapshot

**Task:** Snapshot database after property system phase.

```bash
mysqldump -u [user] -p homeproz > db-snapshots/db-phase-2-property-system.sql
```

**Commit:**
```bash
git add -A
git commit -m "Phase 2 Complete: Property system - CPT, ACF, archive, single, AJAX filters"
```

---

## Phase 3: Page Templates

### Step 3.1: Build Homepage Template

**Task:** Create the homepage with modular sections.

Create:
- `front-page.php`
- `template-parts/components/hero-section.php`
- `template-parts/components/hero-section.scss`
- `template-parts/components/featured-properties.php`
- `template-parts/components/value-props.php`
- `template-parts/components/team-preview.php`
- `template-parts/components/testimonial.php`
- `template-parts/components/cta-section.php`

Requirements:
- Hero with headline, subheadline, CTAs
- Featured properties (3 most recent active)
- Value proposition grid (3 columns)
- Team preview section
- Testimonials
- Contact CTA section
- Body class: `Home_Page`

**Test:**
1. Set a static front page in Settings → Reading
2. Visit homepage
3. All sections display in order
4. Featured properties show real data
5. Responsive on all breakpoints
6. CTAs link to correct pages

**Commit:**
```bash
git add wp-content/themes/homeproz/front-page.php
git add wp-content/themes/homeproz/template-parts/components/
git commit -m "Phase 3.1: Homepage template with sections"
```

---

### Step 3.2: Build About Page Template

**Task:** Create the About/Team page.

Create:
- `page-about.php`
- `template-parts/components/agent-card.php`
- `template-parts/components/agent-card.scss`

Requirements:
- Page hero
- Company story content area
- Mission/values section
- Team grid (4 agents)
- Broker information
- Contact CTA
- Body class: `About_Page`

**Test:**
1. Create page with slug "about"
2. Add company content in editor
3. View page - custom template loads
4. Team members display (from ACF options or CPT)
5. All sections styled correctly

**Commit:**
```bash
git add wp-content/themes/homeproz/page-about.php
git commit -m "Phase 3.2: About page template"
```

---

### Step 3.3: Build Contact Page Template

**Task:** Create the Contact page with form.

Create:
- `page-contact.php`
- `template-parts/components/contact-form.php`
- `template-parts/components/contact-info.php`

Requirements:
- Page hero
- Two-column layout: form left, info right
- Contact Form 7 integration
- Address, phone, email display
- Google Maps embed
- Body class: `Contact_Page`

**Test:**
1. Install Contact Form 7 plugin
2. Create contact form
3. Create page with slug "contact"
4. Add form shortcode to page or template
5. View page - form displays
6. Submit form - email received
7. Map displays correctly

**Commit:**
```bash
git add wp-content/themes/homeproz/page-contact.php
git add wp-content/themes/homeproz/template-parts/components/contact-*.php
git commit -m "Phase 3.3: Contact page template"
```

---

### Step 3.4: Build Blog Archive Template

**Task:** Create the blog listing page.

Create:
- `archive.php`
- `template-parts/content/post-card.php`
- `template-parts/content/post-card.scss`
- `sidebar.php`
- `template-parts/sidebar/sidebar-blog.php`

Requirements:
- Page hero
- Two-column layout: posts left, sidebar right
- Post cards with featured image, title, excerpt, date
- Pagination
- Sidebar with search, categories, recent posts
- Body class: `Blog_Archive`

**Test:**
1. Create 4+ blog posts with featured images
2. Set Posts page in Settings → Reading
3. Visit blog page
4. Posts display in grid/list
5. Sidebar widgets work
6. Pagination works
7. Responsive layout

**Commit:**
```bash
git add wp-content/themes/homeproz/archive.php
git add wp-content/themes/homeproz/sidebar.php
git add wp-content/themes/homeproz/template-parts/content/
git add wp-content/themes/homeproz/template-parts/sidebar/
git commit -m "Phase 3.4: Blog archive template"
```

---

### Step 3.5: Build Single Post Template

**Task:** Create the blog post template.

Create:
- `single.php`
- `template-parts/content/content-single.php`
- `template-parts/content/author-bio.php`
- `template-parts/content/related-posts.php`

Requirements:
- Featured image header
- Post title, date, author, category
- Content area
- Sidebar
- Author bio box
- Related posts (3)
- Body class: `Single_Post`

**Test:**
1. View a blog post
2. All elements display correctly
3. Author bio shows
4. Related posts appear
5. Sidebar displays
6. Content styling matches design

**Commit:**
```bash
git add wp-content/themes/homeproz/single.php
git commit -m "Phase 3.5: Single post template"
```

---

### Step 3.6: Build Additional Templates

**Task:** Create remaining page templates.

Create:
- `template-full-width.php`
- `template-landing.php`
- `search.php`
- `404.php`

Requirements:
- Full width: no max-width constraint
- Landing: minimal header/footer
- Search: results display, property cards for properties, list for posts
- 404: friendly message, search, quick links
- Appropriate body classes for each

**Test:**
1. Create page, select "Full Width" template - no sidebar, full width
2. Create page, select "Landing Page" - minimal header/footer
3. Use site search - results page works
4. Visit invalid URL - 404 page displays

**Commit:**
```bash
git add wp-content/themes/homeproz/template-*.php
git add wp-content/themes/homeproz/search.php
git add wp-content/themes/homeproz/404.php
git commit -m "Phase 3.6: Additional page templates"
```

---

### Step 3.7: Phase 3 Database Snapshot

**Task:** Snapshot database after page templates phase.

```bash
mysqldump -u [user] -p homeproz > db-snapshots/db-phase-3-page-templates.sql
```

**Commit:**
```bash
git add -A
git commit -m "Phase 3 Complete: Page templates - homepage, about, contact, blog, 404, search"
```

---

## Phase 4: Block Patterns

### Step 4.1: Create Block Patterns

**Task:** Build reusable Gutenberg patterns.

Create:
- `patterns/hero-cta.php`
- `patterns/feature-grid.php`
- `patterns/team-grid.php`
- `patterns/testimonial.php`
- `patterns/split-content.php`
- `patterns/cta-banner.php`
- `inc/block-patterns.php`

**Test:**
1. Edit any page in WordPress
2. Open block inserter → Patterns
3. HomeProz patterns appear
4. Insert each pattern - displays correctly
5. Patterns are editable

**Commit:**
```bash
git add wp-content/themes/homeproz/patterns/
git add wp-content/themes/homeproz/inc/block-patterns.php
git commit -m "Phase 4.1: Block patterns"
```

---

### Step 4.2: Editor Styles

**Task:** Make block editor match frontend.

Create/update:
- `src/editor.scss`
- Update `enqueue.php` to add editor styles

**Test:**
1. Edit a page in WordPress
2. Editor styling matches frontend (colors, fonts, spacing)
3. Blocks preview accurately

**Commit:**
```bash
git add wp-content/themes/homeproz/src/editor.scss
git commit -m "Phase 4.2: Editor styles"
```

---

### Step 4.3: Phase 4 Database Snapshot

**Task:** Snapshot database after patterns phase.

```bash
mysqldump -u [user] -p homeproz > db-snapshots/db-phase-4-patterns.sql
```

**Commit:**
```bash
git add -A
git commit -m "Phase 4 Complete: Block patterns and editor styles"
```

---

## Phase 5: Content & SEO

### Step 5.1: Install and Configure SEO Plugin

**Task:** Set up Yoast SEO or Rank Math.

1. Install plugin
2. Run setup wizard
3. Configure basic settings

**Test:**
1. Edit a page/property - SEO meta box appears
2. Can edit title, description
3. View page source - meta tags present

**Commit:**
```bash
git commit -m "Phase 5.1: SEO plugin configured"
```

---

### Step 5.2: Add Schema Markup

**Task:** Implement structured data.

Update templates to include:
- RealEstateAgent schema (about page, agent cards)
- RealEstateListing schema (single property)
- LocalBusiness schema (footer/contact)

**Test:**
1. View page source - JSON-LD schema present
2. Test with Google Rich Results Test
3. No schema errors

**Commit:**
```bash
git commit -m "Phase 5.2: Schema.org structured data"
```

---

### Step 5.3: Enter Initial Content

**Task:** Populate site with real content.

1. Homepage content
2. About page content + team data
3. Contact information
4. Sample properties (or real listings)
5. Sample blog posts (optional)

**Test:**
1. Browse entire site
2. No placeholder/lorem ipsum text visible
3. All images load
4. Contact info is accurate

**Commit:**
```bash
mysqldump -u [user] -p homeproz > db-snapshots/db-phase-5-content.sql
git add -A
git commit -m "Phase 5 Complete: SEO and initial content"
```

---

## Phase 6: Performance & Security

### Step 6.1: Caching and Optimization

**Task:** Install and configure performance plugins.

1. Install caching plugin (WP Super Cache or LiteSpeed)
2. Configure caching rules
3. Enable GZIP compression
4. Verify lazy loading for images

**Test:**
1. Run Lighthouse audit
2. Performance score > 80
3. Page load time < 3s
4. Images lazy load on scroll

**Commit:**
```bash
git commit -m "Phase 6.1: Caching and performance optimization"
```

---

### Step 6.2: Security Hardening

**Task:** Configure security measures.

1. Install Wordfence or similar
2. Configure firewall rules
3. Enable login protection
4. Verify SSL/HTTPS
5. Set up automated backups

**Test:**
1. Site loads over HTTPS only
2. Security plugin dashboard shows no critical issues
3. Backup runs successfully

**Commit:**
```bash
git commit -m "Phase 6.2: Security hardening"
```

---

### Step 6.3: Phase 6 Database Snapshot

```bash
mysqldump -u [user] -p homeproz > db-snapshots/db-phase-6-optimization.sql
git add -A
git commit -m "Phase 6 Complete: Performance and security"
```

---

## Phase 7: Testing & Launch

### Step 7.1: Full QA Testing

**Task:** Complete testing checklist.

Test all items in IMPLEMENTATION-PLAN.md Section 9:
- [ ] Functionality tests
- [ ] Responsiveness tests
- [ ] Browser compatibility
- [ ] Performance benchmarks
- [ ] SEO verification

Document any issues found.

---

### Step 7.2: Create Documentation

**Task:** Write user documentation.

Create:
- Property listing guide
- WordPress basics guide
- Contact form management

**Deliver to:** Client as PDF or in WordPress admin.

---

### Step 7.3: Client Training

**Task:** Conduct training session.

Cover:
- Adding/editing properties
- Managing photos
- Updating pages
- Viewing form submissions

---

### Step 7.4: Final Snapshot and Launch

```bash
mysqldump -u [user] -p homeproz > db-snapshots/db-final-prelaunch.sql
git add -A
git commit -m "Phase 7 Complete: QA tested, documented, ready for launch"
git tag v1.0.0
```

---

## Post-Launch

- Monitor for issues first 48 hours
- Verify backups running
- Check form submissions working
- Begin 60-day warranty period

---

## Quick Reference: Git Workflow

After completing any step:
```bash
# If database changed
mysqldump -u [user] -p homeproz > db-snapshots/db-[description].sql

# Always
git add -A
git commit -m "[Phase X.X]: [Description of what was done]"
```

After completing each phase:
```bash
mysqldump -u [user] -p homeproz > db-snapshots/db-phase-X-[name].sql
git add -A
git commit -m "Phase X Complete: [Summary]"
```