wp-bnb/PLAN.md

WP BnB Implementation Plan

This document outlines the implementation plan for the WP BnB Management plugin.

Phase 1: Foundation (v0.0.x - v0.1.0)

v0.0.1 - Initial Setup (Current)

• Project structure and configuration files
• Composer dependencies (Twig, License Client)
• Git submodule for license client
• Main plugin file with version checks
• Plugin singleton class
• License Manager integration
• Admin menu and settings pages
• CI/CD pipeline for releases
• Basic CSS and JS assets
• Documentation (README, PLAN, CLAUDE)

v0.1.0 - Core Data Structures (Current)

• Custom Post Type: Buildings

  • Meta fields: address, contact, description, images
  • Admin columns and filtering
  • Gutenberg block for display (planned for Phase 6)

• Custom Post Type: Rooms

  • Meta fields: building reference, capacity, amenities, images
  • Relationship to Buildings (parent)
  • Admin columns with building filter
  • Gutenberg block for display (planned for Phase 6)

• Custom Taxonomy: Room Types

  • Standard, Suite, Family, Accessible, etc.
  • Hierarchical structure

• Custom Taxonomy: Amenities

  • WiFi, Parking, Breakfast, etc.
  • Non-hierarchical (tags)

Phase 2: Pricing System (v0.2.0) - Complete

Pricing Classes

• Short-term pricing (per night, 1-6 nights)
• Mid-term pricing (per week, 1-4 weeks)
• Long-term pricing (per month, 1+ months)

Price Configuration

• Room-level price settings
• Seasonal pricing periods
• Weekend/weekday differentiation
• Currency formatting and display

Price Calculation

• Automatic tier detection based on duration
• Price breakdown display
• Discount handling (via seasonal modifiers)

Phase 3: Booking System (v0.3.0) - Complete

Custom Post Type: Bookings

• Guest reference
• Room reference
• Check-in/check-out dates
• Status (pending, confirmed, checked-in, checked-out, cancelled)
• Price calculation and storage
• Notes field

Calendar Integration

• Availability calendar per room
• Availability calendar per building
• Date range picker for bookings
• Conflict detection

Booking Workflow

• Booking creation (admin)
• Status transitions
• Email notifications
• Booking confirmation

Phase 4: Guest Management (v0.4.0) - Complete

Custom Post Type: Guests

• Personal information (name, email, phone)
• Address fields
• ID/Passport information
• Booking history reference
• Notes and preferences

Privacy & Compliance

• GDPR compliance features
• Data export functionality
• Data deletion on request
• Consent tracking

Phase 5: Additional Services (v0.5.0) - Complete

Service Options

• Custom Post Type: Services
• Price per service (or included)
• Per-booking or per-night pricing
• Service categories

Booking Services

• Service selection during booking
• Automatic price calculation
• Service summary display

Phase 6: Frontend Features (v0.6.0) - Complete

Search & Filtering

• Room search with filters
  • Date range (availability)
  • Capacity
  • Room type
  • Amenities
  • Price range
  • Building

Display Components

• Building list/grid shortcode
• Room list/grid shortcode
• Room detail template
• Availability widget

Gutenberg Blocks

• Building block
• Room block
• Room search block
• Buildings list block
• Rooms list block

Widgets

• Similar rooms widget
• Building rooms widget
• Availability calendar widget

Phase 7: Contact Form 7 Integration (v0.7.0) - Complete

Booking Request Form

• Custom CF7 tags for rooms/dates
• Form validation
• Booking creation on submission
• Email notifications

Inquiry Form

• General inquiry handling
• Room-specific inquiries
• Auto-response templates (uses default CF7 mail templates)

Phase 8: Dashboard & Reports (v0.8.0) - Complete

Admin Dashboard

• Occupancy overview
• Upcoming check-ins/check-outs
• Revenue summary
• Quick actions

Reports

• Occupancy report
• Revenue report
• Guest statistics
• Export functionality (CSV, PDF)

Phase 9: Prometheus Metrics (v0.9.0) - Complete

• Meaningful Metrics for this Plugin:
  • Inventory: buildings, rooms by status, services by status
  • Bookings: by status, check-ins/check-outs today, upcoming, avg duration
  • Guests: total, by status, repeat guests, new this month
  • Occupancy: current rate, monthly rate, occupied rooms, bed capacity
  • Revenue: this month, YTD, average booking value, services revenue
• Example Grafana Dashboard:
  • Pre-configured dashboard JSON at assets/grafana/wp-bnb-dashboard.json
  • Automatic registration with wp-prometheus
  • 24 panels with gauges, pie charts, and stat displays
• Update settings page to enable/disable metrics

Phase 10: API Endpoints (v0.10.0) - Complete

• REST API for rooms (list, details, availability, calendar)
• REST API for availability (search available rooms)
• REST API for bookings (CRUD, status transitions)
• REST API for buildings, guests, services, pricing
• Authentication (Application Passwords, edit_posts capability)
• Transient-based rate limiting with tiered limits
• API settings tab with enable/disable toggles

Phase 11: WooCommerce Integration (v0.11.0) - Complete

• Payment processing
• Invoice generation
• Order management
• Refund handling

Phase 12: Security Audit (v0.12.0) - Complete

• Check for WordPress best-practices
• Review the code for OWASP Top 10, including XSS, CSRF, SQLi and other critical threats
• Test the API-Endpoints against a local live system under http://localhost:9080/ for common vulnerabilities
• Fix bugs discovered during security audit

Future Considerations (v1.0.0+)

