# STAGE 2 FRONTEND REFACTOR - DETAILED EXECUTION PLAN

**Created:** November 25, 2025  
**Status:** Planning Complete - Ready for Execution

---

## 📊 SCOPE ANALYSIS

**Total Frontend Files:** 413 TypeScript files  
**Files with Deprecated Fields:** 17 identified  
**Major Modules to Update:** 6 (Planner, Writer, Sites, Settings, Linker, Optimizer)

---

## 🎯 EXECUTION SEQUENCE

### PHASE 1: Core API & Type Definitions (Foundation)
**Priority:** CRITICAL - Must be done first  
**Estimated Changes:** ~500 lines across 2-3 files

#### 1.1 Update API Service (`src/services/api.ts`)
**File:** `frontend/src/services/api.ts` (2482 lines)

**Changes Required:**

**ContentIdea Interface (Lines 770-783):**
- ❌ Remove: `site_entity_type`, `cluster_role`
- ✅ Keep: `content_structure`, `content_type`

**Task Interface (Lines 930-940):**
- ❌ Remove: `entity_type`, `cluster_role`
- ✅ Add: `content_type` (if missing)
- ✅ Add: `content_structure` (if missing)
- ✅ Add: `taxonomy_term_id` (optional)

**Content Interface (Lines 2010-2030):**
- ❌ Remove: `entity_type`, `cluster_role`, `sync_status`
- ✅ Add: `content_type` (required)
- ✅ Add: `content_structure` (required)
- ✅ Add: `taxonomy_terms` (array of taxonomy objects)
- ✅ Add: `source` ('igny8' | 'wordpress')
- ✅ Update `status` type to ('draft' | 'published')

**ContentValidation Interface (Lines 2095-2110):**
- ❌ Remove: `has_entity_type`, `entity_type`
- ✅ Add: `has_content_type`, `content_type`

**Filter Interfaces:**
- Update `TasksFilters` to include `content_type`, `content_structure`
- Update `ContentFilters` to include `content_type`, `content_structure`, `source`

#### 1.2 Update Integration API (`src/services/integration.api.ts`)
**Changes Required:**
- Update `sync_status` type from custom to match backend
- Remove any deprecated field references

---

### PHASE 2: Configuration Files (Data Layer)
**Priority:** HIGH - Defines table columns and filters  
**Estimated Changes:** ~300 lines across 3 files

#### 2.1 Tasks Config (`src/config/pages/tasks.config.tsx`)
**Changes:**
- Update column definitions: remove `entity_type`, `cluster_role`
- Add columns: `content_type`, `content_structure`
- Update filters: replace deprecated with new fields
- Update status options to: `queued`, `completed`

#### 2.2 Content Config (`src/config/pages/content.config.tsx`)
**Changes:**
- Update column definitions: remove `entity_type`, `cluster_role`, `sync_status`
- Add columns: `content_type`, `content_structure`, `source`, `taxonomy_terms`
- Update filters: add `content_type`, `content_structure`, `source`
- Update status options to: `draft`, `published`

#### 2.3 Ideas Config (`src/config/pages/ideas.config.tsx`)
**Changes:**
- Remove: `site_entity_type`, `cluster_role`
- Ensure: `content_type`, `content_structure` are present

---

### PHASE 3: Zustand Stores (State Management)
**Priority:** HIGH - Core state management  
**Estimated Changes:** ~100 lines across 2 files

#### 3.1 Planner Store (`src/store/plannerStore.ts`)
**Changes:**
- Update task state interface to match new API types
- Remove deprecated field handling

#### 3.2 Create/Update Content Store
**Action:** Check if exists, if not create new store for content state management
- Handle `status`: draft, published
- Handle `source`: igny8, wordpress
- Handle `taxonomy_terms` array

---

### PHASE 4: Planner Module (Part B)
**Priority:** MEDIUM  
**Estimated Changes:** ~400 lines across 3 files

#### 4.1 Clusters Page (`src/pages/Planner/Clusters.tsx`)
**Changes:**
- Make cluster names clickable → navigate to `/clusters/:id`
- Remove any `context_type` or `dimension_meta` displays
- Clean up cluster card UI

#### 4.2 Ideas Page (`src/pages/Planner/Ideas.tsx`)
**Current:** 15,062 lines  
**Changes:**
- Update idea cards to show: cluster, `content_type`, `content_structure`
- Remove: `site_entity_type`, `cluster_role`
- Update create/edit forms

