# IGNY8 WordPress Bridge – Implementation Plan

## Objectives
- Keep WordPress as a lightweight publishing edge while IGNY8 SaaS remains the control plane.
- Automate all sync flows once the site connects (no repeated manual buttons).
- Provide hooks for Sites, Planner, Writer, Linker, and Optimizer modules using the endpoints defined in `WORDPRESS-PLUGIN-INTEGRATION.md`.

## Assumptions
1. Existing IGNY8 REST API endpoints (auth, sites, planner, writer) follow the unified response format.
2. WordPress environment runs PHP ≥ 7.4 with REST API enabled and (optionally) WooCommerce.
3. SaaS app can call back into WordPress via authenticated REST endpoints/webhooks.

## Work Breakdown

### Phase 1 – Foundations
| Step | WordPress Tasks | IGNY8 API Usage |
| --- | --- | --- |
| 1.1 | Harden credential storage (option encryption, refresh tracking) | `/auth/login/`, `/auth/refresh/` |
| 1.2 | Build diagnostics card (ping, last sync, token age) | `/system/ping/` (or `/planner/keywords/?page_size=1` as health check) |
| 1.3 | Add “control model” + post-type/Woo toggles on settings page | `GET /system/sites/{id}/` (to pull recommended defaults) |

### Phase 2 – Automatic Taxonomy & Keyword Sync
| Step | WordPress Tasks | IGNY8 API Usage |
| --- | --- | --- |
| 2.1 | Scheduled fetch of sectors/clusters; populate `igny8_sectors`, `igny8_clusters` | `/planner/sectors/`, `/planner/clusters/` |
| 2.2 | Pull Planner keywords per cluster and store `_igny8_keyword_ids` meta | `/planner/keywords/?cluster_id=` |
| 2.3 | Render read-only badges in list tables and editor side panels | — (local data) |

### Phase 3 – Writer Module Integration
| Step | WordPress Tasks | IGNY8 API Usage |
| --- | --- | --- |
| 3.1 | Cron or webhook to fetch new/updated tasks and create posts | `/writer/tasks/?site_id=&status=` |
| 3.2 | Hook `save_post` / `transition_post_status` to push status & URLs | `/writer/tasks/{id}/` (PUT) |
| 3.3 | Store briefs/outlines on post meta for editors | `/writer/tasks/{id}/brief/` |
| 3.4 | Queue visualization (counts, failures) in settings page | — (local logs) |

### Phase 4 – Sites Module & Semantic Mapping
| Step | WordPress Tasks | IGNY8 API Usage |
| --- | --- | --- |
| 4.1 | Implement incremental + full site-data collectors honoring toggles | — (WP data) |
| 4.2 | Schedule automatic submission of site payloads | `/system/sites/{id}/import/` (full) |
| 4.3 | Track semantic map metadata locally for reporting | `/planner/sites/{id}/semantic-map/` |

### Phase 5 – Planner, Linker, Optimizer Hooks
| Step | WordPress Tasks | IGNY8 API Usage |
| --- | --- | --- |
| 5.1 | Display Planner briefs/tasks per post; allow “request refresh” actions | `/planner/tasks/{id}/brief/`, `/planner/tasks/{id}/refresh/` |
| 5.2 | Export WP link graph during site scans | `/linker/link-map/` (POST) |
| 5.3 | Accept link recommendations via webhook and queue insertions | SaaS → WP REST endpoint (new) |
| 5.4 | Expose optimizer triggers (metrics requests, re-optimization) | `/optimizer/jobs/` (POST), `/optimizer/jobs/{id}/` |

### Phase 6 – Webhooks & Remote Control
| Step | WordPress Tasks | IGNY8 API Usage |
| --- | --- | --- |
| 6.1 | Register REST routes (`/wp-json/igny8/v1/event`) with shared secret | — (incoming) |
| 6.2 | Handle SaaS events: task published, link recommendation, optimizer request | SaaS posts payloads; responses follow unified JSON |
| 6.3 | Persist webhook activity logs (custom table or option) | — |

### Phase 7 – Automation & Monitoring
| Step | WordPress Tasks | IGNY8 API Usage |
| --- | --- | --- |
| 7.1 | WP-CLI commands (`wp igny8 sync posts`, `sync site`) to mirror SaaS automation | Same endpoints as UI |
| 7.2 | Admin notices + status widget for sync health (error counts, tokens) | `/system/sites/{id}/status/` (if available) |
| 7.3 | Structured logging (maybe `wp_igny8_logs` table) for audits | — |

## Deliverables
1. Updated plugin code implementing all phases.
2. Settings UI redesign with automatic operations (no manual sync buttons post-setup).
3. REST endpoints + cron jobs documented for SaaS team.
4. Test plan covering happy path, token expiry, webhook retries.

## Timeline (Rough)
| Phase | Est. Effort | Notes |
| --- | --- | --- |
| 1 | 2–3 days | Mostly admin UI + auth refactor |
| 2 | 3 days | Taxonomies + keywords + scheduling |
| 3 | 3–4 days | Writer hooks + automatic task ingestion |
| 4 | 2 days | Site data automation |
| 5 | 4 days | Requires close coordination with SaaS teams |
| 6 | 2 days | REST/webhook security |
| 7 | 1–2 days | Tooling & monitoring |

Effort assumes endpoints already exist; see `docs/missing-saas-api-endpoints.md` for gaps.