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)

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

### v0.1.0 - Core Data Structures (Current)

- [x] Custom Post Type: Buildings
  - Meta fields: address, contact, description, images
  - Admin columns and filtering
  - Gutenberg block for display (planned for Phase 6)

- [x] 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)

- [x] Custom Taxonomy: Room Types
  - Standard, Suite, Family, Accessible, etc.
  - Hierarchical structure

- [x] Custom Taxonomy: Amenities
  - WiFi, Parking, Breakfast, etc.
  - Non-hierarchical (tags)

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

### Pricing Classes

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

### Price Configuration

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

### Price Calculation

- [x] Automatic tier detection based on duration
- [x] Price breakdown display
- [x] Discount handling (via seasonal modifiers)

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

### Custom Post Type: Bookings

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

### Calendar Integration

- [x] Availability calendar per room
- [x] Availability calendar per building
- [x] Date range picker for bookings
- [x] Conflict detection

### Booking Workflow

- [x] Booking creation (admin)
- [x] Status transitions
- [x] Email notifications
- [x] Booking confirmation

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

### Custom Post Type: Guests

- [x] Personal information (name, email, phone)
- [x] Address fields
- [x] ID/Passport information
- [x] Booking history reference
- [x] Notes and preferences

### Privacy & Compliance

- [x] GDPR compliance features
- [x] Data export functionality
- [x] Data deletion on request
- [x] Consent tracking

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

### Service Options

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

### Booking Services

- [x] Service selection during booking
- [x] Automatic price calculation
- [x] Service summary display

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

### Search & Filtering

- [x] Room search with filters
  - Date range (availability)
  - Capacity
  - Room type
  - Amenities
  - Price range
  - Building

### Display Components

- [x] Building list/grid shortcode
- [x] Room list/grid shortcode
- [x] Room detail template
- [x] Availability widget

### Gutenberg Blocks

- [x] Building block
- [x] Room block
- [x] Room search block
- [x] Buildings list block
- [x] Rooms list block

### Widgets

- [x] Similar rooms widget
- [x] Building rooms widget
- [x] Availability calendar widget

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

### Booking Request Form

- [x] Custom CF7 tags for rooms/dates
- [x] Form validation
- [x] Booking creation on submission
- [x] Email notifications

### Inquiry Form

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

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

### Admin Dashboard

- [x] Occupancy overview
- [x] Upcoming check-ins/check-outs
- [x] Revenue summary
- [x] Quick actions

### Reports

- [x] Occupancy report
- [x] Revenue report
- [x] Guest statistics
- [x] Export functionality (CSV, PDF)

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

- [x] 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
- [x] 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
- [x] Update settings page to enable/disable metrics

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

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

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

- [x] Payment processing
- [x] Invoice generation
- [x] Order management
- [x] Refund handling

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

- [x] Check for WordPress best-practices
- [x] Review the code for OWASP Top 10, including XSS, CSRF, SQLi and other critical threats
- [x] Test the API-Endpoints against a local live system under <http://localhost:9080/> for common vulnerabilities
- [x] 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

```text
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      |