Multi-language Support

• Full translation support
• WPML compatibility
• Polylang compatibility

Advanced Features

• Channel manager integration
• iCal sync
• Automated pricing rules
• Loyalty program support

Technical Architecture

Directory Structure

wp-bnb/
├── wp-bnb.php              # Main plugin file (entry point)
├── composer.json           # Composer configuration
├── composer.lock           # Dependency lock file
├── CHANGELOG.md            # Version history
├── CLAUDE.md               # AI assistant documentation
├── PLAN.md                 # Implementation roadmap
├── README.md               # User documentation
├── .editorconfig           # Editor configuration
├── .gitignore              # Git ignore patterns
├── .gitmodules             # Git submodule configuration
├── .gitea/
│   └── workflows/
│       └── release.yml     # CI/CD release pipeline
├── src/                    # PHP source (PSR-4: Magdev\WpBnb)
│   ├── Plugin.php          # Main plugin singleton
│   ├── Admin/              # Admin pages
│   │   ├── Calendar.php    # Availability calendar page
│   │   ├── Dashboard.php   # Dashboard page with statistics
│   │   ├── Reports.php     # Reports page with exports
│   │   └── Seasons.php     # Seasons management page
│   ├── Api/                # REST API (v0.10.0+)
│   │   ├── RestApi.php     # Main API registration
│   │   ├── RateLimiter.php # Transient-based rate limiting
│   │   ├── ResponseFormatter.php # Standardized responses
│   │   └── Controllers/    # API endpoint controllers
│   │       ├── AbstractController.php
│   │       ├── BookingsController.php
│   │       ├── BuildingsController.php
│   │       ├── GuestsController.php
│   │       ├── PricingController.php
│   │       ├── RoomsController.php
│   │       └── ServicesController.php
│   ├── Blocks/             # Gutenberg blocks
│   │   └── BlockRegistrar.php  # Block registration and rendering
│   ├── Booking/            # Booking logic
│   │   ├── Availability.php    # Availability checking
│   │   └── EmailNotifier.php   # Email notifications
│   ├── Frontend/           # Frontend components
│   │   ├── Search.php      # Room search and AJAX handlers
│   │   ├── Shortcodes.php  # All shortcode handlers
│   │   └── Widgets/        # WordPress widgets
│   │       ├── AvailabilityCalendar.php
│   │       ├── BuildingRooms.php
│   │       └── SimilarRooms.php
│   ├── Integration/        # Third-party integrations
│   │   ├── CF7.php         # Contact Form 7 integration
│   │   └── Prometheus.php  # Prometheus metrics
│   ├── License/            # License management
│   │   ├── Manager.php     # License validation and activation
│   │   └── Updater.php     # Auto-update system
│   ├── PostTypes/          # Custom post types
│   │   ├── Booking.php
│   │   ├── Building.php
│   │   ├── Guest.php
│   │   ├── Room.php
│   │   └── Service.php
│   ├── Pricing/            # Pricing logic
│   │   ├── Calculator.php  # Price calculation
│   │   ├── PricingTier.php # Pricing tier enum
│   │   └── Season.php      # Seasonal pricing
│   ├── Privacy/            # Privacy & GDPR
│   │   └── Manager.php     # Data export/deletion
│   └── Taxonomies/         # Custom taxonomies
│       ├── Amenity.php     # Amenities (tags)
│       ├── RoomType.php    # Room types (categories)
│       └── ServiceCategory.php  # Service categories
├── assets/                 # CSS, JS, images
│   ├── css/
│   │   ├── admin.css       # Admin styles
│   │   ├── blocks-editor.css   # Gutenberg editor styles
│   │   ├── cf7-integration.css # CF7 form styles
│   │   └── frontend.css    # Frontend styles
│   ├── grafana/
│   │   └── wp-bnb-dashboard.json  # Pre-configured Grafana dashboard
│   └── js/
│       ├── admin.js        # Admin scripts
│       ├── blocks-editor.js    # Gutenberg editor scripts
│       ├── cf7-integration.js  # CF7 form scripts
│       └── frontend.js     # Frontend scripts
├── languages/              # Translation files (.pot/.po/.mo)
├── lib/                    # Git submodules
│   └── wc-licensed-product-client/
├── releases/               # Release packages (git-ignored)
├── templates/              # Twig templates (reserved for future)
└── vendor/                 # Composer dependencies

Database Tables (Custom)

For performance with large datasets, custom tables may be added:

• {prefix}bnb_availability - Room availability cache
• {prefix}bnb_prices - Price history and seasonal rates
• {prefix}bnb_booking_services - Many-to-many booking/service relation

Hooks and Filters

The plugin will provide extensive hooks for customization:

• wp_bnb_before_booking_create
• wp_bnb_after_booking_create
• wp_bnb_calculate_price
• wp_bnb_room_availability
• wp_bnb_booking_statuses
• wp_bnb_email_templates

Version Milestones

Version	Focus	Target
0.0.1	Initial setup	Complete
0.1.0	Data structures	Complete
0.2.0	Pricing	Complete
0.3.0	Bookings	Complete
0.4.0	Guests	Complete
0.5.0	Services	Complete
0.6.0	Frontend	Complete
0.7.0	CF7 Integration	Complete
0.8.0	Dashboard	Complete
0.9.0	Prometheus Metrics	Complete
0.10.0	API Endpoints	Complete
0.11.0	WooCommerce Integration	Complete
0.12.0	Security Audit	Complete
1.0.0	Stable Release	TBD