helix/docs/implementation-plan.md

# Implementation Plan

## Project Status Overview

Helix is at **version 0.1.0** — a functional MVP with core infrastructure complete, one fully implemented feature (Settings), one partially implemented feature (Posts), and several features in planning/stub state.

## Status Summary

| Feature | Status | Completion |
|---------|--------|------------|
| Core PHP Architecture | ✅ Implemented | 100% |
| Admin Redirect & Menu | ✅ Implemented | 100% |
| REST API (Settings) | ✅ Implemented | 100% |
| Settings Page | ✅ Implemented | 100% |
| Dashboard | ✅ Implemented | 80% |
| Posts Management | 🟡 Phase 1 of 5 | 25% |
| Component Library | ✅ Implemented | 70% |
| Build System | ✅ Implemented | 80% |
| Users Management | ❌ Stub | 5% |
| 2FA | ❌ Stub | 0% |
| Media Library | ❌ Not Started | 0% |
| Page Manager | ❌ Not Started | 0% |

## Priority Roadmap

### Phase A — Complete Current Features (2–3 weeks)

**Goal**: Finish what's already in progress before starting new features.

#### A1. Dashboard Polish
- [ ] Replace hardcoded trend percentages with computed deltas from previous period
- [ ] Fetch live WordPress news from the WordPress.org RSS feed
- [ ] Add error UI with retry button for failed data fetches
- [ ] Add periodic auto-refresh (60s polling)
- [ ] Replace all `wp-admin` links with Helix-native pages once available

#### A2. Posts — Phase 2 (Enhanced List)
- [ ] Wire up the "Add New Post" button to a creation form
- [ ] Implement bulk actions toolbar with select-all checkbox
- [ ] Add category and tag filter dropdowns (API already fetches them)
- [ ] Move date-range filtering from client-side to API query parameters
- [ ] Implement column sorting (click headers to sort by title, date, status)
- [ ] Add post thumbnails column

### Phase B — Missing Core Features (4–6 weeks)

**Goal**: Build features that exist as stubs.

#### B1. Posts — Phase 3 (Editor)
- [ ] Integrate a rich text editor (TinyMCE, Lexical, or TipTap)
- [ ] Build a full post creation/editing page within Helix (no wp-admin redirect)
- [ ] Add featured image selector with media library integration
- [ ] Category/tag assignment UI with autocomplete
- [ ] Content scheduling (future publish date)
- [ ] Draft auto-save

#### B2. Users Management
- [ ] User list with pagination, search, and role filtering
- [ ] Create/Edit user forms
- [ ] Delete user with content reassignment
- [ ] Bulk role changes
- [ ] Role & capability management

#### B3. Media Library
- [ ] Media grid/list view with pagination
- [ ] Drag-and-drop upload
- [ ] Media details panel (metadata, URLs, dimensions)
- [ ] Media search and filtering
- [ ] Bulk delete

### Phase C — Advanced Features (6–8 weeks)

**Goal**: Differentiate Helix with features beyond the default WordPress admin.

#### C1. Two-Factor Authentication
- [ ] PHP: TOTP library integration, secret generation, code validation
- [ ] PHP: REST endpoints for 2FA enable/disable/verify
- [ ] PHP: `wp_login` filter integration
- [ ] React: 2FA setup wizard with QR code
- [ ] Backup codes and recovery flow
- [ ] Rate limiting and brute-force protection

#### C2. Posts — Phase 4 (Collaboration)
- [ ] Editorial calendar view
- [ ] Review and approval workflow
- [ ] Editorial comments on drafts
- [ ] Team assignment and notifications

#### C3. Page Manager
- [ ] Page list view (similar to Posts list)
- [ ] Page hierarchy/tree view
- [ ] Page editor integration
- [ ] Page attributes (parent, template, order)

### Phase D — Polish & Performance (2–3 weeks)

**Goal**: Production readiness.

- [ ] Replace multi-mount-point architecture with proper client-side routing via `react-router-dom`
- [ ] Implement code splitting and lazy loading per page
- [ ] Add light/dark theme toggle with CSS custom properties
- [ ] WCAG 2.1 AA accessibility audit and fixes
- [ ] Keyboard navigation support
- [ ] Error boundaries on all pages
- [ ] Comprehensive test suite (unit + integration)
- [ ] Bundle size optimization (tree-shake MUI, remove unused deps)
- [ ] Virtual scrolling for lists with 100+ items
- [ ] Offline caching with service worker

## Architecture Improvements

These are cross-cutting changes that affect multiple features:

| Improvement | Priority | Effort |
|-------------|----------|--------|
| True SPA routing with `react-router-dom` | High | Medium |
| Code splitting & lazy loading | High | Low |
| Centralized API client (replace inline `fetch` calls) | Medium | Medium |
| Global error boundary | Medium | Low |
| TypeScript migration | Low | High |
| CSS Modules or Tailwind | Low | High |
| End-to-end tests (Playwright/Cypress) | Low | Medium |

## Success Criteria

- **Phase A**: Dashboard is production-quality; Posts has bulk operations and creation
- **Phase B**: Users can manage users, media, and create/edit posts without ever leaving Helix
- **Phase C**: 2FA is production-ready; editorial workflow is functional
- **Phase D**: Helix passes accessibility audit; bundle size is under 200KB gzipped; test coverage > 80%

## Risk Factors

1. **WordPress Core Updates**: The `wp-admin` redirect hijack relies on specific hooks and globals that could change in future WP versions
2. **REST API Rate Limits**: No caching layer exists — repeated API calls could trigger rate limiting on some hosts
3. **MUI Bundle Size**: Material UI v7 adds significant weight; may need to swap for a lighter alternative or tree-shake aggressively
4. **Plugin Conflicts**: Other plugins that modify the admin menu or REST API could conflict with Helix's aggressive menu removal and redirect
5. **Auth Token Expiry**: REST API nonces expire after 24 hours — long-lived admin sessions may need a token refresh mechanism