#### 4.3 Planner Dashboard (`src/pages/Planner/Dashboard.tsx`)
**Changes:**
- Remove deprecated field displays
- Update task creation form:
  - Required: cluster, content_type, content_structure
  - Optional: taxonomy_term (only when content_type = 'taxonomy')
  - Remove: cluster_role, entity_type

---

### PHASE 5: Writer Module (Part C)
**Priority:** HIGH  
**Estimated Changes:** ~600 lines across 3 files

#### 5.1 Tasks Page (`src/pages/Writer/Tasks.tsx`)
**Current:** 28,013 lines  
**Changes:**
- Update table columns:
  - Replace `entity_type` → `content_type`
  - Replace `cluster_role` → `content_structure`
  - Update status display (queued/completed)
- Update filters:
  - Add: content_type, content_structure
  - Remove: entity_type, cluster_role, sync_status
- Task detail: redirect to Content Manager after generation

#### 5.2 Content Page (`src/pages/Writer/Content.tsx`)
**Current:** 11,037 lines  
**Changes:**
- Update table columns:
  - Add: content_type, content_structure, source, taxonomy_terms
  - Remove: entity_type, cluster_role, sync_status
- Update filters:
  - Add: content_type, content_structure, source
  - Remove: deprecated filters
- Update status display (draft/published)

#### 5.3 Writer Dashboard (`src/pages/Writer/Dashboard.tsx`)
**Changes:**
- Update metrics to use new field names
- Remove deprecated status counts

---

### PHASE 6: Sites Module - Major Restructure (Part D)
**Priority:** CRITICAL - 18-point specification  
**Estimated Changes:** ~1000 lines across 4 files

#### 6.1 Sites List Page (`src/pages/Sites/List.tsx`)
**Current:** 36,680 lines  
**18-Point Changes:**
1. ✅ Grid view ONLY - remove table toggle
2. ✅ Collapsible Add Site form
3. ✅ Remove: Pages button, Sectors button, Blueprints button
4. ✅ Remove: Create Site (builder) button
5. ✅ Remove: Banner notifications
6. ✅ Remove: "Sites Configuration" text
7. ✅ Site card top-right: Active/inactive switch
8. ✅ Site card bottom: ONLY Dashboard, Content, Settings buttons

#### 6.2 Site Settings Page (`src/pages/Sites/Settings.tsx`)
**Current:** 37,735 lines  
**Changes:**
- Two-row grid of 4 cards: General, SEO Meta, Open Graph, Schema
- Move Sector/Industry selector below cards
- Remove deprecated integration fields

#### 6.3 Content Page (`src/pages/Sites/Content.tsx`)
**Current:** 11,424 lines  
**Changes:**
- Update to use new content fields
- Remove deprecated filters
- This becomes primary content management interface

#### 6.4 Remove/Clean Builder Folder
**Action:** Review `src/pages/Sites/Builder/` - may need deprecation

---

### PHASE 7: Create Cluster Detail Page (Part E - NEW)
**Priority:** MEDIUM  
**Estimated Changes:** ~500 lines - NEW FILE

#### 7.1 Create New Page (`src/pages/Planner/ClusterDetail.tsx`)
**Structure:**
- Route: `/clusters/:id`
- Tabs: Articles, Pages, Products, Taxonomy Pages
- Each tab shows:
  - Title (clickable → Content Manager)
  - content_type
  - content_structure
  - taxonomy_terms (as chips/tags)
  - status (draft/published)
  - source (IGNY8/WP)
  - Actions (edit, view)

#### 7.2 Update Routing
**File:** `src/App.tsx` or routing config
- Add route: `/clusters/:id` → ClusterDetail component

---

### PHASE 8: Content Manager Refactor (Part F - MOST CRITICAL)
**Priority:** CRITICAL  
**Estimated Changes:** ~800 lines across 2-3 files

#### 8.1 Content Table Component
**Location:** TBD (may be in Sites/Content.tsx or separate)

**Table Columns (New Structure):**
1. Title (clickable → edit)
2. Content Type
3. Content Structure
4. Cluster
5. Taxonomy Terms (chips)
6. Status (draft/published badge)
7. Source (IGNY8/WP badge)
8. URL (if published)
9. Word Count (computed frontend from content_html)
10. Images (if API supports)
11. Actions dropdown

**Filters:**
- cluster (dropdown)
- content_type (dropdown)
- content_structure (dropdown)
- taxonomy (multi-select)
- status (draft/published)
- source (igny8/wordpress)

