# BW Babel — Phase 1 Foundation Build Progress

**Project:** BW Babel (Schema Markup Made Simple)  
**Phase:** 1 — Foundation Refactoring  
**Started:** 2026-08-05  
**Current Session:** Mosiah (Claude)

---

## Overview

Phase 1 extracts business logic into a services layer, creates a form builder, and modularizes the admin interface via page classes. **No user-facing changes** — just cleaner, maintainable code underneath.

All `bw_schema_*` references are migrated to `bw_babel_*` as work proceeds. Backward compatibility maintained.

---

## Tasks Completed

- [x] **Task 1.1: Create Services Layer** (COMPLETED 2026-08-05)
  - [x] BW_Babel_Service_Organization — CRUD + validation + field definitions
  - [x] BW_Babel_Service_Locations — Multi-location + rooms/accommodations management
  - [x] BW_Babel_Service_People — Authors, team, author box, redirect settings
  - [x] BW_Babel_Service_Survey — Survey config + response management + moderation
  - [x] BW_Babel_Service_Cache — Cache status, clearing, health checks
  - [ ] Unit tests (next phase)

- [ ] **Task 1.2: Create Form Builder** (2-3 days)
  - [ ] BW_Babel_Form_Builder
  - [ ] BW_Babel_Form_Fields
  - [ ] BW_Babel_Form_Validator
  - [ ] Tests

- [ ] **Task 1.3: Create Page Classes** (3-4 days)
  - [ ] BW_Babel_Page_Dashboard
  - [ ] BW_Babel_Page_Organization
  - [ ] BW_Babel_Page_Locations
  - [ ] BW_Babel_Page_People
  - [ ] BW_Babel_Page_Content
  - [ ] BW_Babel_Page_Tools
  - [ ] BW_Babel_Page_Help
  - [ ] Tests

- [ ] **Task 1.4: Refactor Admin Class** (1-2 days)
  - [ ] Simplify BW_Babel_Admin
  - [ ] Wire page classes
  - [ ] Menu routing

- [ ] **Task 1.5: Migration & Data** (1 day)
  - [ ] BW_Babel_Migration class
  - [ ] bw_schema_* → bw_babel_* mapping
  - [ ] Activation hook

- [ ] **Task 1.6: QA & Testing** (1 day)
  - [ ] Full site test
  - [ ] Settings save/load
  - [ ] No breaking changes

---

## Architecture Notes

### Services Layer Pattern

Each service handles business logic for one feature area:

```php
class BW_Babel_Service_Organization {
    /**
     * Get organization data from options
     */
    public static function get() { }
    
    /**
     * Save organization data to options
     */
    public static function save( $data ) { }
    
    /**
     * Validate organization data
     */
    public static function validate( $data ) { }
    
    /**
     * Get field definitions for form builder
     */
    public static function get_field_definitions() { }
}
```

**Key principle:** Services are:
- ✅ Static methods (stateless)
- ✅ No WordPress hooks (no side effects)
- ✅ Single responsibility (one feature area)
- ✅ Testable (pure functions)
- ✅ Reusable (can be called from pages, AJAX, CLI)

### Form Builder Pattern

Forms are defined declaratively, not in view files:

```php
$form = BW_Babel_Form_Builder::build_form( 'organization', [
    [
        'name' => 'org_name',
        'label' => __( 'Organization Name', 'bw-babel' ),
        'type' => 'text',
        'required' => true,
        'help' => __( 'Your official organization name', 'bw-babel' ),
        'sanitize' => 'sanitize_text_field',
        'validate' => function( $value ) { 
            return ! empty( $value ); 
        }
    ],
    // ... more fields
] );

// Render the form
echo $form->render();

// Process form submission
if ( $_POST ) {
    $result = $form->validate_and_save( $_POST );
}
```

### Page Classes Pattern

Each admin page is a class:

```php
class BW_Babel_Page_Organization {
    public function __construct() {
        $this->service = BW_Babel_Service_Organization::class;
    }
    
    public function render() {
        $data = $this->service::get();
        // ... render page
    }
    
    public function handle_save() {
        $data = // ... sanitize $_POST
        return $this->service::save( $data );
    }
}
```

---

## Current Session Work

### Starting Point

Current plugin structure (v2.6.0, bw-ai-schema-pro):
- Main admin logic in `includes/class-bw-schema-admin.php` (mixed concerns)
- Settings view in `admin/views/settings.php` (73KB monolith)
- Business logic scattered across `BW_Schema_Core`, `BW_Schema_*` classes
- No services layer
- No form builder
- No page classes

### Work Log

**2026-08-05 — Session Start: Task 1.1 COMPLETED**

✅ **Created 5 Services (admin/services/ directory):**

1. **class-bw-babel-service-organization.php** (210 lines)
   - Get/save/validate organization data
   - 20 field definitions for form builder
   - Business type options
   - Defaults for all fields
   - Sanitization for all input types

2. **class-bw-babel-service-locations.php** (280 lines)
   - Full location CRUD (create, read, update, delete)
   - Service areas management
   - Rooms/Accommodations module support
   - Multi-location queries with filtering
   - UUID generation for location IDs

3. **class-bw-babel-service-people.php** (250 lines)
   - Team/author configuration
   - Author box settings (enabled, position, post types)
   - Author archive redirect control
   - User default author assignment
   - Post author assignment and override
   - Team member queries

4. **class-bw-babel-service-survey.php** (300 lines)
   - Survey configuration (slug, opens/expires dates, notifications)
   - Response CRUD operations
   - Approval/rejection workflow
   - Moderator notes
   - Email notification logic
   - Survey activity status checks

5. **class-bw-babel-service-cache.php** (190 lines)
   - Cache enable/disable
   - Clear all/per-post cache
   - Cache status and size monitoring
   - Health check with issue detection
   - Last clear timestamp tracking

**Key Decisions Made:**
- Kept `bw_schema_*` prefix for backward compatibility (will migrate to `bw_babel_*` at v3.0.0-babel)
- All services use static methods (stateless)
- No WordPress hooks in services (pure business logic)
- Consistent validate → sanitize → save pattern
- All services return structured arrays or WP_Error for consistency
- Cache invalidation happens automatically in save methods

---

## Notes for Next Session

(Placeholder for handoff notes. Update here if pausing mid-task.)

---

## References

- Main plan: `/home/adi/BW_SCHEMA_PLUGIN_REFACTOR_PLAN.md`
- Current plugin: `bw-ai-schema-pro` v2.6.0
- Target: `bw-babel` v3.0.0-babel