Add dev_commit.sh helper and no-emoji mandate

2025-11-28 16:05:26 -06:00
parent fc7c6b0844
commit 7650362efe
3260 changed files with 1429683 additions and 0 deletions
@@ -0,0 +1,679 @@
+# 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
+
+---
+
+*Document Version: 1.0*
+*Date: November 28, 2025*
+*Prepared by: Hanson.xyz Development Team*