**Row Actions:**
- Edit Content
- Publish to WordPress
- View in WordPress (if external_url)
- Assign taxonomy
- Assign cluster
- View images

**Bulk Actions:**
- Bulk publish
- Bulk assign cluster
- Bulk assign taxonomy

#### 8.2 Content Editor Page
**Create:** `src/pages/Sites/ContentEditor.tsx` or update existing

**Editable Fields:**
- title (text input)
- content_html (rich editor)
- cluster (dropdown)
- taxonomy_terms (multi-select)
- content_type (dropdown - backend choices)
- content_structure (dropdown - backend choices)

**Remove:**
- sync_status
- cluster_role
- All WP meta fields (handled by backend)

#### 8.3 Publish to WordPress
**Function:** Update publish handler
- Call: `POST /v1/writer/content/{id}/publish/`
- On success:
  - Update local state: status = 'published'
  - Update: external_id, external_url
  - Show success toast with WP URL

---

### PHASE 9: Integration Components
**Priority:** LOW-MEDIUM  
**Estimated Changes:** ~200 lines across 2 files

#### 9.1 WordPress Integration Card (`src/components/sites/WordPressIntegrationCard.tsx`)
**Changes:**
- Remove deprecated sync_status displays
- Update to show source tracking

#### 9.2 Site Integrations Section (`src/components/integration/SiteIntegrationsSection.tsx`)
**Changes:**
- Update integration status displays
- Remove deprecated fields

---

### PHASE 10: Linker & Optimizer Modules
**Priority:** LOW - Can be done separately  
**Estimated Changes:** ~400 lines across 4 files

#### 10.1 Linker Content List (`src/pages/Linker/ContentList.tsx`)
**Changes:**
- Update content display to use new fields
- Remove deprecated filters

#### 10.2 Optimizer Content Selector (`src/pages/Optimizer/ContentSelector.tsx`)
**Changes:**
- Update content query fields
- Remove entity_type references

#### 10.3 Optimizer Analysis Preview (`src/pages/Optimizer/AnalysisPreview.tsx`)
**Changes:**
- Update content field displays

---

### PHASE 11: Global UI Cleanup (Part G)
**Priority:** MEDIUM  
**Estimated Changes:** Distributed across all files

**Actions:**
- Search and remove all "Blog post" references
- Remove all sync_status badges/labels
- Remove cluster_role displays
- Remove context_type displays
- Ensure button consistency
- Ensure icon consistency
- Fix spacing and padding issues

---

### PHASE 12: Documentation (Part H)
**Priority:** LOW  
**Estimated Changes:** 1 new doc file

**Create:** `frontend/ARCHITECTURE.md`
**Content:**
- Final UI structure
- Page responsibilities
- New pipeline: Planner → Writer → Content Manager → WP Publish
- Dropdown field mappings
- Component flow diagrams

---

### PHASE 13: Changelog (Part I)
**Priority:** LOW  
**Estimated Changes:** 1 file update

**Update:** `CHANGELOG.md`
**Add Entry:**
```markdown
## [v1.0.0] - Stage 2 Frontend Refactor - 2025-11-25

### Changed
- Planner, Writer, Sites, Clusters, Content Manager UI fully updated
- Deprecated UI elements removed (cluster_role, sync_status, entity_type)
- Full alignment with Stage 1 backend
- Unified statuses: queued→completed (tasks), draft→published (content)
- Content types and structures from backend choices
- WordPress publish and import integration updated

### Added
- Cluster detail page (/clusters/:id)
- Enhanced Content Manager with full taxonomy support
- Source tracking (IGNY8/WordPress)
- Direct taxonomy term assignment

### Removed
- All deprecated field UI elements
- Legacy sync status displays
- Blog post type references
- Cluster role displays

### Documentation
- Frontend architecture documented
- Component flow diagrams added
```

---

## 📋 FILE CHANGE SUMMARY

### Files to Modify (17 core files)
1. ✏️ `src/services/api.ts` - API interfaces
2. ✏️ `src/services/integration.api.ts` - Integration types
3. ✏️ `src/config/pages/tasks.config.tsx` - Task table config
4. ✏️ `src/config/pages/content.config.tsx` - Content table config
5. ✏️ `src/config/pages/ideas.config.tsx` - Ideas config
6. ✏️ `src/store/plannerStore.ts` - Planner state
7. ✏️ `src/pages/Planner/Clusters.tsx` - Cluster list
8. ✏️ `src/pages/Planner/Ideas.tsx` - Ideas page
9. ✏️ `src/pages/Planner/Dashboard.tsx` - Planner dashboard
10. ✏️ `src/pages/Writer/Tasks.tsx` - Tasks page
11. ✏️ `src/pages/Writer/Content.tsx` - Writer content
12. ✏️ `src/pages/Writer/Dashboard.tsx` - Writer dashboard
13. ✏️ `src/pages/Sites/List.tsx` - Sites list (18-point fix)
14. ✏️ `src/pages/Sites/Settings.tsx` - Site settings
15. ✏️ `src/pages/Sites/Content.tsx` - Site content
16. ✏️ `src/components/sites/WordPressIntegrationCard.tsx`
17. ✏️ `src/components/integration/SiteIntegrationsSection.tsx`

### Files to Create (2 new files)
1. ✨ `src/pages/Planner/ClusterDetail.tsx` - New cluster detail page
2. ✨ `frontend/ARCHITECTURE.md` - Frontend documentation

### Files to Review for Cleanup (6 files)
1. 🔍 `src/pages/Linker/ContentList.tsx`
2. 🔍 `src/pages/Optimizer/ContentSelector.tsx`
3. 🔍 `src/pages/Optimizer/AnalysisPreview.tsx`
4. 🔍 `src/pages/Sites/DeploymentPanel.tsx`
5. 🔍 `src/pages/Sites/PostEditor.tsx`
6. 🔍 `src/pages/Sites/Builder/*` - Consider deprecation

---

## ⚠️ CRITICAL DEPENDENCIES

**Must Complete in Order:**
1. PHASE 1 (API) → All other phases depend on this
2. PHASE 2 (Config) → Required before UI updates
3. PHASE 3 (Stores) → Required before component updates
4. PHASES 4-10 → Can be done in parallel after 1-3
5. PHASES 11-13 → Final cleanup

**Backend Contract (DO NOT MODIFY):**
- Use EXACT backend field names in API calls
- Frontend labels can be prettier, but API payloads must match backend
- No new backend fields can be requested

---

## 🧪 TESTING STRATEGY

### After Each Phase:
1. **Type Check:** `npm run type-check` (if available)
2. **Build Check:** `npm run build`
3. **Manual Test:** Verify UI renders without errors

### Critical Test Paths:
1. **Task Creation Flow:** Planner → Create Task → View in Writer
2. **Content Generation:** Task → Generate → View in Content Manager
3. **WP Publish:** Content Manager → Publish → Verify external_url
4. **Cluster Detail:** Clusters → Click Name → View Detail Page
5. **Content Filter:** Content Manager → Filter by type, structure, source
6. **Bulk Actions:** Select Multiple → Bulk Publish

---

## 📊 ESTIMATED EFFORT

| Phase | Priority | Estimated Time | Lines Changed |
|-------|----------|----------------|---------------|
| 1. API & Types | CRITICAL | 2-3 hours | ~500 |
| 2. Config Files | HIGH | 1-2 hours | ~300 |
| 3. Stores | HIGH | 1 hour | ~100 |
| 4. Planner | MEDIUM | 2-3 hours | ~400 |
| 5. Writer | HIGH | 3-4 hours | ~600 |
| 6. Sites (18-pt) | CRITICAL | 4-5 hours | ~1000 |
| 7. Cluster Detail | MEDIUM | 2-3 hours | ~500 |
| 8. Content Manager | CRITICAL | 4-5 hours | ~800 |
| 9. Integration | LOW-MED | 1-2 hours | ~200 |
| 10. Linker/Optimizer | LOW | 2 hours | ~400 |
| 11. UI Cleanup | MEDIUM | 2-3 hours | distributed |
| 12-13. Docs | LOW | 1 hour | minimal |

**Total Estimated: 25-35 hours of focused development**

---

## 🚀 EXECUTION READINESS

**Status:** ✅ PLAN COMPLETE  
**Next Step:** Begin Phase 1 - API & Type Definitions  
**Blocker Check:** ✅ None - Backend is stable and deployed

**Ready to Execute:** YES

---

## 📝 NOTES

- All changes are frontend-only
- Backend is locked and stable
- Type safety will catch most issues early
- Test incrementally to avoid compound errors
- Keep git commits granular per phase

**End of Execution Plan**
